Guia de formulários

Como montar o documento de um formulário do WhatsApp (telas, rotas, blocos e condições), publicar em cada conta, enviar numa conversa e ler as respostas.

Um formulário é um WhatsApp Flow: telas que a pessoa preenche sem sair do WhatsApp. Você descreve o formulário num documento da Vozko, mais simples que o Flow JSON da Meta, e a plataforma confere o documento, gera o Flow JSON, publica na Meta e liga cada resposta ao lead e à conversa.

Cada bloco de exibição e cada tipo de campo, com os limites e as propriedades que aceita, estão em Campos e blocos de formulário. As rotas estão no grupo WhatsApp: formulários da Referência da API; comece por GET /whatsapp/forms/options, que devolve os tipos, os limites e os modelos prontos que o construtor usa.

Ciclo de vida

  1. Criar. POST /whatsapp/forms com name (até 120 caracteres, único no workspace) e, se quiser, starter, um modelo pronto: lead_capture, appointment, nps, sign_up, contact_us, quote ou documents. A resposta traz o rascunho em draft.
  2. Editar o rascunho. PUT /whatsapp/forms/{formId}/draft com o document e o baseVersionId (o id do rascunho que você abriu). Cada salvamento cria uma versão; um documento igual ao atual não cria. Problemas nunca impedem salvar: eles voltam em draft.problems.
  3. Conferir. POST /whatsapp/forms/check confere um documento sem salvar. GET /whatsapp/forms/{formId}/compiled mostra o Flow JSON que o rascunho gera, e POST /whatsapp/forms/{formId}/preview gera a pré-visualização oficial da Meta, com um link que vale até 30 dias.
  4. Publicar em uma ou mais contas do WhatsApp.
  5. Enviar numa conversa, num modelo de mensagem com botão de formulário ou por um fluxo.
  6. Ler as respostas e o desempenho.

Se outra pessoa salvou o rascunho depois que você o abriu, o salvamento responde 409 whatsapp_form_stale_draft e nada se perde: leia o rascunho de novo e reaplique a mudança.

O documento

{
  "schema": 1,
  "categories": ["LEAD_GENERATION"],
  "screens": [
    {
      "key": "s_contato",
      "title": "Seus dados",
      "blocks": [
        { "key": "b_intro", "display": { "kind": "paragraph", "text": "Responda em menos de um minuto." } },
        { "key": "b_nome", "field": { "key": "nome", "kind": "short_text", "label": "Nome", "required": true, "sensitive": false, "binding": { "target": "name" } } },
        { "key": "b_interesse", "field": { "key": "interesse", "kind": "single_choice_radio", "label": "O que você procura?", "required": true, "sensitive": false, "options": [
          { "id": "compra", "title": "Comprar" },
          { "id": "suporte", "title": "Suporte" }
        ] } },
        { "key": "b_pedido", "field": { "key": "pedido", "kind": "short_text", "label": "Número do pedido", "required": false, "sensitive": false }, "visibleIf": { "fieldKey": "interesse", "value": "suporte" } }
      ],
      "route": { "next": "s_fim", "branchOn": "interesse", "branches": [ { "optionId": "compra", "next": "s_compra" } ] },
      "submitLabel": "Continuar"
    },
    {
      "key": "s_compra",
      "title": "Preferências",
      "blocks": [
        { "key": "b_orcamento", "field": { "key": "orcamento", "kind": "single_choice_dropdown", "label": "Orçamento", "required": true, "sensitive": false, "options": [
          { "id": "ate_mil", "title": "Até R$ 1.000" },
          { "id": "acima_mil", "title": "Acima de R$ 1.000" }
        ] } }
      ],
      "route": { "next": "s_fim" },
      "submitLabel": "Continuar"
    },
    {
      "key": "s_fim",
      "title": "Quase lá",
      "blocks": [
        { "key": "b_aceite", "field": { "key": "aceite", "kind": "opt_in", "label": "Aceito receber mensagens no WhatsApp", "required": false, "sensitive": false, "termsUrl": "https://exemplo.com.br/privacidade", "binding": { "target": "consent_whatsapp" } } }
      ],
      "submitLabel": "Enviar"
    }
  ]
}

Nesse exemplo, quem escolhe "Comprar" vai para a tela s_compra e depois para s_fim; quem escolhe "Suporte" vê o campo do número do pedido e vai direto para s_fim.

PropriedadeRegra
schemaSempre 1.
categoriesPelo menos uma categoria da Meta: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY ou OTHER.
screensPelo menos uma tela. A primeira é a que abre. O formulário precisa ter pelo menos um campo (problema no_input).

Telas

PropriedadeRegra
keyÚnica no documento. Letra minúscula seguida de letras minúsculas, números ou _, até 40 caracteres. A mesma regra vale para as chaves de bloco, de campo e de opção.
titleObrigatório.
blocksOs blocos da tela, na ordem em que aparecem.
submitLabelO texto do botão da tela, obrigatório.
routePara onde a tela leva. Sem route, a tela é a última e o botão envia o formulário.

Rotas

PropriedadeRegra
route.nextA próxima tela. Com branchOn, é o destino de quem escolheu uma opção sem desvio.
route.branchOnA chave de um campo de escolha única obrigatório da própria tela.
route.branchesUma lista de optionId e next: quem escolhe a opção vai para next. Cada opção aparece uma vez.

As rotas só andam para a frente: um destino que vem antes da tela atual, ou a própria tela, volta com o problema backward_route. Toda tela precisa ser alcançável a partir da primeira (problema unreachable).

Blocos

Cada bloco tem key e exatamente um entre display (um texto, imagem ou link) e field (uma pergunta). Um campo pode trazer question, um texto mostrado logo acima dele.

binding grava a resposta do campo no lead quando o formulário é respondido; veja Gravar respostas no lead.

Condições de exibição

visibleIf mostra o bloco só quando a resposta de um campo anterior (numa tela anterior ou acima, na mesma tela) tem um valor:

Campo de origemvalue
Escolha únicaO id de uma opção do campo.
Aceite (opt_in)true ou false.

negate: true inverte a condição. Outros tipos de campo não decidem condições.

Problemas

Cada problema aponta onde corrigir:

{ "screen": "s_compra", "property": "route.next", "code": "backward_route" }
codeSignificado
requiredFalta um valor obrigatório.
too_long, too_many, too_fewPassou de um limite; o limite vem em limit.
duplicateChave, opção ou desvio repetido.
invalidValor fora do formato.
not_allowedA propriedade não vale para esse tipo.
unknown_targetAponta para uma tela, campo, opção ou imagem que não existe.
backward_routeRota para trás.
unreachableTela que nenhuma rota alcança.
no_inputO formulário não tem nenhum campo.
binding_unknown_field, binding_incompatible, binding_sensitive, binding_duplicate, binding_options_mismatchProblemas de gravação no lead.
meta_validationA Meta recusou o Flow JSON ao publicar.

Publicar ou pré-visualizar um rascunho com problemas responde 422 whatsapp_form_invalid, com os problemas, e nada vai para a Meta.

Gravar respostas no lead

binding.target diz onde a resposta vai:

targetGrava em
nameNome do lead.
emailE-mail do lead.
birth_dateData de nascimento.
address.zip, address.city, address.stateCEP, cidade e estado do endereço.
consent_whatsappConsentimento de receber mensagens no WhatsApp.
custom_fieldO campo personalizado do lead indicado em customFieldKey.

Cada destino aceita só alguns tipos de campo (veja a gravação de cada tipo em Campos e blocos de formulário). Um campo sensível, um campo de foto ou documento e um campo personalizado sensível não podem ser gravados. Num campo personalizado de seleção, cada opção do formulário precisa ter o title igual a uma opção do campo. Dois campos não gravam no mesmo destino. GET /whatsapp/forms/options lista os destinos e os campos personalizados que cada tipo aceita.

Publicar

GET /whatsapp/forms/publish-targets lista as contas do WhatsApp em que o workspace é dono de um número oficial conectado, com supported (o provedor do número aceita formulários) e businessVerified (a empresa da conta está verificada na Meta, o que a Meta costuma exigir para publicar).

POST /whatsapp/forms/{formId}/publish publica o rascunho nas contas de metaWabaIds. A resposta traz o resultado de cada conta em outcomes; uma conta com problema não impede as outras. Uma conta que já tem o formulário recebe a nova versão no mesmo formulário da Meta, então os modelos de mensagem que apontam para ele continuam funcionando.

Status da publicaçãoSignificado
creating, draftEm criação ou ainda em rascunho na Meta.
publishedPublicado e liberado para envio.
throttledLiberado com limite de envios pela Meta. Ainda pode ser enviado.
blockedBloqueado pela Meta. Não pode ser enviado.
deprecatedDescontinuado.
failedA publicação falhou; o motivo vem em lastError ou problems.

POST /whatsapp/forms/{formId}/publications/{metaWabaId}/deprecate descontinua o formulário numa conta. A Meta não permite reverter: publicar de novo cria outro formulário nessa conta. POST /whatsapp/forms/{formId}/archive descontinua em todas as contas e arquiva; se a Meta não confirmar em alguma conta, nada é arquivado.

Enviar numa conversa

Com a janela de 24 horas aberta, POST /conversations/whatsapp/{entryId}/forms envia o formulário numa conversa do WhatsApp oficial:

{
  "formId": "0f8c2d1e-5b6a-4c3d-9e8f-7a6b5c4d3e2f",
  "copy": {
    "header": "Pesquisa rápida",
    "body": "Responda nossa pesquisa rápida.",
    "footer": "Leva menos de um minuto",
    "cta": "Responder"
  }
}
Campo de copyRegra
bodyObrigatório, até 1.024 caracteres.
ctaO texto do botão, obrigatório, até 30 caracteres, sem emoji.
header, footerOpcionais, até 60 caracteres cada.

O formulário precisa estar publicado e liberado na conta do número da conversa (409 whatsapp_form_not_published ou 409 whatsapp_form_not_sendable). Com a janela fechada, a resposta é 409 whatsapp_form_outside_window: envie um modelo de mensagem com botão de formulário (veja Modelos e botões). GET /whatsapp/forms/sendable lista os formulários que um número pode enviar, com o metaFlowId e a firstScreen que o botão do modelo usa.

Um fluxo também envia formulários, pelo nó "Enviar formulário", e pode começar quando um formulário é respondido; veja o Catálogo de nós.

Respostas

Cada envio leva um token próprio. Quando a resposta chega, a plataforma a liga ao envio pelo token ou pela mensagem respondida, conferindo o número e o contato. Uma resposta ligada a um envio grava os campos com binding no lead, guarda as fotos e os documentos, retoma o fluxo que esperava a resposta e dispara as automações de formulário respondido.

Campo da respostaSignificado
matchtoken ou context quando a resposta foi ligada a um envio; unmatched_no_token, unmatched_unknown_token ou unmatched_sender quando não foi (por exemplo, um formulário enviado pelo WhatsApp Manager).
answers.valuesUma resposta por chave de campo, com kind e o valor no campo do tipo.
answers.unknownChaves recebidas que o formulário não tem.
answers.problemsValores que não puderam ser lidos.
applyStatusapplied, partial (algo não foi gravado; veja report), pending ou skipped (resposta não ligada a um envio).
reportO que foi gravado no lead (changed), o que conflitou ou foi recusado, o consentimento e os arquivos.

GET /whatsapp/forms/{formId}/responses lista as respostas, da mais recente para a mais antiga, só das conversas que quem consulta alcança, com filtros de período, origem, número, versão, campanha e match, paginadas por cursor (after). Sem a permissão whatsapp_form_responses:read_sensitive, respostas sensíveis, fotos e documentos aparecem mascarados. GET /whatsapp/forms/responses/{responseId} mostra uma resposta com a versão preenchida, e revealed diz se as respostas sensíveis vieram abertas.

Desempenho

GET /whatsapp/forms/{formId}/stats traz os envios por status, entregues, lidos, respostas, o tempo mediano até a resposta, por origem e por dia. GET /whatsapp/forms/{formId}/fields/{fieldKey}/distribution conta quantas respostas escolheram cada opção de um campo de escolha. GET /whatsapp/forms/{formId}/sends lista os envios, com a origem, o status e o motivo de falha.

Erros

Status e códigoQuando
400 whatsapp_form_name_required, whatsapp_form_name_too_long, whatsapp_form_description_too_long, whatsapp_form_starter_unknownNome, descrição ou modelo pronto inválidos.
400 whatsapp_form_copy_invalidTextos de envio inválidos.
400 whatsapp_form_no_account_chosenPublicação sem nenhuma conta.
403 whatsapp_form_not_ownerSó o workspace dono do número usa formulários nele.
404 whatsapp_form_not_foundFormulário inexistente.
409 whatsapp_form_name_takenOutro formulário tem o mesmo nome.
409 whatsapp_form_stale_draftO rascunho mudou depois de aberto.
409 whatsapp_form_archivedO formulário está arquivado.
409 whatsapp_form_no_account, whatsapp_form_provider_unsupportedSem conta elegível, ou o provedor do número não aceita formulários.
409 whatsapp_form_outside_window, whatsapp_form_not_published, whatsapp_form_not_sendableO formulário não pode ser enviado nessa conversa agora.
422 whatsapp_form_invalidO documento tem problemas.

Rotas

RotaO que faz
GET /whatsapp/forms/optionsTipos, limites, destinos de gravação e modelos prontos.
POST /whatsapp/forms/checkConfere um documento sem salvar.
GET /whatsapp/formsLista os formulários.
POST /whatsapp/formsCria um formulário.
GET /whatsapp/forms/{formId}O formulário, o rascunho, a versão publicada e as publicações.
PATCH /whatsapp/forms/{formId}Troca nome e descrição.
PUT /whatsapp/forms/{formId}/draftSalva o rascunho.
GET /whatsapp/forms/{formId}/compiledO Flow JSON do rascunho.
GET /whatsapp/forms/{formId}/versionsAs versões salvas.
POST /whatsapp/forms/{formId}/duplicateDuplica o formulário.
POST /whatsapp/forms/{formId}/previewPré-visualização da Meta.
GET /whatsapp/forms/publish-targetsContas onde publicar.
POST /whatsapp/forms/{formId}/publishPublica nas contas escolhidas.
POST /whatsapp/forms/{formId}/publications/{metaWabaId}/deprecateDescontinua numa conta.
POST /whatsapp/forms/{formId}/archiveDescontinua em todas as contas e arquiva.
GET /whatsapp/forms/sendableFormulários que um número pode enviar.
POST /conversations/whatsapp/{entryId}/formsEnvia numa conversa.
GET /whatsapp/forms/{formId}/sendsEnvios.
GET /whatsapp/forms/{formId}/responsesRespostas.
GET e DELETE /whatsapp/forms/responses/{responseId}Lê ou exclui uma resposta.
GET /whatsapp/forms/{formId}/statsDesempenho.
GET /whatsapp/forms/{formId}/fields/{fieldKey}/distributionDistribuição de um campo de escolha.
GET /whatsapp/forms/{formId}/automationsFluxos ligados ao formulário.
POST /whatsapp/forms/{formId}/automationsCria um fluxo desligado, já ligado ao formulário.