Skip to main content
POST
Enviar Flow
Envia um WhatsApp Flow diretamente, como mensagem interativa.
O envio direto de flow só funciona dentro da janela de 24h (sessão aberta com o contato). Para disparo proativo (como um lembrete ou uma pesquisa), use Send Template com um template que tenha botão de Flow.

flowData

O dataset completo do flow, enviado de uma vez. Os dados entram pela tela de entrada (a única que o WhatsApp permite pré-preencher no disparo) e, em flows multi-tela, são repassados internamente para as telas seguintes via navigate — você não divide o flowData por tela. Os valores são referenciados no flow via ${data.campo} e a Meta substitui os placeholders no momento do envio. Quando enviar flowData, informe também screen (a tela de entrada).

metadata

Metadados livres gravados na mensagem para controle/consulta posterior (ex.: { "pedidoId": "...", "clienteId": "..." }).

Idempotência (X-Request-Id)

Mesmo comportamento do Send Template: envie um UUID no header X-Request-Id para evitar envio duplicado em retries.

Authorizations

Authorization
string
header
required

Token JWT da sua conta. Use o formato: Bearer {seu-jwt-token}

Headers

X-Request-Id
string<uuid>

Chave de idempotência gerada pelo integrador para evitar disparo duplicado da mesma mensagem em caso de retry. Gere um UUID por mensagem lógica e reenvie o mesmo valor se precisar repetir a requisição. A chave é única por canal (channelId). Se não for um UUID válido, a API responde 400 (key: "invalid_request_id"). Se omitido, não há deduplicação.

Example:

"11111111-1111-4111-8111-111111111111"

Body

application/json

Dados para enviar um WhatsApp Flow

channelId
string
required

ID do canal para envio.

Example:

"clh1234567890"

phone
string
required

Número do destinatário (formato internacional).

Example:

"+5511999999999"

flowId
string
required

ID do WhatsApp Flow a enviar.

Example:

"123456789012345"

body
string
required

Texto do corpo da mensagem que acompanha o botão do flow.

Example:

"Toque para escolher seu horário"

flowCta
string
required

Rótulo do botão que abre o flow (CTA). Recomendado < 30 caracteres.

Example:

"Agendar"

screen
string

Tela inicial do flow. Obrigatória quando enviar flowData.

Example:

"AGENDAMENTO"

flowData
object

Dados iniciais para pré-preencher a 1ª tela (referenciados via ${data.campo}).

Example:
mode
enum<string>

draft (teste) ou published (padrão).

Available options:
draft,
published
Example:

"published"

metadata
object

Metadados livres gravados na mensagem (ex.: id do pedido, id do cliente).

Example:

Response

Replay: uma requisição com o mesmo X-Request-Id já foi processada com sucesso neste canal. A mensagem não é reenviada e a resposta traz o mesmo resultado da primeira vez (mesmo wamid, chatId etc.).

success
boolean
required

Indica se o envio foi bem-sucedido.

Example:

true

chatId
string
required

ID interno do chat.

Example:

"clh0987654321"

externalChatId
string
required

ID externo do chat (número do WhatsApp).

Example:

"5511999999999@s.whatsapp.net"

message
string
required

Mensagem de confirmação.

Example:

"Template enviado com sucesso"

wamid
string

WhatsApp Message ID retornado pela Meta.

Example:

"wamid.HBgNNTUxMTk5OTk5OTk5FQIAERgSQjYxNzc2..."