Buscar conversación por contacto

Busca una conversación y sus mensajes identificando a un contacto por número de teléfono y/o un campo de contacto personalizado.

GET/api/external/v2/conversations

Autenticación

Este endpoint se autentica con una API key mediante la cabecera X-API-Key (formato ek_live_...), en lugar del token bearer del resto de la referencia.

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Descripción
`phone`	String	Opcional	Teléfono del contacto (solo dígitos, con código de país). Puede combinarse con field_key/field_value.
`field_key`	String	Opcional	Clave del ContactFieldDefinition por la que buscar (p. ej. 'rut'). Debe usarse con field_value.
`field_value`	String	Opcional	Valor a coincidir para el field_key indicado. Debe usarse con field_key.
`message_limit`	Integer	Opcional	Número de mensajes a devolver (por defecto 50, máximo 200).

Ejemplo de solicitud

bash

curl -X GET "https://eclectic-api-537143970188.us-central1.run.app/api/external/v2/conversations?phone=56912345678&message_limit=50" \
  -H "X-API-Key: ek_live_your_api_key_here"

Ejemplo de respuesta

json

{
  "contact": {
    "id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "56912345678"
  },
  "conversation": {
    "id": "f3670b13-446b-4127-9623-8b1cd78899f9",
    "platform": "whatsapp",
    "created_at": "2024-09-23T20:09:10Z",
    "last_message_at": "2024-09-24T11:32:05Z",
    "message_count": 2,
    "messages": [
      {
        "id": "a1b2c3d4-0001-0000-0000-000000000000",
        "text": "Hello",
        "direction": "inbound",
        "status": "RECEIVED",
        "error": null,
        "created_at": "2024-09-23T20:09:10Z"
      },
      {
        "id": "a1b2c3d4-0002-0000-0000-000000000000",
        "text": "Hi! How can we help?",
        "direction": "outbound",
        "status": "DELIVERED",
        "error": null,
        "created_at": "2024-09-24T11:32:05Z"
      },
      {
        "id": "a1b2c3d4-0003-0000-0000-000000000000",
        "text": "Can you confirm your email?",
        "direction": "outbound",
        "status": "ERROR",
        "error": "Message undeliverable",
        "created_at": "2024-09-24T11:35:15Z"
      }
    ]
  }
}

Notas

Debes proporcionar al menos un método de búsqueda. Si combinas filtros, todos deben coincidir (lógica AND).
Cada mensaje incluye status (ERROR, DELIVERED, RECEIVED o READ) y error. El campo error viene como null salvo que el mensaje haya fallado.
Posibles errores: 400 (validación), 401 (API key inválida o ausente), 404 (no se encontró contacto o conversación), 409 (se encontraron múltiples contactos o conversaciones), 500 (error interno).