Look up conversation by contact

Look up a single conversation and its messages by identifying a contact via phone number and/or a custom contact field.

GET/api/external/v2/conversations

Authentication

This endpoint authenticates with an API key via the X-API-Key header (ek_live_... format), instead of the bearer token used in the rest of the reference.

Query parameters

Parameter	Type	Required	Description
`phone`	String	Optional	Contact's phone number (digits only, with country code). Can be combined with field_key/field_value.
`field_key`	String	Optional	ContactFieldDefinition key to search by (e.g. 'rut'). Must be used with field_value.
`field_value`	String	Optional	Value to match for the given field_key. Must be used with field_key.
`message_limit`	Integer	Optional	Number of messages to return (default 50, max 200).

Example request

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"

Example response

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"
      }
    ]
  }
}

Notes

You must provide at least one lookup method. When combining filters, all must match (AND logic).
Each message includes status (ERROR, DELIVERED, RECEIVED or READ) and error. The error field is null unless the message failed.
Possible errors: 400 (validation), 401 (invalid or missing API key), 404 (no contact or conversation found), 409 (multiple contacts or conversations found), 500 (internal error).