Contact timeline

Retrieve every message of a contact across all channels (WhatsApp, Instagram, email, web chat and more), merged into a single conversation, oldest first.

GET/contacts/:uuid/timeline

Authentication

This endpoint authenticates with your API key sent in the X-API-Key header (ek_live_... format). You can manage your API keys from the Dev Tools section of the dashboard.

Path parameters

Parameter	Type	Required	Description
`uuid`	UUID	Required	UUID of the contact.

Query parameters

Parameter	Type	Required	Description
`since`	Datetime	Optional	ISO 8601 date and time. Returns messages created at or after it.
`until`	Datetime	Optional	ISO 8601 date and time. Returns messages created before it.
`channel`	String	Optional	Comma-separated channels to include. Defaults to all. Values: whatsapp, whatsapp_web, instagram, messenger, tiktok, email, sms, web_embed, hubspot_chat, voice.
`limit`	Integer	Optional	Messages per page (default 100, max 500).
`cursor`	String	Optional	The next_cursor of the previous page. Omit it on the first request.

Example request

bash

curl -X GET "https://api.eclecticlabs.com/api/external/v2/contacts/eb2b914a-977e-4ab8-96e7-b886698b3eac/timeline?limit=100" \
  -H "X-API-Key: ek_live_your_api_key_here"

Example response

json

{
  "contact": {
    "id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
    "first_name": "Ana",
    "last_name": "Pérez",
    "phone_number": "56912345678"
  },
  "messages": [
    {
      "id": "c0ffee00-0001-0000-0000-000000000000",
      "conversation_id": "7a1c2d3e-0000-0000-0000-000000000000",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "instagram",
      "direction": "inbound",
      "sender_type": "contact",
      "agent": null,
      "user": null,
      "type": "text",
      "text": "Vi el producto en su perfil, ¿tiene stock?",
      "media": null,
      "reply_to_id": null,
      "status": "RECEIVED",
      "error": null,
      "created_at": "2026-09-10T15:20:00Z"
    },
    {
      "id": "a1b2c3d4-0005-0000-0000-000000000000",
      "conversation_id": "f3670b13-446b-4127-9623-8b1cd78899f9",
      "contact_id": "eb2b914a-977e-4ab8-96e7-b886698b3eac",
      "channel": "whatsapp",
      "direction": "outbound",
      "sender_type": "human",
      "agent": null,
      "user": {
        "id": "0b1c2d3e-0000-0000-0000-000000000000",
        "name": "Camila",
        "email": "camila@example.com"
      },
      "type": "text",
      "text": "Hola Ana, te escribo por acá para coordinar el despacho.",
      "media": null,
      "reply_to_id": null,
      "status": "DELIVERED",
      "error": null,
      "created_at": "2026-09-11T10:05:00Z"
    }
  ],
  "next_cursor": null
}

Response fields

idUUID of the message.
conversation_idUUID of the conversation the message belongs to.
contact_idUUID of that conversation's contact.
channelChannel of the message, such as whatsapp or instagram.
directioninbound if the contact sent it, outbound if your business did.
sender_typeWho sent the message. See the values below.
agentAI agent that replied (id and name), or null.
userTeam member who replied from Eclectic (id, name and email), or null.
typeMessage type: text, image, audio, document, template, and so on.
textMessage text. Can be empty for file-only messages.
mediaAttached file (id, filename and content_type), or null.
reply_to_idUUID of the message it replies to, or null.
statusERROR, DELIVERED, RECEIVED or READ.
errorDelivery error detail, or null.
created_atDate and time of the message (ISO 8601, UTC).

sender_type values

sender_type separates replies from AI, from your team and from your integrations.

contactThe customer.
ai_agentAn Eclectic AI agent.
humanA member of your team, from Eclectic or from the channel's own app (such as WhatsApp Business).
apiA message sent through the Eclectic public API.
automationCampaigns, flows and system messages.

Notes

Repeat the request with each response's next_cursor until it is null. A page can hold fewer messages than limit.
Each message carries its channel and conversation, so you can rebuild each thread separately. When a number is connected to both WhatsApp Web and the WhatsApp Business API, each message recorded on both appears once, under the whatsapp channel.
Files come as a reference in media. To download one, request a URL with GET /media/:id using the media id.
This endpoint and GET /messages share a limit of 120 requests per minute per business.
Possible errors: 400 (invalid parameters), 401 (invalid or missing API key), 404 (contact not found), 429 (rate limit).