Endpoint ·
POST /conversation/actionsPOST /conversation/actions ejecuta un grupo de hasta 10
acciones sobre una sola conversación, en el orden que las envías. En vez
de hacer N requests para etiquetar, dejar una nota y ejecutar el AI, los
encadenas en un solo request. Es el camino recomendado para mutar una
conversación desde un cliente externo.
Cada elemento del array actions lleva un campo type. send_message unifica
los cuatro modos de envío (texto, media, respuesta rápida, plantilla).
send_quick_reply_or_template es la única cuyo modo lo decide el servidor: manda
la respuesta rápida si la ventana de 24h está abierta, o la
plantilla si está cerrada.
Un grupo admite hasta 10 acciones, de las cuales como máximo 3 pueden
disparar al AI. Excederlo falla con
BATCH_LIMIT_EXCEEDED.Identificar la conversación
El grupo corre sobre una conversación: la identificas con el objetoconversation, que lleva exactamente uno de uuid, whatsapp_user_id,
username o phone, más channel (obligatorio).
string
Clave estable de una conversación que ya conoces. El camino más directo.
string
BSUID del contacto (identidad opaca de Meta). Resuelve por igualdad exacta;
identificador recomendado de aquí en adelante.
string
Username público de WhatsApp, con o sin
@ y sin distinguir mayúsculas. Si
varios contactos lo comparten, la API responde 409 (USERNAME_AMBIGUOUS).string
Teléfono en formato E.164. Si está duplicado entre contactos, la API responde
409 (PHONE_NUMBER_AMBIGUOUS) en vez de adivinar.string
requerido
Clave pública del canal — cópiala del dashboard en Configuración → Canales
(campo Clave de canal), o lístalas con
GET /channels. Obligatorio en todo
request: fija el canal objetivo. En las vías por contacto (phone, username,
whatsapp_user_id) restringe la resolución a ese canal; con uuid el motor lo
ignora, pero el contrato igual lo exige. Una clave que no existe → 404
(CHANNEL_NOT_FOUND).Cómo se ejecuta
1
Validación síncrona
La API valida el request. Si el preflight lo rechaza (ej. el AI no tiene
tokens), responde un
4xx síncrono y ninguna acción se ejecuta.2
202 Accepted
Si pasa la validación, responde
202 de inmediato; el grupo corre en
background.3
Ejecución en orden
Las acciones se ejecutan una por una, en el orden enviado.
Stop on error
stop_on_error controla qué pasa cuando una acción falla durante la ejecución:
Escalada a pending
escalate_on_error controla si una falla del grupo escala la conversación a inbox_status='pending' para que un humano la revise:
Los errores de input del integrador (
*_NOT_FOUND, *_AMBIGUOUS, WINDOW_CLOSED, TEMPLATE_NOT_APPROVED, etc.), los guards de billing (WALLET_BLOCKED, VISION_WALLET_BLOCKED) y el guard de integridad de mark_resolved (TRANSCRIPTION_REQUIRED_TO_RESOLVE) nunca escalan — corrígelos y reintenta sin intervención humana.Armar una lista de acciones
Cada acción es un objeto en el arrayactions, identificado por su type. Un
request agrupa varias acciones sobre la misma conversación y se ejecutan en el
orden enviado. El objeto conversation siempre incluye channel. Ejemplo —
etiquetar, dejar una nota y ejecutar el AI, sin cortar ante fallos:
Identificar por distintos campos
Cambia solo el identificador dentro deconversation (channel va siempre); el
resto del request no cambia:
unassign_ai, sin campos. Es idempotente:
si la conversación ya no tiene AI, es un no-op exitoso.