Returns a paginated, cross-source timeline of everything a contact has done, merged in
reverse-chronological order (most recent first): conversations opened, campaigns received,
events fired, NPS surveys, in-app surveys, page views and visitor conversions.

Contact Identification

You can retrieve the timeline using various types of identifiers:

1. Customerly Contact ID (numeric):

• Use the internal contact ID directly (e.g., 29911301)
• Example: GET /contacts/29911301/activity/timeline

2. Custom User ID (prefix: cuid:):

• Your own custom identifier for a registered user
• Example: GET /contacts/cuid:user_123/activity/timeline

3. Custom Lead ID (prefix: clid:):

• Your own custom identifier for a lead
• Example: GET /contacts/clid:lead_456/activity/timeline

4. WhatsApp Number (prefix: wa:):

• The contact's WhatsApp number in E.164 format
• Example: GET /contacts/wa:+1234567890/activity/timeline

5. Email Address (prefix: uem: or lem:):

• For registered users: uem:[email protected] (User EMail)
• For leads: lem:[email protected] (Lead EMail)
• Example: GET /contacts/uem:[email protected]/activity/timeline

Pagination

This endpoint uses opaque cursor-based pagination:

• per_page: Number of activities to return per page (default: 20, max: 100)
• cursor: The opaque cursor string returned by the previous response

Example pagination flow:

1. First request: GET /contacts/{id}/activity/timeline?per_page=20
2. Response returns up to 20 activities and a cursor string
3. Next page: GET /contacts/{id}/activity/timeline?per_page=20&cursor={cursor}
4. Continue until cursor is null (no more activities available)

The cursor value is opaque — do not parse it, just pass it back as-is.

Response

Each activity has:

• type: One of activity, conversation_open, campaign_sent, campaign_seen,
  campaign_clicked, campaign_replied, event, nps_sent, nps_voted, survey_seen,
  survey_completed, survey_rejected, page_view, visitor_converted
• triggered_at: Unix timestamp (seconds) of when the activity happened
• metadata: A type-specific object (see the metadata field description for the keys per type)