Retrieve messages by AI contact with pagination (legacy)
Contact Management
Retrieve messages by AI contact with pagination
Replaces the old endpoint /public/ai-message/:aiContactId
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
pageparameter 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
hasMorefield 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
Related Endpoints
- GET /api/public/contact//conversations - Get conversations grouped (better for chat UI)
- GET /api/public/contact//info - Get contact info
- GET /api/public/contacts/search - Search contacts by phone/email
Best Practices
1. Handle Empty Pages
2. Implement Rate Limiting
3. Cache Pages
Headers
API key required to authorize the request
Path Parameters
ID of the AI contact
Query Parameters
Page index, 0-BASED (page=0 returns the newest messages). Required: omitting it returns 400.
Example:
0
Response
Messages retrieved successfully.
Messages for this page, newest first, plus synthetic "stage" and "interactive_note" entries that are not counted in total.
Total real messages for this contact (excludes the synthetic entries present in data).
Example:
45
The requested page PLUS ONE — i.e. the next page to request.
Example:
1
Number of pages. Highest requestable page is pages - 1.
Example:
3
