WAHA MCP Server

Instructions

Implementation Reference

• src/index.ts:1240-1267 (handler)

  Main handler function for 'waha_get_messages' tool. Extracts parameters, calls WAHAClient.getChatMessages, formats output using formatMessages, and returns formatted text content.

  private async handleGetMessages(args: any) {
    const chatId = args.chatId;
    const limit = args.limit || 10;
    const offset = args.offset;
    const downloadMedia = args.downloadMedia || false;
  
    if (!chatId) {
      throw new Error("chatId is required");
    }
  
    const messages = await this.wahaClient.getChatMessages({
      chatId,
      limit,
      offset,
      downloadMedia,
    });
  
    const formattedResponse = formatMessages(messages);
  
    return {
      content: [
        {
          type: "text",
          text: formattedResponse,
        },
      ],
    };
  }

• src/index.ts:88-113 (schema)

  Input schema and description definition for the 'waha_get_messages' tool, returned by ListToolsRequestHandler.

  name: "waha_get_messages",
  description: "Get messages from a specific WhatsApp chat. Returns message content, sender, timestamp, and status. Default limit is 10 messages.",
  inputSchema: {
    type: "object",
    properties: {
      chatId: {
        type: "string",
        description: "Chat ID to get messages from (format: number@c.us for individual, number@g.us for group)",
      },
      limit: {
        type: "number",
        description: "Number of messages to retrieve (default: 10, max: 100)",
        default: 10,
      },
      offset: {
        type: "number",
        description: "Offset for pagination",
      },
      downloadMedia: {
        type: "boolean",
        description: "Download media files (default: false)",
        default: false,
      },
    },
    required: ["chatId"],
  },

• src/index.ts:1054-1055 (registration)

  Tool registration/dispatch in the CallToolRequestHandler switch statement.

    return await this.handleGetMessages(args);
  case "waha_send_message":

• src/tools/formatters.ts:92-102 (helper)

  Helper function to format the list of messages into human-readable text for LLM consumption.

  export function formatMessages(messages: Message[]): string {
    if (messages.length === 0) {
      return "No messages found.";
    }
  
    const sections = messages.map((msg, index) => {
      return `\n[Message ${index + 1}]\n${formatMessage(msg)}`;
    });
  
    return `Found ${messages.length} message${messages.length > 1 ? 's' : ''}:\n${sections.join('\n')}`;
  }

• src/client/waha-client.ts:144-187 (helper)

  Underlying WAHAClient method that performs the actual API call to retrieve messages from WAHA server.

  async getChatMessages(params: GetMessagesParams): Promise<Message[]> {
    const {
      chatId,
      limit = 10,
      offset,
      downloadMedia = false,
      filters,
    } = params;
  
    if (!chatId) {
      throw new WAHAError("chatId is required");
    }
  
    const queryParams: Record<string, any> = {
      limit: Math.min(limit, 100), // Max 100
      offset,
      downloadMedia,
    };
  
    // Add filters if provided
    if (filters) {
      if (filters.timestampLte !== undefined) {
        queryParams["filter.timestamp.lte"] = filters.timestampLte;
      }
      if (filters.timestampGte !== undefined) {
        queryParams["filter.timestamp.gte"] = filters.timestampGte;
      }
      if (filters.fromMe !== undefined) {
        queryParams["filter.fromMe"] = filters.fromMe;
      }
      if (filters.ack !== undefined) {
        queryParams["filter.ack"] = filters.ack;
      }
    }
  
    const queryString = this.buildQueryString(queryParams);
    const endpoint = `/api/${this.session}/chats/${encodeURIComponent(
      chatId
    )}/messages${queryString}`;
  
    return this.request<Message[]>(endpoint, {
      method: "GET",
    });
  }