monica_manage_conversation
Manage messages within Monica CRM conversations by listing, creating, updating, or deleting them to organize communication records.
Instructions
List, inspect, create, update, delete, or manage messages inside Monica conversations. Provide either contactFieldTypeId or contactFieldTypeName for the channel.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| conversationId | No | ||
| messageId | No | ||
| contactId | No | ||
| limit | No | ||
| page | No | ||
| payload | No | ||
| messagePayload | No |
Implementation Reference
- src/tools/modules/communications.ts:52-393 (registration)Registers the 'monica_manage_conversation' tool using server.registerTool, providing title, description, input schema, and the inline asynchronous handler function.server.registerTool( 'monica_manage_conversation', { title: 'Manage Monica conversations', description: 'List, inspect, create, update, delete, or manage messages inside Monica conversations. Provide either contactFieldTypeId or contactFieldTypeName for the channel.', inputSchema: { action: z.enum([ 'list', 'get', 'create', 'update', 'delete', 'addMessage', 'updateMessage', 'deleteMessage' ]), conversationId: z.number().int().positive().optional(), messageId: z.number().int().positive().optional(), contactId: z.number().int().positive().optional(), limit: z.number().int().min(1).max(100).optional(), page: z.number().int().min(1).optional(), payload: conversationPayloadSchema.optional(), messagePayload: conversationMessagePayloadSchema.optional() } }, async ({ action, conversationId, messageId, contactId, limit, page, payload, messagePayload }) => { switch (action) { case 'list': { const response = await client.listConversations({ contactId, limit, page }); const conversations = response.data.map(normalizeConversation); const scope = contactId ? `contact ${contactId}` : 'your account'; const textSummary = conversations.length ? `Found ${conversations.length} conversation${conversations.length === 1 ? '' : 's'} for ${scope}.` : `No conversations found for ${scope}.`; return { content: [ { type: 'text' as const, text: textSummary } ], structuredContent: { action, contactId, conversations, pagination: { currentPage: response.meta.current_page, lastPage: response.meta.last_page, perPage: response.meta.per_page, total: response.meta.total } } }; } case 'get': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when retrieving a conversation.' } ] }; } const response = await client.getConversation(conversationId); const conversation = normalizeConversation(response.data); const channel = conversation.channel.name; const contactName = conversation.contact?.name || `Contact ${conversation.contactId}`; return { content: [ { type: 'text' as const, text: `Conversation ${conversationId} via ${channel} with ${contactName}. ${conversation.messages.length} message(s).` } ], structuredContent: { action, conversationId, conversation } }; } case 'create': { if (!payload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide happenedAt, contactFieldTypeId or contactFieldTypeName, and contactId when creating a conversation.' } ] }; } let input: CreateConversationPayload; try { input = await toConversationCreatePayload(client, payload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.createConversation(input); const conversation = normalizeConversation(response.data); logger.info({ conversationId: conversation.id, contactId: conversation.contactId }, 'Created Monica conversation'); return { content: [ { type: 'text' as const, text: `Created conversation ${conversation.id} for contact ${conversation.contactId}.` } ], structuredContent: { action, conversation } }; } case 'update': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when updating a conversation.' } ] }; } if (!payload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide happenedAt and channel info when updating a conversation.' } ] }; } let input: UpdateConversationPayload; try { input = toConversationUpdatePayload(payload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.updateConversation(conversationId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId }, 'Updated Monica conversation'); return { content: [ { type: 'text' as const, text: `Updated conversation ${conversationId}.` } ], structuredContent: { action, conversationId, conversation } }; } case 'delete': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when deleting a conversation.' } ] }; } const result = await client.deleteConversation(conversationId); logger.info({ conversationId }, 'Deleted Monica conversation'); return { content: [ { type: 'text' as const, text: `Deleted conversation ID ${conversationId}.` } ], structuredContent: { action, conversationId, result } }; } case 'addMessage': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when adding a message.' } ] }; } if (!messagePayload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide message details when adding to a conversation.' } ] }; } let input: CreateConversationMessagePayload; try { input = toConversationMessageCreatePayload(messagePayload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.addConversationMessage(conversationId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId, contactId: input.contactId }, 'Added Monica conversation message'); return { content: [ { type: 'text' as const, text: `Added message to conversation ${conversationId}.` } ], structuredContent: { action, conversationId, conversation } }; } case 'updateMessage': { if (!conversationId || !messageId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId and messageId when updating a message.' } ] }; } if (!messagePayload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide message details when updating a conversation message.' } ] }; } let input: UpdateConversationMessagePayload; try { input = toConversationMessageUpdatePayload(messagePayload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.updateConversationMessage(conversationId, messageId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId, messageId }, 'Updated Monica conversation message'); return { content: [ { type: 'text' as const, text: `Updated message ${messageId} in conversation ${conversationId}.` } ], structuredContent: { action, conversationId, messageId, conversation } }; } case 'deleteMessage': { if (!conversationId || !messageId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId and messageId when deleting a conversation message.' } ] }; } const result = await client.deleteConversationMessage(conversationId, messageId); logger.info({ conversationId, messageId }, 'Deleted Monica conversation message'); return { content: [ { type: 'text' as const, text: `Deleted message ${messageId} from conversation ${conversationId}.` } ], structuredContent: { action, conversationId, messageId, result } }; } default: return { isError: true as const, content: [ { type: 'text' as const, text: `Unsupported action: ${action}.` } ] }; } } );
- The inline handler function that handles all tool actions by switching on 'action' and calling appropriate MonicaClient methods for listing, retrieving, creating, updating, deleting conversations and managing their messages.async ({ action, conversationId, messageId, contactId, limit, page, payload, messagePayload }) => { switch (action) { case 'list': { const response = await client.listConversations({ contactId, limit, page }); const conversations = response.data.map(normalizeConversation); const scope = contactId ? `contact ${contactId}` : 'your account'; const textSummary = conversations.length ? `Found ${conversations.length} conversation${conversations.length === 1 ? '' : 's'} for ${scope}.` : `No conversations found for ${scope}.`; return { content: [ { type: 'text' as const, text: textSummary } ], structuredContent: { action, contactId, conversations, pagination: { currentPage: response.meta.current_page, lastPage: response.meta.last_page, perPage: response.meta.per_page, total: response.meta.total } } }; } case 'get': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when retrieving a conversation.' } ] }; } const response = await client.getConversation(conversationId); const conversation = normalizeConversation(response.data); const channel = conversation.channel.name; const contactName = conversation.contact?.name || `Contact ${conversation.contactId}`; return { content: [ { type: 'text' as const, text: `Conversation ${conversationId} via ${channel} with ${contactName}. ${conversation.messages.length} message(s).` } ], structuredContent: { action, conversationId, conversation } }; } case 'create': { if (!payload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide happenedAt, contactFieldTypeId or contactFieldTypeName, and contactId when creating a conversation.' } ] }; } let input: CreateConversationPayload; try { input = await toConversationCreatePayload(client, payload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.createConversation(input); const conversation = normalizeConversation(response.data); logger.info({ conversationId: conversation.id, contactId: conversation.contactId }, 'Created Monica conversation'); return { content: [ { type: 'text' as const, text: `Created conversation ${conversation.id} for contact ${conversation.contactId}.` } ], structuredContent: { action, conversation } }; } case 'update': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when updating a conversation.' } ] }; } if (!payload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide happenedAt and channel info when updating a conversation.' } ] }; } let input: UpdateConversationPayload; try { input = toConversationUpdatePayload(payload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.updateConversation(conversationId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId }, 'Updated Monica conversation'); return { content: [ { type: 'text' as const, text: `Updated conversation ${conversationId}.` } ], structuredContent: { action, conversationId, conversation } }; } case 'delete': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when deleting a conversation.' } ] }; } const result = await client.deleteConversation(conversationId); logger.info({ conversationId }, 'Deleted Monica conversation'); return { content: [ { type: 'text' as const, text: `Deleted conversation ID ${conversationId}.` } ], structuredContent: { action, conversationId, result } }; } case 'addMessage': { if (!conversationId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId when adding a message.' } ] }; } if (!messagePayload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide message details when adding to a conversation.' } ] }; } let input: CreateConversationMessagePayload; try { input = toConversationMessageCreatePayload(messagePayload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.addConversationMessage(conversationId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId, contactId: input.contactId }, 'Added Monica conversation message'); return { content: [ { type: 'text' as const, text: `Added message to conversation ${conversationId}.` } ], structuredContent: { action, conversationId, conversation } }; } case 'updateMessage': { if (!conversationId || !messageId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId and messageId when updating a message.' } ] }; } if (!messagePayload) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide message details when updating a conversation message.' } ] }; } let input: UpdateConversationMessagePayload; try { input = toConversationMessageUpdatePayload(messagePayload); } catch (error) { return { isError: true as const, content: [ { type: 'text' as const, text: (error as Error).message } ] }; } const response = await client.updateConversationMessage(conversationId, messageId, input); const conversation = normalizeConversation(response.data); logger.info({ conversationId, messageId }, 'Updated Monica conversation message'); return { content: [ { type: 'text' as const, text: `Updated message ${messageId} in conversation ${conversationId}.` } ], structuredContent: { action, conversationId, messageId, conversation } }; } case 'deleteMessage': { if (!conversationId || !messageId) { return { isError: true as const, content: [ { type: 'text' as const, text: 'Provide conversationId and messageId when deleting a conversation message.' } ] }; } const result = await client.deleteConversationMessage(conversationId, messageId); logger.info({ conversationId, messageId }, 'Deleted Monica conversation message'); return { content: [ { type: 'text' as const, text: `Deleted message ${messageId} from conversation ${conversationId}.` } ], structuredContent: { action, conversationId, messageId, result } }; } default: return { isError: true as const, content: [ { type: 'text' as const, text: `Unsupported action: ${action}.` } ] }; } }
- Zod schemas for validating conversationPayload and conversationMessagePayload inputs used in the tool's inputSchema.const conversationPayloadSchema = z.object({ happenedAt: z .string() .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'happenedAt must use YYYY-MM-DD format.') .optional(), contactFieldTypeId: z.number().int().positive().optional(), contactFieldTypeName: z.string().min(1).max(255).optional(), contactId: z.number().int().positive().optional() }); type ConversationPayloadForm = z.infer<typeof conversationPayloadSchema>; const conversationMessagePayloadSchema = z.object({ writtenAt: z .string() .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'writtenAt must use YYYY-MM-DD format.') .optional(), writtenByMe: z.boolean().optional(), content: z.string().min(1).max(1_000_000).optional(), contactId: z.number().int().positive().optional() }); type ConversationMessagePayloadForm = z.infer<typeof conversationMessagePayloadSchema>; const callPayloadSchema = z.object({ calledAt: z .string() .regex(/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/u, 'calledAt must use YYYY-MM-DD format.') .optional(), contactId: z.number().int().positive().optional(), content: z.string().max(1_000_000).optional().nullable() }); type CallPayloadForm = z.infer<typeof callPayloadSchema>;
- Helper functions to transform and validate form payloads into API payloads for creating/updating conversations and messages, including resolving contact field types.async function toConversationCreatePayload( client: ToolRegistrationContext['client'], payload: ConversationPayloadForm ): Promise<CreateConversationPayload> { if (!payload.happenedAt) { throw new Error('Provide happenedAt when creating a conversation.'); } if (typeof payload.contactId !== 'number') { throw new Error('Provide contactId when creating a conversation.'); } const contactFieldTypeId = await resolveContactFieldTypeId(client, { contactFieldTypeId: payload.contactFieldTypeId, contactFieldTypeName: payload.contactFieldTypeName }); return { happenedAt: payload.happenedAt, contactFieldTypeId, contactId: payload.contactId }; } function toConversationUpdatePayload(payload: ConversationPayloadForm): UpdateConversationPayload { if (!payload.happenedAt) { throw new Error('Provide happenedAt when updating a conversation.'); } return { happenedAt: payload.happenedAt }; } function toConversationMessageCreatePayload( payload: ConversationMessagePayloadForm ): CreateConversationMessagePayload { if ( typeof payload.contactId !== 'number' || !payload.writtenAt || typeof payload.writtenByMe !== 'boolean' || !payload.content ) { throw new Error('Provide contactId, writtenAt, writtenByMe, and content when adding a conversation message.'); } return { contactId: payload.contactId, writtenAt: payload.writtenAt, writtenByMe: payload.writtenByMe, content: payload.content }; } function toConversationMessageUpdatePayload( payload: ConversationMessagePayloadForm ): UpdateConversationMessagePayload { if ( typeof payload.contactId !== 'number' || !payload.writtenAt || typeof payload.writtenByMe !== 'boolean' || !payload.content ) { throw new Error('Provide contactId, writtenAt, writtenByMe, and content when updating a conversation message.'); } return { contactId: payload.contactId, writtenAt: payload.writtenAt, writtenByMe: payload.writtenByMe, content: payload.content }; }