list-messages

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

1. 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

2. 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)

3. 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):

1. Note: MCP Sinch does not provide a list messages tool, so this skill always uses the Conversation API
2. Use the Conversation API endpoint: GET /v1/projects/{project_id}/messages
3. Authentication: Use Basic Auth with CONVERSATION_KEY_ID and CONVERSATION_KEY_SECRET, or OAuth2
4. Include required headers: Authorization, Content-Type: application/json
5. 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