API de Conversaciones y Mensajes: enviar un mensaje y consultar estados
Cómo enviar mensajes por API a una conversación de Omnifox y seguir su estado de entrega.
Mira este paso en el video · Conversaciones y mensajes por API
La API de Conversaciones y Mensajes permite leer, crear y responder conversaciones de cualquier canal conectado (WhatsApp, Instagram, Messenger, Webchat, etc.) desde tu propio backend o herramienta de automatización, sin abrir el Inbox.
Requisitos
- Token Bearer con acceso al workspace.
- Un
conversation_idexistente, o usarfind-or-createpara obtenerlo a partir de un contacto/canal.
Endpoints principales
GET /api/v1/conversations— lista conversaciones (con?workspace_id=y filtros de estado).POST /api/v1/conversations/find-or-create— obtiene o crea la conversación para un contacto+canal.GET /api/v1/conversations/{conversation}— detalle.POST /api/v1/conversations/{conversation}/messages— envía un mensaje.GET /api/v1/conversations/{conversation}/messages— lista los mensajes.GET /api/v1/conversations/{conversation}/messages/{message}— consulta el estado de un mensaje puntual.POST /api/v1/conversations/{conversation}/assign,/close,/reopen— flujo operativo.
Cuerpo para enviar un mensaje
{
"content": "Hola, ¿en qué te puedo ayudar?",
"type": "text",
"is_internal_note": false,
"reply_to_message_id": null
}
Para plantillas de WhatsApp, usa "type": "template" con template_id y template_params.
Estados de un mensaje
Cada mensaje trae un campo status con estos valores: queued, sent, delivered, read, failed. Consúltalo con un GET al mensaje o suscríbete a los eventos message.sent, message.delivered, message.read y message.failed vía Webhooks salientes.
Ejemplo: enviar un mensaje de texto
curl -X POST "https://app.omnifox.io/api/v1/conversations/101/messages" \
-H "Authorization: Bearer TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Tu pedido ya fue despachado."}'
Consejos
- Usa
is_internal_note: truepara dejar contexto solo visible a agentes, sin enviarlo al cliente. - Si el canal es WhatsApp y pasaron más de 24 h desde el último mensaje del cliente, solo se puede reabrir la conversación con una plantilla aprobada (
type: template).
Solución de problemas
status: failed: revisa el detalle del mensaje; suele indicar plantilla no aprobada, ventana de 24h vencida o número inválido.- 404 en
/messages: elconversation_idno existe o pertenece a otro workspace. - Mensaje enviado pero contacto no lo ve: confirma que
is_internal_noteno quedó entruepor error.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.