O que é
Um formulário é uma tela de perguntas que abre por cima da conversa, dentro do próprio WhatsApp, quando o cliente toca no botão da sua mensagem. Ele preenche ali, toca em Enviar, e a resposta volta pra você já separada campo a campo. Não é link, não é site, não é bot perguntando uma coisa por vez. É um recurso nativo do WhatsApp (a Meta chama de Flow) que a Arara cria, publica e lê pra você. O formulário da Arara é uma tela só e estática: de 1 a 10 perguntas, todas visíveis de uma vez, tudo declarado na criação. Não tem etapas, não tem pergunta que aparece dependendo da resposta anterior e não tem nada vindo do seu servidor enquanto o cliente preenche. Os tipos de campo são nove — texto, texto longo, e-mail, telefone, número, escolha única, múltipla escolha, data e aceite. Não há upload de arquivo, imagem nem link dentro do formulário.Por que usar
- Ninguém sai da conversa. Sem link externo, sem página que demora a carregar, sem “abrir no navegador”.
- A resposta chega estruturada. Você lê
fields.email, não uma frase pra interpretar. - A chave do campo é sua e não muda. O que você leu uma vez vale pra sempre.
- Serve pra cadastro, pesquisa, NPS, agendamento, opt-in. De 1 a 10 perguntas por formulário.
Disponível do plano Voo pra cima. Abaixo disso, criar ou enviar formulário responde
403 PLAN_FEATURE_LOCKED.Como aparece no WhatsApp
À esquerda, a mensagem com o botão. À direita, o formulário depois que o cliente toca nele. Quando o cliente toca em Enviar, a conversa recebe uma mensagem de resposta e o seu webhook recebe o eventomessage.flow_reply com os campos preenchidos.
Como faço
1
Crie o formulário no painel
Na aba Formulários, em Nova, você escreve as perguntas, escolhe o tipo de cada uma e confere a prévia. A Arara monta o Flow JSON, sobe pra Meta e publica.Vale gastar um minuto na prévia: a criação já publica, e publicado não se edita.Depois de criado, o formulário aparece na lista com o id — é esse id que você usa no envio pela API e o que o botão de template aponta.Os limites de quem preenche o construtor: de 1 a 10 perguntas, título até 30 caracteres, introdução até 300, de 2 a 20 opções em escolha única e múltipla, com até 30 caracteres cada. Pergunta que não couber no rótulo do WhatsApp aparece como texto acima do campo, com um rótulo curto no campo — você não precisa encurtar.
2
Mande num template (ou direto na conversa)
Com template, use o botão Depois de aprovado, envie como qualquer outro template.Sem template, com a janela de 24h aberta, o formulário vai como mensagem interativa. Não passa por aprovação da Meta, então é o jeito mais rápido de testar: crie e mande pra você mesmo.
FLOW com o id do formulário. Um botão de formulário por template, podendo conviver com outros botões.body é obrigatório. buttonText é opcional: padrão Responder, até 20 caracteres. Fora da janela de 24h a API recusa, e aí o caminho é o template. No dashboard, é o link Formulário ao lado de Template, na caixa de Conversas.POST /v1/messages e POST /v1/templates aceitam API key. O flowId vem da lista de formulários no painel.3
Leia a resposta
Cada envio chega no seu webhook como Os valores já vêm legíveis: a opção escolhida chega com o texto da opção, múltipla escolha separada por vírgula, aceite como
message.flow_reply. Leia de data.fields:Sim ou Não, data como dd/MM/yyyy. Pergunta opcional sem resposta chega como string vazia, nunca ausente.source_message_id é o id da mensagem da Arara que levou o botão. Use pra ligar a resposta ao envio, ao contato e à campanha.A conversa não mostra o que foi respondido. No inbox entra só uma mensagem do cliente com o texto “Formulário respondido” — as respostas em si só existem em dois lugares: no webhook e no detalhe do formulário, numa lista de 50 por página em que você expande cada envio.O que pode dar errado
Publicar é automático, e publicado não se edita
POST /v1/flows já publica. Não existe rascunho pra revisar antes, nem pré-visualização no WhatsApp de formulário não publicado: quando a chamada volta 201, ele está no ar. Confira as perguntas, as opções e as chaves antes de criar — é o que mais gera retrabalho aqui.
A Meta não deixa mudar um formulário que já está no ar. Não existe endpoint de edição na Arara porque não existe do outro lado. Pra mudar uma pergunta, crie outro formulário e desative o antigo com POST /v1/flows/{id}/deprecate. Desativar mantém as respostas já recebidas e impede que o botão abra pra quem recebeu a mensagem antes.
DELETE /v1/flows/{id} só funciona em formulário que nunca foi publicado (DRAFT); publicado responde 409 FLOW_NOT_DRAFT.
Formulário vive por número, não por conta
O formulário nasce preso ao número (à conta WhatsApp) em que foi criado. É a mesma armadilha do template:- Se o botão de um template apontar pra um formulário criado em outro número, o envio é recusado com a frase “foi criado em outro número. Recrie o formulário neste número”.
- Se aquele número sair da sua conta, as ações sobre esse formulário respondem
409 FLOW_NUMBER_GONE. - Trocou de número ou de conexão? Recrie o formulário, não adianta reapontar.
409 FLOW_NAME_TAKEN quando repete.
E não existe atalho: template tem “Recriar neste número”, formulário não tem. Não dá pra duplicar nem reaproveitar. Trocou de número, você reescreve as perguntas à mão. Some isso a “publicado não se edita” e a conclusão prática é uma só: confira na prévia antes de publicar.
A resposta casa pelo token do envio
O WhatsApp não diz qual formulário foi respondido. Ele devolve só oflow_token que saiu no envio — e a Arara manda ali o id do formulário mais o id da mensagem. É assim que flow_id e source_message_id aparecem no webhook.
Consequências práticas:
- O token vem do aparelho do cliente, então a Arara sempre confere se aquele formulário é da organização dona do número que recebeu. Token que não casa é ignorado, sem evento.
- Resposta que chega duas vezes (o WhatsApp reentrega) é gravada uma vez só, pelo id da mensagem do provedor.
- Se a gravação da resposta falhar, a mensagem “Formulário respondido” ainda entra na conversa — só que sem resposta guardada e sem evento. Conversa com essa mensagem e nenhum envio na lista do formulário é exatamente esse caso.
A publicação falha sem o formulário sumir
Criar são três chamadas na Meta. Se o JSON for recusado, nada é gravado e você recebe400 INVALID_FLOW com o motivo. Se só a publicação falhar, o formulário fica em rascunho com o erro da Meta anotado. Ele aparece assim na lista e você manda publicar de novo pelo painel, sem reescrever as perguntas.
Chave de campo é decisão de uma vez só
Semkey, a chave nasce do texto da pergunta (Seu melhor e-mail vira seu_melhor_e_mail). Como o formulário publicado não se edita, essa chave vai viver com você. Defina a sua sempre que o handler do outro lado já existir.
Referência
Limites de cada campo
Endpoints
Estes caminhos respondem à sessão do painel. A API key ainda não os alcança — com
ara_live_... a resposta é 403.{ data, pagination }.