Skip to main content
GET
Retrieve messages by AI contact with pagination (legacy)

Overview

Retrieve messages from a contact with pagination support. This endpoint returns a flat list of messages in chronological order, perfect for processing large message histories efficiently. This is the recommended endpoint for accessing message history when you need pagination, sequential processing, or want to handle large datasets.

Use Cases

  • Message Processing: Process messages sequentially for analytics or exports
  • Large Message Histories: Handle contacts with thousands of messages efficiently
  • Data Export: Export all messages in chunks
  • Message Analytics: Analyze message patterns, response times, sentiment
  • Search & Filter: Build custom message search and filtering
  • Audit Logs: Create audit trails of all communications

Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

Path Parameters

Query Parameters

Pagination: Each page returns a fixed number of messages. Keep incrementing page until you receive an empty array.

Response Structure

Returns an object with pagination information and messages:

Message Object

Example Requests

Get First Page

Get Second Page

Example Response

Common Use Cases

1. Fetch All Messages with Pagination

2. Export Messages to CSV

3. Calculate Response Time Metrics

4. Find Messages with Specific Content

5. Get Latest Messages Only

Pagination Details

Page Size

  • Each page typically returns 20-50 messages (exact number may vary)
  • Pages are numbered starting from 1
  • Messages are ordered chronologically (oldest to newest or newest to oldest)

Fetching All Pages

Error Responses

Important Notes

  • Pagination Required: The page parameter is mandatory
  • Page Starts at 1: First page is 1, not 0
  • No Total Count: Response may not include total message count
  • Check hasMore: Use hasMore field to determine if more pages exist
  • Cross-Channel: Works with all communication channels
  • Include Stage History: Messages include stage change events

When to Use This vs Conversations

Best Practices

1. Handle Empty Pages

2. Implement Rate Limiting

3. Cache Pages

Headers

x-api-key
string
required

API key required to authorize the request

Path Parameters

aiContactId
string
required

ID of the AI contact

Query Parameters

page
number
required

Page index, 0-BASED (page=0 returns the newest messages). Required: omitting it returns 400.

Example:

0

Response

Messages retrieved successfully.

data
object[]

Messages for this page, newest first, plus synthetic "stage" and "interactive_note" entries that are not counted in total.

total
number

Total real messages for this contact (excludes the synthetic entries present in data).

Example:

45

page
number

The requested page PLUS ONE — i.e. the next page to request.

Example:

1

pages
number

Number of pages. Highest requestable page is pages - 1.

Example:

3