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"
  }'

await fetch(`https://ryzeapi.cloud/api/message/form/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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"
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/form/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/form/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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
  }'

await fetch(`https://ryzeapi.cloud/api/message/form/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/form/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/form/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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\"}}"
  }'

const flowParams = {
  flow_message_version: "3",
  flow_token:           "meu-token-123",
  flow_id:              "123456789012345",
  flow_cta:             "Responder pesquisa",
  flow_action:          "navigate",
  flow_action_payload:  { screen: "WELCOME" }
};

await fetch(`https://ryzeapi.cloud/api/message/form/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:           "5511999999999",
    message:          "Responda à pesquisa rápida e ganhe 10% off",
    buttonLabel:      "Responder pesquisa",
    buttonParamsJSON: JSON.stringify(flowParams)
  })
});

import os, json, requests

flow_params = {
    "flow_message_version": "3",
    "flow_token":           "meu-token-123",
    "flow_id":              "123456789012345",
    "flow_cta":             "Responder pesquisa",
    "flow_action":          "navigate",
    "flow_action_payload":  {"screen": "WELCOME"}
}

requests.post(
    f"https://ryzeapi.cloud/api/message/form/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":           "5511999999999",
        "message":          "Responda à pesquisa rápida e ganhe 10% off",
        "buttonLabel":      "Responder pesquisa",
        "buttonParamsJSON": json.dumps(flow_params)
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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\"}}"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/form/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

obrigatório

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

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

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

string

obrigatório

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

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.

string

padrão:"Adicionar informações"

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

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.

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).

string

padrão:"4"

Versão do flow_message_version enviada para o WhatsApp.

int

padrão:"3"

Versão do message_version do payload Native Flow.

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.

boolean

padrão:"true"

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

boolean

padrão:"true"

Exibe o campo “Número de telefone”.

boolean

padrão:"true"

Exibe o campo “E-mail”.

boolean

padrão:"true"

Exibe o campo “CPF/CNPJ”.

boolean

padrão:"true"

Exibe o campo “Endereço de entrega”.

string

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

string

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

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.

string

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

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.

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" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Enviar Formulário

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

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