MCP Tools Reference
Complete reference for all 11 MCP tools exposed by Pons.
Pons exposes 11 tools to MCP clients. Each tool requires either an API key or an OAuth access token with the appropriate scope.
Reading Tools
These tools require the read scope.
list_conversations
List recent WhatsApp conversations with contacts.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Max conversations to return (default 50) |
Returns: List of conversations with contact name, phone number, unread count, 24h window status, last message preview, and conversation ID.
list_unanswered
List conversations waiting for a reply — where the last message is from the customer.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | number | No | Max conversations to return (default 20) |
Returns: Conversations where the most recent message is inbound, with contact info, time since last message, window status, message text, and IDs.
get_conversation
Get a conversation with its recent messages.
| Parameter | Type | Required | Description |
|---|---|---|---|
conversationId | string | Yes | The conversation ID |
messageLimit | number | No | Max messages to return (default 50) |
Returns: Contact details, 24h window status, and message history with direction (← inbound, → outbound), timestamps, delivery status, and content.
search_messages
Search for messages containing specific text.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Text to search for in messages |
limit | number | No | Max results (default 20) |
Returns: Matching messages with contact info, timestamp, message text, and conversation ID.
list_templates
List available message templates for this account.
No parameters.
Returns: All templates with name, language, approval status, category, and ID. Templates must be created and approved in the Meta Business Suite.
Write Tools
These tools require the write scope.
mark_as_read
Mark a message as read (sends read receipt to the sender).
| Parameter | Type | Required | Description |
|---|---|---|---|
waMessageId | string | Yes | The WhatsApp message ID (wamid.xxx) to mark as read |
Returns: Confirmation that the message was marked as read.
send_reaction
React to a message with an emoji.
| Parameter | Type | Required | Description |
|---|---|---|---|
conversationId | string | Yes | The conversation ID |
phone | string | Yes | Phone number in E.164 format (e.g., +491234567890) |
waMessageId | string | Yes | The WhatsApp message ID to react to |
emoji | string | Yes | Emoji to react with (e.g., 👍, ❤️, 😂) |
Returns: Confirmation that the reaction was sent.
updateConversation
Update conversation metadata. Currently supports archiving and unarchiving chats.
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Recipient phone number in E.164 format (e.g., +491234567890) |
archived | boolean | Yes | true to archive, false to unarchive |
Returns: Confirmation with conversation ID and the updated archived state.
Send Tools
These tools require the send scope.
send_text
Send a text message to a WhatsApp contact. Requires an open 24-hour window.
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Phone number in E.164 format (e.g., +491234567890) |
text | string | Yes | Message text to send |
replyToMessageId | string | No | WhatsApp message ID to reply to |
Returns: Confirmation with the sent message ID. If the 24h window is closed, returns an error suggesting send_template instead.
send_media
Send a media file (image, document, video, or audio) to a WhatsApp contact. Requires an open 24-hour window.
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Phone number in E.164 format (e.g., +491234567890) |
url | string | Yes | Publicly accessible URL of the file to send |
mimeType | string | Yes | MIME type of the file (e.g., image/jpeg, application/pdf, video/mp4) |
filename | string | No | Display filename for documents (e.g., report.pdf) |
caption | string | No | Caption to send with the media |
Returns: Confirmation with the sent message ID. The file type (image, video, audio, document) is auto-detected from the MIME type.
send_template
Send a pre-approved template message. Use this for first contact or when the 24-hour messaging window is closed.
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes | Phone number in E.164 format |
templateName | string | Yes | Name of the approved template |
templateLanguage | string | Yes | Language code (e.g., en_US, de_DE) |
components | object | No | Template components (header, body, button variables) as JSON |
Returns: Confirmation with template name and message ID.
24-Hour Window
WhatsApp enforces a 24-hour messaging window:
- When a customer sends you a message, a 24-hour window opens
- During this window, you can send free-form messages using
send_text - After the window closes, you can only send pre-approved template messages using
send_template - When the customer responds to a template, a new 24-hour window opens
Use list_conversations or list_unanswered to check the window status. The response includes [24h window open] or [window closed — template required].