list_messages
Retrieve and filter messages from Carbon Voice using date ranges, user IDs, conversation IDs, or folders. Access presigned URLs directly for seamless usage, with options to sort and paginate results.
Instructions
List Messages. By default returns latest 20 messages. The maximum allowed range between dates is 183 days (6 months). All presigned URLs returned by this tool are ready to use. Do not parse, modify, or re-encode them—always present or use the URLs exactly as received.If you want to get messages from a specific date range, you can use the "start_date" and "end_date" parameters. If you want to get messages from a specific date, you can use the "date" parameter. If you want to get messages from a specific user, you can use the "user_ids" parameter. If you want to get messages from a specific conversation, you can use the "conversation_id" parameter. If you want to get messages from a specific folder, you can use the "folder_id" parameter. If you want to get messages from a specific workspace, you can use the "workspace_id" parameter. If you want to get messages for a particular language, you can use the "language" parameter.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | No | Conversation ID (optional) | |
| end_date | No | End Date range | |
| folder_id | No | Folder ID (optional) | |
| language | No | Language (optional) | |
| page | No | ||
| size | No | Max number of results per page is: **50** | |
| sort_direction | No | The field used to sort results is **Creation Date** | DESC |
| start_date | No | Start Date range | |
| type | No | Type (optional) | |
| user_ids | No | User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included. | |
| workspace_id | No | Workspace ID (optional) |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"conversation_id": {
"description": "Conversation ID (optional)",
"type": "string"
},
"end_date": {
"description": "End Date range",
"format": "date-time",
"type": "string"
},
"folder_id": {
"description": "Folder ID (optional)",
"type": "string"
},
"language": {
"description": "Language (optional)",
"type": "string"
},
"page": {
"default": 1,
"minimum": 1,
"type": "number"
},
"size": {
"default": 20,
"description": "Max number of results per page is: **50**",
"maximum": 50,
"minimum": 1,
"type": "number"
},
"sort_direction": {
"default": "DESC",
"description": "The field used to sort results is **Creation Date**",
"enum": [
"ASC",
"DESC"
],
"type": "string"
},
"start_date": {
"description": "Start Date range",
"format": "date-time",
"type": "string"
},
"type": {
"description": "Type (optional)",
"enum": [
"channel",
"prerecorded",
"voicememo",
"stored",
"welcome"
],
"type": "string"
},
"user_ids": {
"description": "User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included.",
"items": {
"type": "string"
},
"type": "array"
},
"workspace_id": {
"description": "Workspace ID (optional)",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/server.ts:107-123 (handler)The MCP tool handler for 'list_messages', which authenticates and delegates to the generated simplifiedApi.listMessages, formatting the response or error.async ( params: ListMessagesParams, { authInfo }, ): Promise<McpToolResponse> => { try { // Fallback to regular API return formatToMCPToolResponse( await simplifiedApi.listMessages( params, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error listing messages:', { params, error }); return formatToMCPToolResponse(error); } },
- src/server.ts:87-124 (registration)MCP server registration of the 'list_messages' tool with description, input schema reference, annotations, and handler function.server.registerTool( 'list_messages', { description: 'List Messages. By default returns latest 20 messages. The maximum allowed range between dates is 183 days (6 months). ' + 'All presigned URLs returned by this tool are ready to use. ' + 'Do not parse, modify, or re-encode them—always present or use the URLs exactly as received.' + 'If you want to get messages from a specific date range, you can use the "start_date" and "end_date" parameters. ' + 'If you want to get messages from a specific date, you can use the "date" parameter. ' + 'If you want to get messages from a specific user, you can use the "user_ids" parameter. ' + 'If you want to get messages from a specific conversation, you can use the "conversation_id" parameter. ' + 'If you want to get messages from a specific folder, you can use the "folder_id" parameter. ' + 'If you want to get messages from a specific workspace, you can use the "workspace_id" parameter. ' + 'If you want to get messages for a particular language, you can use the "language" parameter. ', inputSchema: listMessagesQueryParams.shape, annotations: { readOnlyHint: true, destructiveHint: false, }, }, async ( params: ListMessagesParams, { authInfo }, ): Promise<McpToolResponse> => { try { // Fallback to regular API return formatToMCPToolResponse( await simplifiedApi.listMessages( params, setCarbonVoiceAuthHeader(authInfo?.token), ), ); } catch (error) { logger.error('Error listing messages:', { params, error }); return formatToMCPToolResponse(error); } }, );
- Zod schema definition for input parameters (listMessagesQueryParams) used in the tool's inputSchema.export const listMessagesQueryParams = zod.object({ "page": zod.number().min(1).default(listMessagesQueryPageDefault), "size": zod.number().min(1).max(listMessagesQuerySizeMax).default(listMessagesQuerySizeDefault).describe('Max number of results per page is: **50**'), "sort_direction": zod.enum(['ASC', 'DESC']).default(listMessagesQuerySortDirectionDefault).describe('The field used to sort results is **Creation Date**'), "start_date": zod.string().datetime({}).optional().describe('Start Date range'), "end_date": zod.string().datetime({}).optional().describe('End Date range'), "workspace_id": zod.string().optional().describe('Workspace ID (optional)'), "conversation_id": zod.string().optional().describe('Conversation ID (optional)'), "language": zod.string().optional().describe('Language (optional)'), "type": zod.enum(['channel', 'prerecorded', 'voicememo', 'stored', 'welcome']).optional().describe('Type (optional)'), "folder_id": zod.string().optional().describe('Folder ID (optional)'), "user_ids": zod.array(zod.string()).optional().describe('User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included.') })
- Zod schema for the response structure (listMessagesResponse) of the underlying API call.export const listMessagesResponse = zod.object({ "page": zod.number().min(1).default(listMessagesResponsePageDefault), "size": zod.number().min(1).max(listMessagesResponseSizeMax).default(listMessagesResponseSizeDefault).describe('Max number of results per page is: **50**'), "sort_direction": zod.enum(['ASC', 'DESC']).default(listMessagesResponseSortDirectionDefault).describe('The field used to sort results is **Creation Date**'), "total": zod.number().describe('Total number of records by applied filters (if any)'), "results_count": zod.number().describe('Results count (paginated results)'), "has_next_page": zod.boolean().describe('If there is more data available (omitted by pagination)'), "filters": zod.object({ "start_date": zod.string().datetime({}).optional().describe('Start Date range'), "end_date": zod.string().datetime({}).optional().describe('End Date range'), "workspace_id": zod.string().optional().describe('Workspace ID (optional)'), "conversation_id": zod.string().optional().describe('Conversation ID (optional)'), "language": zod.string().optional().describe('Language (optional)'), "type": zod.enum(['channel', 'prerecorded', 'voicememo', 'stored', 'welcome']).optional().describe('Type (optional)'), "folder_id": zod.string().optional().describe('Folder ID (optional)'), "user_ids": zod.array(zod.string()).optional().describe('User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included.') }).optional().describe('Filters'), "results": zod.array(zod.object({ "id": zod.string().describe('ID'), "name": zod.string().optional().describe('Name'), "link": zod.string().describe('Link to Message'), "creator_id": zod.string().describe('Creator ID'), "conversation_id": zod.string().optional().describe('Conversation ID'), "workspace_id": zod.string().optional().describe('Workspace ID'), "created_at": zod.string().datetime({}), "last_updated_at": zod.string().datetime({}), "deleted_at": zod.string().datetime({}).optional(), "duration_ms": zod.number().describe('The length of the message in milliseconds'), "audio_url": zod.string().optional().describe('The URL for the message audio file'), "audio_stream_url": zod.string().optional().describe('The URL for the message audio stream'), "transcript": zod.string().optional().describe('Transcript of the message'), "ai_summary": zod.string().optional().describe('AI Summary generated of the message'), "waveform_url": zod.string().optional().describe('The URL for the message waveform image'), "reply_count": zod.number().describe('The number of replies to the message'), "parent_message_id": zod.string().optional().describe('Parent Message unique ID (only available for replies)'), "language": zod.string().default(listMessagesResponseResultsItemLanguageDefault).describe('Language for the message (Transcript, AI summary, Audio...)'), "status": zod.enum(['offline', 'paused', 'processing', 'scheduled', 'active', 'deleted', 'account-deleted', 'initializing', 'inprogress', 'canceled', 'failed']).describe('Current status of the Message'), "type": zod.enum(['channel', 'prerecorded', 'voicememo', 'stored', 'welcome']).describe('Type of the Message'), "attachments": zod.array(zod.object({ "id": zod.string(), "creator_id": zod.string(), "created_at": zod.string().datetime({}), "type": zod.enum(['link', 'file', 'location', 'ai-response-id', 'ai-prompt-id']), "link": zod.string(), "active_begin": zod.string().datetime({}).optional(), "active_end": zod.string().datetime({}).optional(), "filename": zod.string().optional(), "mime_type": zod.string().optional(), "length_in_bytes": zod.number().optional(), "location": zod.object({ }).optional() })).optional().describe('List of attachments for the message'), "share_link_id": zod.string().optional().describe('Share Link ID to a message'), "folder_id": zod.string().optional().describe('Folder ID where the message is stored') })).describe('List of Messages') })
- TypeScript type definition matching the input parameters for listMessages.export type ListMessagesParams = { page?: number; /** * Max number of results per page is: **50** */ size?: number; /** * The field used to sort results is **Creation Date** */ sort_direction?: ListMessagesSortDirection; /** * Start Date range */ start_date?: string; /** * End Date range */ end_date?: string; /** * Workspace ID (optional) */ workspace_id?: string; /** * Conversation ID (optional) */ conversation_id?: string; /** * Language (optional) */ language?: string; /** * Type (optional) */ type?: ListMessagesType; /** * Folder ID (optional) */ folder_id?: string; /** * User IDs (optional). List of user IDs to filter messages by. If not provided, all users will be included. */ user_ids?: string[]; };