Enviar Formulário

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

Descrição

Envia uma mensagem com um botão que abre um Native Flow do WhatsApp, um formulário nativo que coleta dados estruturados (nome, telefone, e-mail, CPF/CNPJ, endereço) sem sair da conversa. Suporta dois fluxos prontos: contact_details (Dados do cliente) e registration_offer (Oferta de Cadastro), além de uma escape hatch via buttonParamsJSON para flows totalmente customizados. Ideal para captação de leads, cadastros e ofertas com confirmação rápida.

Compatibilidade de cliente: Native Flows ainda não são suportados no WhatsApp Web/Desktop. O botão do formulário só será renderizado para destinatários nos apps oficiais de Android e iOS, em outros clientes a mensagem aparecerá sem o botão interativo.

Exemplos

Oferta de cadastro (registration_offer)

Envia uma oferta com título e descrição. O botão abre o Flow padrão de cadastro com os campos visíveis configuráveis.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":           "5511999999999",
    "message":          "Garanta sua vaga no curso com 50% off!",
    "formType":         "registration_offer",
    "buttonLabel":      "Quero garantir",
    "offerName":        "Curso de Go - Turma Maio",
    "offerDescription": "Acesso vitalício + certificado + suporte 30 dias"
  }'

Captura de dados de contato (contact_details)

Usa o flow oficial contact_details do WhatsApp. Esconda campos que você não quer pedir via flags *Visible. Aqui pedimos só nome, telefone e e-mail.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":                 "5511999999999",
    "message":                "Para finalizar seu atendimento, complete seus dados:",
    "formType":               "contact_details",
    "buttonLabel":            "Preencher dados",
    "fullNameVisible":        true,
    "phoneNumberVisible":     true,
    "emailVisible":           true,
    "cpfOrCnpjVisible":       false,
    "deliveryAddressVisible": false
  }'

Flow customizado via `buttonParamsJSON`

Escape hatch para flows próprios (criados no WhatsApp Business Manager). Quando buttonParamsJSON é fornecido, o servidor ignora todos os outros campos relacionados ao flow (formType, flowId, visibilidades, offerName, etc.) e usa o JSON literal como params do botão Native Flow.

Criar Flows

Acesse o WhatsApp Business Manager para criar e gerenciar seus Flows customizados (obtenha o flow_id aqui).

Playground de Flows

Teste e prototipe schemas de Flow no playground oficial da Meta antes de publicar em produção.

curl -X POST "https://ryzeapi.cloud/api/message/form/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":           "5511999999999",
    "message":          "Responda à pesquisa rápida e ganhe 10% off",
    "buttonLabel":      "Responder pesquisa",
    "buttonParamsJSON": "{\"flow_message_version\":\"3\",\"flow_token\":\"meu-token-123\",\"flow_id\":\"123456789012345\",\"flow_cta\":\"Responder pesquisa\",\"flow_action\":\"navigate\",\"flow_action_payload\":{\"screen\":\"WELCOME\"}}"
  }'

Resposta de sucesso

O messageType retornado é interactive (formulário é uma variação de mensagem interativa Native Flow), e o content ecoa o message enviado. Guarde o messageId (e o flowToken, gerado automaticamente quando você não envia) para correlacionar com a resposta do flow no webhook.

200 OK

{
  "success": true,
  "message": "Form message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "interactive",
    "content":     "Garanta sua vaga no curso com 50% off!",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

Quando o usuário preenche e envia o formulário, o WhatsApp envia uma mensagem do tipo interactive_response carregando o flow_token (UUID que você informou ou o gerado automaticamente) e o JSON com as respostas. Capture via webhook/websocket para correlacionar com o envio.

Parâmetros de rota

instance

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

token

string

obrigatório

TokenAccount ou TokenInstance.

Content-Type

string

obrigatório

application/json

Request body

number

string

obrigatório

Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us).

message

string

obrigatório

Texto exibido no balão da mensagem, acima do botão que abre o Flow.

formType

string

padrão:"registration_offer"

Tipo de formulário pré-configurado: "contact_details" (Dados do cliente) ou "registration_offer" (Oferta de Cadastro). Ignorado se buttonParamsJSON for fornecido.

buttonLabel

string

padrão:"Adicionar informações"

Texto exibido no botão que abre o Flow (flow_cta).

flowToken

string

Token para correlacionar a resposta do formulário com o envio. Quando omitido, o servidor gera um UUID automaticamente. Você pode usar esse token para amarrar com um lead/oportunidade no seu CRM.

flowId

string

ID do Flow no WhatsApp Business. Padrões por formType:

contact_details → 1889354358373616
registration_offer → 892701196712475

Sobrescreva apenas se for usar um Flow customizado pelo nome (sem usar buttonParamsJSON).

flowMessageVersion

string

padrão:"4"

Versão do flow_message_version enviada para o WhatsApp.

messageVersion

int

padrão:"3"

Versão do message_version do payload Native Flow.

buttonParamsJSON

string

Escape hatch para flows totalmente customizados. Quando fornecido, o servidor envia esse JSON literal como params do botão Native Flow e ignora formType, flowId, flowToken, flowMessageVersion, messageVersion, todas as flags *Visible, offerName e offerDescription. Útil para integrar com flows que você criou no WhatsApp Business Manager com schemas específicos.

fullNameVisible

boolean

padrão:"true"

Exibe o campo “Nome completo” no formulário. Ignorado se buttonParamsJSON for fornecido.

phoneNumberVisible

boolean

padrão:"true"

Exibe o campo “Número de telefone”.

emailVisible

boolean

padrão:"true"

Exibe o campo “E-mail”.

cpfOrCnpjVisible

boolean

padrão:"true"

Exibe o campo “CPF/CNPJ”.

deliveryAddressVisible

boolean

padrão:"true"

Exibe o campo “Endereço de entrega”.

offerName

string

Título da oferta exibido dentro do Flow. Usado quando formType=registration_offer.

offerDescription

string

Descrição da oferta exibida dentro do Flow. Usado quando formType=registration_offer.

delay

int

padrão:"0"

Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” ao destinatário.

replyTo

string

ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.

replyPrivate

boolean

padrão:"false"

Quando true e replyTo aponta para uma mensagem originária de um grupo, a resposta é redirecionada para o privado do autor original.

source

string

padrão:"api"

Identificador de origem para rastreabilidade (ex.: crm, landing-vendas, n8n).

Notas

Os Flows contact_details e registration_offer são templates do WhatsApp já aprovados e prontos para uso. Se quiser um formulário com campos específicos (perguntas custom, lógicas de tela), use buttonParamsJSON com um Flow seu.
O flowToken é o seu identificador para amarrar a resposta do formulário com o registro de origem (lead, pedido, etc.). Se não enviar, salve o UUID gerado para conseguir correlacionar depois.
Quando buttonParamsJSON é enviado, todos os outros campos relacionados ao Flow são ignorados, você assume controle total do payload, incluindo o flow_id, flow_action, flow_action_payload e flow_message_version.
Native Flow só funciona em chats 1-a-1 (@s.whatsapp.net) e em grupos (@g.us); canais (@newsletter) não são suportados pelo WhatsApp.
A resposta do formulário chega como evento interactive_response, não é uma mensagem de texto comum, então trate o webhook adequadamente.

Erros

HTTP	Status interno	Mensagem
400	,	`Instance name is required`
400	,	`Invalid request: <detalhe>`
400	,	`Number is required`
400	,	`Message is required`
400	`invalid_number`	`Invalid phone number format: <detalhe>`
400	`reply_message_not_found`	`Original message not found (ID: ...)`
400	`reply_message_instance_mismatch`	`Original message does not belong to this instance`
400	`private_reply_failed`	(motivo do erro de redirecionamento privado)
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

{
  "success": false,
  "error": { "message": "Message is required" }
}

​Descrição

​Exemplos

​Oferta de cadastro (registration_offer)

​Captura de dados de contato (contact_details)

​Flow customizado via buttonParamsJSON

Criar Flows

Playground de Flows

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Oferta de cadastro (registration_offer)

Captura de dados de contato (contact_details)

Flow customizado via `buttonParamsJSON`

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros