Disparar un flujo
POST/flows/:id/trigger
Inicia una ejecución del flujo para un contacto. El flujo debe estar activo y publicado, y la versión publicada debe tener un disparador de tipo API.
Identifica el contacto por contact.id o por contact.phone — con el teléfono, un
contacto que no existe se crea. Lo que venga en data queda disponible en el flujo como
{{trigger.<clave>}}. El número que envía es phoneNumberId, o el configurado en el
disparador, o el número activo más antiguo de la cuenta.
La respuesta es 202 con el runId; los mensajes salen después, fuera de la
solicitud. runId puede venir null sin ser un error: el disparador no lleva a ningún
paso, o el mismo contacto empezó este flujo hace poco (el intervalo mínimo entre
ejecuciones). Empezar una ejecución cancela las otras en curso del mismo contacto en ese
número.
Idempotencia. Con Idempotency-Key, repetir la llamada en hasta 24 horas devuelve
200 con el mismo runId y replayed: true, sin iniciar otra ejecución. A diferencia
de POST /messages: aquí el cuerpo no se compara, y una llamada que falló no guarda
la clave — la repetición vuelve a intentarlo.
Request
Responses
- 200
- 202
- 401
- 402
- 403
- 404
- 409
- 422
- 429
Repetición con la misma Idempotency-Key.
Ejecución iniciada.
Token ausente, mal formado, desconocido o revocado (authentication), o cuenta
suspendida (tenant_inactive).
Sin derecho de uso (payment_required). El cuerpo trae el motivo en reason y la
salida en action: qué hacer (kind) y la página del panel donde se hace (url).
La credencial no puede usar el número: fuera del alcance de la clave, de otra cuenta, o la cuenta no tiene número activo.
Flujo inexistente (not_found) o contact.id desconocido (contact_not_found).
El flujo no está activo o no se publicó (flow_not_active).
Cuerpo inválido (invalid_request), la versión publicada no tiene disparador de API (flow_no_api_trigger) o el teléfono no es válido (contact_invalid_phone).
Límite de peticiones superado (rate_limit).
Response Headers
Segundos a esperar antes de reintentar.
Categoría de límite aplicada — send, media o default.
Qué cubo describen las otras cabeceras — key (la API key), session (el panel) o account (el techo de la cuenta).
Techo de peticiones de la categoría en la ventana actual.
Peticiones restantes en la ventana actual.