whatsapp_send_document
Send document files to WhatsApp contacts or groups using either a URL or base64 encoded data. Specify recipients, file name, and optional caption to share documents through WhatsApp messaging.
Instructions
Send a document file to a WhatsApp contact or group. Can send from URL or base64.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| caption | No | Caption for the document (max 1024 characters) | |
| documentBase64 | No | Base64 encoded document data (alternative to documentURL) | |
| documentURL | No | URL of the document to send (alternative to documentBase64) | |
| fileName | Yes | Name of the document file (max 255 characters) | |
| isForwarded | No | Whether the message should be marked as forwarded | |
| mentions | No | List of phone numbers to mention in the caption | |
| replyTo | No | ID of the message being replied to | |
| to | Yes | Recipient phone number (with @s.whatsapp.net) or group ID (with @g.us) |
Input Schema (JSON Schema)
{
"properties": {
"caption": {
"description": "Caption for the document (max 1024 characters)",
"optional": true,
"type": "string"
},
"documentBase64": {
"description": "Base64 encoded document data (alternative to documentURL)",
"optional": true,
"type": "string"
},
"documentURL": {
"description": "URL of the document to send (alternative to documentBase64)",
"optional": true,
"type": "string"
},
"fileName": {
"description": "Name of the document file (max 255 characters)",
"type": "string"
},
"isForwarded": {
"description": "Whether the message should be marked as forwarded",
"optional": true,
"type": "boolean"
},
"mentions": {
"description": "List of phone numbers to mention in the caption",
"items": {
"type": "string"
},
"optional": true,
"type": "array"
},
"replyTo": {
"description": "ID of the message being replied to",
"optional": true,
"type": "string"
},
"to": {
"description": "Recipient phone number (with @s.whatsapp.net) or group ID (with @g.us)",
"type": "string"
}
},
"required": [
"to",
"fileName"
],
"type": "object"
}
Implementation Reference
- src/tools/messaging-advanced.ts:159-226 (handler)Core ToolHandler for 'whatsapp_send_document' that defines the tool metadata, input schema for MCP, and the handler function which validates input using Zod schema and sends the document via WSAPI client.export const sendDocumentMessage: ToolHandler = { name: 'whatsapp_send_document', description: 'Send a document file to a WhatsApp contact or group. Can send from URL or base64.', inputSchema: { type: 'object', properties: { to: { type: 'string', description: 'Recipient phone number (with @s.whatsapp.net) or group ID (with @g.us)', }, documentBase64: { type: 'string', description: 'Base64 encoded document data (alternative to documentURL)', optional: true, }, documentURL: { type: 'string', description: 'URL of the document to send (alternative to documentBase64)', optional: true, }, fileName: { type: 'string', description: 'Name of the document file (max 255 characters)', }, caption: { type: 'string', description: 'Caption for the document (max 1024 characters)', optional: true, }, mentions: { type: 'array', items: { type: 'string' }, description: 'List of phone numbers to mention in the caption', optional: true, }, replyTo: { type: 'string', description: 'ID of the message being replied to', optional: true, }, isForwarded: { type: 'boolean', description: 'Whether the message should be marked as forwarded', optional: true, }, }, required: ['to', 'fileName'], }, handler: async (args: any) => { const input = validateInput(sendDocumentMessageSchema, args) as SendDocumentMessageInput; logger.info('Sending document message', { to: input.to, fileName: input.fileName, hasCaption: !!input.caption, }); const result = await wsapiClient.post('/messages/document', input); logger.info('Document message sent successfully', { messageId: result.id }); return { success: true, messageId: result.id, message: 'Document message sent successfully', }; }, };
- src/validation/schemas.ts:73-84 (schema)Zod schema (sendDocumentMessageSchema) used for runtime input validation in the handler.export const sendDocumentMessageSchema = z.object({ to: chatIdSchema, documentBase64: base64Schema.optional(), documentURL: urlSchema.optional(), fileName: z.string().min(1).max(255), caption: z.string().max(1024).optional(), mentions: z.array(phoneNumberSchema).optional(), replyTo: messageIdSchema.optional(), isForwarded: z.boolean().optional(), }).refine(data => data.documentBase64 || data.documentURL, { message: "Either documentBase64 or documentURL must be provided", });
- src/tools/messaging.ts:541-555 (registration)Includes the advancedMessagingTools (containing whatsapp_send_document) into the messagingTools export, which is then imported and registered in src/server.ts.import { advancedMessagingTools } from './messaging-advanced.js'; // Export all messaging tools export const messagingTools = { sendTextMessage, sendImageMessage, sendVideoMessage, sendLinkMessage, sendReactionMessage, editMessage, deleteMessage, markMessageAsRead, starMessage, ...advancedMessagingTools, };
- src/server.ts:53-79 (registration)Generic registration logic in MCP server that registers all tools from messagingTools (which includes whatsapp_send_document) into the server's tool map.private setupToolHandlers(): void { logger.info('Setting up tool handlers'); // Register all tool categories const toolCategories = [ messagingTools, contactTools, groupTools, chatTools, sessionTools, instanceTools, accountTools, ]; toolCategories.forEach(category => { Object.values(category).forEach(tool => { if (this.tools.has(tool.name)) { logger.warn(`Tool ${tool.name} already registered, skipping`); return; } this.tools.set(tool.name, tool); logger.debug(`Registered tool: ${tool.name}`); }); }); logger.info(`Registered ${this.tools.size} tools`); }