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
- Criar.
POST /whatsapp/formscomname(até 120 caracteres, único no workspace) e, se quiser,starter, um modelo pronto:lead_capture,appointment,nps,sign_up,contact_us,quoteoudocuments. A resposta traz o rascunho emdraft. - Editar o rascunho.
PUT /whatsapp/forms/{formId}/draftcom odocumente obaseVersionId(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 emdraft.problems. - Conferir.
POST /whatsapp/forms/checkconfere um documento sem salvar.GET /whatsapp/forms/{formId}/compiledmostra o Flow JSON que o rascunho gera, ePOST /whatsapp/forms/{formId}/previewgera a pré-visualização oficial da Meta, com um link que vale até 30 dias. - Publicar em uma ou mais contas do WhatsApp.
- Enviar numa conversa, num modelo de mensagem com botão de formulário ou por um fluxo.
- 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.
| Propriedade | Regra |
|---|---|
schema | Sempre 1. |
categories | Pelo menos uma categoria da Meta: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY ou OTHER. |
screens | Pelo menos uma tela. A primeira é a que abre. O formulário precisa ter pelo menos um campo (problema no_input). |
Telas
| Propriedade | Regra |
|---|---|
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. |
title | Obrigatório. |
blocks | Os blocos da tela, na ordem em que aparecem. |
submitLabel | O texto do botão da tela, obrigatório. |
route | Para onde a tela leva. Sem route, a tela é a última e o botão envia o formulário. |
Rotas
| Propriedade | Regra |
|---|---|
route.next | A próxima tela. Com branchOn, é o destino de quem escolheu uma opção sem desvio. |
route.branchOn | A chave de um campo de escolha única obrigatório da própria tela. |
route.branches | Uma 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 origem | value |
|---|---|
| Escolha única | O 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" }code | Significado |
|---|---|
required | Falta um valor obrigatório. |
too_long, too_many, too_few | Passou de um limite; o limite vem em limit. |
duplicate | Chave, opção ou desvio repetido. |
invalid | Valor fora do formato. |
not_allowed | A propriedade não vale para esse tipo. |
unknown_target | Aponta para uma tela, campo, opção ou imagem que não existe. |
backward_route | Rota para trás. |
unreachable | Tela que nenhuma rota alcança. |
no_input | O formulário não tem nenhum campo. |
binding_unknown_field, binding_incompatible, binding_sensitive, binding_duplicate, binding_options_mismatch | Problemas de gravação no lead. |
meta_validation | A 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:
target | Grava em |
|---|---|
name | Nome do lead. |
email | E-mail do lead. |
birth_date | Data de nascimento. |
address.zip, address.city, address.state | CEP, cidade e estado do endereço. |
consent_whatsapp | Consentimento de receber mensagens no WhatsApp. |
custom_field | O 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ção | Significado |
|---|---|
creating, draft | Em criação ou ainda em rascunho na Meta. |
published | Publicado e liberado para envio. |
throttled | Liberado com limite de envios pela Meta. Ainda pode ser enviado. |
blocked | Bloqueado pela Meta. Não pode ser enviado. |
deprecated | Descontinuado. |
failed | A 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 copy | Regra |
|---|---|
body | Obrigatório, até 1.024 caracteres. |
cta | O texto do botão, obrigatório, até 30 caracteres, sem emoji. |
header, footer | Opcionais, 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 resposta | Significado |
|---|---|
match | token 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.values | Uma resposta por chave de campo, com kind e o valor no campo do tipo. |
answers.unknown | Chaves recebidas que o formulário não tem. |
answers.problems | Valores que não puderam ser lidos. |
applyStatus | applied, partial (algo não foi gravado; veja report), pending ou skipped (resposta não ligada a um envio). |
report | O 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ódigo | Quando |
|---|---|
400 whatsapp_form_name_required, whatsapp_form_name_too_long, whatsapp_form_description_too_long, whatsapp_form_starter_unknown | Nome, descrição ou modelo pronto inválidos. |
400 whatsapp_form_copy_invalid | Textos de envio inválidos. |
400 whatsapp_form_no_account_chosen | Publicação sem nenhuma conta. |
403 whatsapp_form_not_owner | Só o workspace dono do número usa formulários nele. |
404 whatsapp_form_not_found | Formulário inexistente. |
409 whatsapp_form_name_taken | Outro formulário tem o mesmo nome. |
409 whatsapp_form_stale_draft | O rascunho mudou depois de aberto. |
409 whatsapp_form_archived | O formulário está arquivado. |
409 whatsapp_form_no_account, whatsapp_form_provider_unsupported | Sem 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_sendable | O formulário não pode ser enviado nessa conversa agora. |
422 whatsapp_form_invalid | O documento tem problemas. |
Rotas
| Rota | O que faz |
|---|---|
GET /whatsapp/forms/options | Tipos, limites, destinos de gravação e modelos prontos. |
POST /whatsapp/forms/check | Confere um documento sem salvar. |
GET /whatsapp/forms | Lista os formulários. |
POST /whatsapp/forms | Cria 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}/draft | Salva o rascunho. |
GET /whatsapp/forms/{formId}/compiled | O Flow JSON do rascunho. |
GET /whatsapp/forms/{formId}/versions | As versões salvas. |
POST /whatsapp/forms/{formId}/duplicate | Duplica o formulário. |
POST /whatsapp/forms/{formId}/preview | Pré-visualização da Meta. |
GET /whatsapp/forms/publish-targets | Contas onde publicar. |
POST /whatsapp/forms/{formId}/publish | Publica nas contas escolhidas. |
POST /whatsapp/forms/{formId}/publications/{metaWabaId}/deprecate | Descontinua numa conta. |
POST /whatsapp/forms/{formId}/archive | Descontinua em todas as contas e arquiva. |
GET /whatsapp/forms/sendable | Formulários que um número pode enviar. |
POST /conversations/whatsapp/{entryId}/forms | Envia numa conversa. |
GET /whatsapp/forms/{formId}/sends | Envios. |
GET /whatsapp/forms/{formId}/responses | Respostas. |
GET e DELETE /whatsapp/forms/responses/{responseId} | Lê ou exclui uma resposta. |
GET /whatsapp/forms/{formId}/stats | Desempenho. |
GET /whatsapp/forms/{formId}/fields/{fieldKey}/distribution | Distribuição de um campo de escolha. |
GET /whatsapp/forms/{formId}/automations | Fluxos ligados ao formulário. |
POST /whatsapp/forms/{formId}/automations | Cria um fluxo desligado, já ligado ao formulário. |