API de Conversaciones y Mensajes: enviar un mensaje y consultar estados

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_id existente, o usar find-or-create para 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, usá "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. Consultalo con un GET al mensaje o suscribite 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

• Usá is_internal_note: true para 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: revisá el detalle del mensaje; suele indicar plantilla no aprobada, ventana de 24h vencida o número inválido.
• 404 en /messages: el conversation_id no existe o pertenece a otro workspace.
• Mensaje enviado pero contacto no lo ve: confirmá que is_internal_note no quedó en true por error.