WhatsApp: Flows por la API
Lista los WhatsApp Flows publicados de un número y envía un Flow al contacto por la API de XBASE, dentro de la ventana de 24 horas.
Actualizado el
Un WhatsApp Flow es un formulario que se abre dentro de WhatsApp, como un registro, una reserva o una encuesta. Los Flows se crean y se publican en WhatsApp API → Flows, y las respuestas del contacto llegan a la conversación.
Listar los Flows
GET https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId es obligatorio: los Flows son de la cuenta de WhatsApp de la empresa en Meta, y cada número envía los de su cuenta.
curl "https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Respuesta 200:
[
{
"id": "1234567890123456",
"name": "Reserva de visita",
"status": "PUBLISHED",
"categories": ["APPOINTMENT_BOOKING"]
}
]| Campo | Tipo | Descripción |
|---|---|---|
id | texto | Id del Flow en Meta. Va en flow.flowId en el envío |
name | texto | Nombre del Flow |
status | texto | PUBLISHED, o THROTTLED (publicado, pero Meta lo limitó a 10 envíos por hora) |
categories | lista de textos | Categorías del Flow en Meta |
Solo vienen los Flows que Meta entrega a un contacto: los borradores y los Flows descontinuados quedan fuera.
Enviar un Flow
El Flow sale por POST /whatsapp/messages con "type": "flow", dentro de la ventana 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": "5491155550100",
"type": "flow",
"flow": {
"flowId": "1234567890123456",
"body": "Elige el mejor día para la visita.",
"cta": "Reservar"
}
}'| Campo | Regla |
|---|---|
flow.flowId | Id del Flow, solo dígitos (listar los Flows) |
flow.body | Texto del mensaje, hasta 1024 caracteres |
flow.cta | Texto del botón que abre el Flow, hasta 30 caracteres |
flow.header · flow.footer | Opcionales, hasta 60 caracteres |
La respuesta es la misma de los mensajes. El Flow se abre en la primera pantalla. Cuando el contacto envía el formulario, las respuestas aparecen en la conversación y llegan como whatsapp.message.received en los webhooks del workspace.
Errores
| Estado | code | Cuándo |
|---|---|---|
| 400 | (sin code) | Falta numberId, flowId con algo más que dígitos o Flow sin pantallas |
| 404 | NUMBER_NOT_FOUND | El número no existe en este workspace |
| 404 | FLOW_NOT_FOUND | El Flow no es de la cuenta de WhatsApp de este número |
| 422 | NUMBER_DISCONNECTED | El número está desconectado |
| 422 | WINDOW_CLOSED | Fuera de la ventana de 24 horas. Envía una plantilla |
| 422 | META_ERROR | Meta rechazó. details.metaCode trae el código de Meta |
Mira el formato completo en Errores.