Conversas — API Zyron Connect Suite

Módulo

Conversaciones

Lee conversaciones del Inbox y el historial completo de mensajes.

GET/conversations/conversations GET/conversations/:id/messages/conversations/:id/messages GET/conversations/resolve/conversations/resolve GET/conversations/:id/conversations/:id PATCH/conversations/:id/conversations/:id

GET/conversationsAlcance: readOficial + Básico

Lista conversaciones del Inbox.

Devuelve último mensaje, estado, conexión y datos básicos del contacto.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`opcional	uuid	Filtra por conexión de WhatsApp.
`contact_id`opcional	uuid	Filtra por las conversaciones de un contacto.
`phone`opcional	string	Filtra por el teléfono del contacto (con DDI).
`status`opcional	open \| closed \| pending	Filtra por estado de conversación.
`limit`opcional	number	Cantidad de registros por página. Predeterminado 50; máximo 200 en la mayoría de listas.
`offset`opcional	number	Índice inicial de la página. Usa pagination.next_offset para la siguiente página.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations?status=open&limit=20&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Conversaciones devueltas.

Ejemplo de respuesta

{
  "data": [
    {
      "id": "<CONVERSATION_ID>",
      "connection_id": "<CONNECTION_ID>",
      "contact_id": "<CONTACT_ID>",
      "status": "open",
      "last_message_text": "Quero saber mais",
      "last_message_at": "2026-06-15T12:30:00.000Z",
      "unread_count": 2,
      "contacts": {
        "name": "Maria Silva",
        "phone": "5511999998888"
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 41,
    "next_offset": 20
  }
}

GET/conversations/:id/messagesAlcance: readOficial + Básico

Lista mensajes de una conversación.

El límite predeterminado es 100 y el máximo 500. Orden ascendente por created_at.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	uuid	ID de la conversación.

Parámetros de query

Campo	Tipo	Descripción
`limit`opcional	number	Cantidad de mensajes. Predeterminado 100; máximo 500.
`offset`opcional	number	Índice inicial de la página.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>/messages?limit=100&offset=0" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Mensajes devueltos.
404	Conversación no encontrada.

Ejemplo de respuesta

{
  "data": [
    {
      "id": "41a9fa77-6b9d-4d94-a48d-74d036c54121",
      "direction": "in",
      "body": "Quero saber mais",
      "created_at": "2026-06-15T12:30:00.000Z"
    },
    {
      "id": "d38adf37-0f2a-477f-8d8a-238caab12411",
      "direction": "out",
      "body": "Claro, vou te explicar.",
      "created_at": "2026-06-15T12:31:00.000Z"
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2,
    "next_offset": null
  }
}

GET/conversations/resolveAlcance: readOficial + Básico

Resuelve una conversación por número.

Evita depender de un UUID previo usando connection_id + teléfono, BSUID, parent BSUID o username.

Parámetros de ruta

Sin parámetros adicionales.

Parámetros de query

Campo	Tipo	Descripción
`connection_id`obligatorio	uuid	Conexión de WhatsApp.
`phone`opcional	string	Teléfono con DDI.
`business_scoped_user_id`opcional	string	Identidad BSUID de Meta.
`parent_business_scoped_user_id`opcional	string	Parent BSUID de Meta.
`username`opcional	string	Usuario externo persistido en el contacto.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/resolve?connection_id=<CONNECTION_ID>&phone=5511999998888" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Conversación resuelta.
404	Contacto o conversación no encontrado.

Ejemplo de respuesta

{
  "data": {
    "id": "<CONVERSATION_ID>",
    "connection_id": "<CONNECTION_ID>",
    "status": "open",
    "last_inbound_at": "2026-07-13T13:28:28.347Z",
    "contact": { "id": "<CONTACT_ID>", "phone": "5511999998888" }
  }
}

GET/conversations/:idAlcance: readOficial + Básico

Detalle operativo de la conversación.

Devuelve estado, etiquetas, agente, nota interna, last_inbound_at (ventana de 24 h) e identidades del contacto.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	uuid	ID de conversación.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Este endpoint no recibe cuerpo JSON.

Ejemplos listos

curl -X GET "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Respuestas

200	Conversación devuelta.
404	Conversación no encontrada.

PATCH/conversations/:idAlcance: writeOficial + Básico

Actualiza estado operativo.

Cierra, reabre, deja pendiente y actualiza etiquetas/notas.

Parámetros de ruta

Campo	Tipo	Descripción
`id`obligatorio	uuid	ID de conversación.

Parámetros de query

Sin parámetros adicionales.

Campos del cuerpo

Campo	Tipo	Descripción
`status`opcional	open \| closed \| pending	Estado de conversación.
`tags`opcional	string[]	Etiquetas operativas (hasta 30).
`assignee_name`opcional	string	Agente responsable.
`internal_note`opcional	string	Nota interna del equipo, hasta 4000 caracteres.

Ejemplos listos

curl -X PATCH "https://connect.zyronstack.com/api/v1/conversations/<CONVERSATION_ID>" \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "content-type: application/json" \
  -d '{
  "status": "pending",
  "tags": ["lead-quente", "n8n"],
  "assignee_name": "Time comercial"
}'

Respuestas

200	Conversación actualizada.