| name | list-messages |
| description | Retrieve and display message history from Sinch Conversation API. Use when the user asks to show messages, view conversation history, list recent messages, see messages with a contact, check message history, or view last N messages. Supports filtering by contact, conversation, channel, and time range. |
List Messages
Retrieve message history from Sinch Conversation API using the Conversation API specification. Note: MCP tools do not provide a list messages tool, so this skill always uses the Conversation API endpoint. Supports filtering by contact, conversation, channel, and time range.
Instructions
-
Extract query parameters from user request:
- Contact: contact ID, phone number, or contact name
- Conversation: conversation ID (if specified)
- Channel: WhatsApp, SMS, or other channel filter
- Count: number of messages to retrieve (default: 10, max: 1000)
- Time range: start_time and end_time if specified
-
Use Conversation API endpoint to list messages:
- Note: MCP Sinch does not provide a list messages tool, so this skill always uses the Conversation API endpoint
- Endpoint:
GET /v1/projects/{project_id}/messages
- Operation ID:
Messages_ListMessages
- Authentication: Use Basic Auth or OAuth2 with credentials from environment variables (CONVERSATION_PROJECT_ID, CONVERSATION_KEY_ID, CONVERSATION_KEY_SECRET)
- Region: Use CONVERSATION_REGION environment variable (us, eu, or br)
- Base URL:
https://{region}.conversation.api.sinch.com
- Apply filters based on extracted parameters as query parameters
- Messages are returned in descending order by accept_time (most recent first)
-
Response formatting:
- Display messages in chronological order (oldest to newest for readability)
- Include: message ID, timestamp, sender/recipient, channel, message content
- Show conversation context if available
- Indicate if there are more messages (pagination using page_token)
Examples
Natural language prompts that trigger this Skill:
- "Show me the last 5 messages with Alice"
- "What messages did I receive from John?"
- "List recent WhatsApp messages"
- "Show conversation history with contact ID abc123"
- "Display messages from the last hour"
- "What are the last 10 messages?"
Conversation API Usage (Required - no MCP alternative):
- Note: MCP Sinch does not provide a list messages tool, so this skill always uses the Conversation API
- Use the Conversation API endpoint:
GET /v1/projects/{project_id}/messages
- Authentication: Use Basic Auth with CONVERSATION_KEY_ID and CONVERSATION_KEY_SECRET, or OAuth2
- Include required headers:
Authorization, Content-Type: application/json
- Use query parameters for filtering:
contact_id, conversation_id, channel, start_time, end_time, page_size, page_token, app_id, channel_identity, messages_source, only_recipient_originated, view
Filtering Options
- By contact: Filter messages for a specific contact
- By conversation: Filter messages in a specific conversation
- By channel: Filter messages by channel (WHATSAPP, SMS, etc.)
- By time range: Filter messages between start_time and end_time
- By app: Filter messages for a specific app ID
- Pagination: Use page_size (default 10, max 1000) and page_token for pagination
Message View Options
- FULL: Complete message details (default)
- BASIC: Basic message information
Notes
- MCP Note: MCP Sinch does not provide a list messages tool, so this skill always uses the Conversation API endpoint
- Messages are ordered by accept_time in descending order (most recent first)
- Use the Conversation API endpoint directly - reference the OpenAPI spec for exact parameter names and types
- If no messages found, inform the user clearly
- Support pagination for large message lists using
page_token from response
- The
messages_source parameter determines processing mode: CONVERSATION_SOURCE for CONVERSATION mode, DISPATCH_SOURCE for DISPATCH mode
- Some query parameters may not be supported depending on the
messages_source value - check the API spec for details
