WhatsApp: Flows pela API
Liste os WhatsApp Flows publicados de um número e envie um Flow ao contato pela API da XBASE, dentro da janela de 24 horas.
Atualizado em
Um WhatsApp Flow é um formulário que abre dentro do WhatsApp, como cadastro, agendamento ou pesquisa. Os Flows são criados e publicados em WhatsApp API → Flows, e as respostas do contato chegam na conversa.
Listar os Flows
GET https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId é obrigatório: os Flows são da conta de WhatsApp da empresa na Meta, e cada número envia os da conta dele.
curl "https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Resposta 200:
[
{
"id": "1234567890123456",
"name": "Agendamento de visita",
"status": "PUBLISHED",
"categories": ["APPOINTMENT_BOOKING"]
}
]| Campo | Tipo | Descrição |
|---|---|---|
id | texto | Id do Flow na Meta. Vai em flow.flowId no envio |
name | texto | Nome do Flow |
status | texto | PUBLISHED, ou THROTTLED (publicado, mas a Meta limitou a 10 envios por hora) |
categories | lista de textos | Categorias do Flow na Meta |
Só vêm os Flows que a Meta entrega a um contato: rascunhos e Flows descontinuados ficam de fora.
Enviar um Flow
O Flow sai por POST /whatsapp/messages com "type": "flow", dentro da janela de 24 horas:
curl -X POST https://api.xbase.app/api/external/v1/whatsapp/messages \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"to": "5521999990000",
"type": "flow",
"flow": {
"flowId": "1234567890123456",
"body": "Escolha o melhor dia para a visita.",
"cta": "Agendar"
}
}'| Campo | Regra |
|---|---|
flow.flowId | Id do Flow, só dígitos (listar os Flows) |
flow.body | Texto da mensagem, até 1.024 caracteres |
flow.cta | Texto do botão que abre o Flow, até 30 caracteres |
flow.header · flow.footer | Opcionais, até 60 caracteres |
A resposta é a mesma das mensagens. O Flow abre na primeira tela. Quando o contato envia o formulário, as respostas aparecem na conversa e chegam como whatsapp.message.received nos webhooks do workspace.
Erros
| Status | code | Quando |
|---|---|---|
| 400 | (sem code) | numberId faltando, flowId com algo além de dígitos ou Flow sem telas |
| 404 | NUMBER_NOT_FOUND | O número não existe neste workspace |
| 404 | FLOW_NOT_FOUND | O Flow não é da conta de WhatsApp deste número |
| 422 | NUMBER_DISCONNECTED | O número está desconectado |
| 422 | WINDOW_CLOSED | Fora da janela de 24 horas. Envie um template |
| 422 | META_ERROR | A Meta recusou. details.metaCode traz o código da Meta |
Veja o formato completo em Erros.