Merge Unified's WhatsApp integration Merge Agent Handler's WhatsApp MCP server

Connect your AI Agents to WhatsApp in minutes

Merge lets you securely connect your agents to WhatsApp and thousands of tools instantly

Start building for free

Read docs

Learn more about Merge Agent Handler

Available tools

get_conversation_analytics

Get WhatsApp conversation analytics (volume and cost per category/direction/type) for a time range. start and end are Unix timestamps in seconds; start must be within the past 365 days. Granularity: HALF_HOUR, DAILY, or MONTHLY.

get_pricing_analytics

Get WhatsApp pricing analytics (cost and volume per pricing category and type) for a time range. Granularity: HALF_HOUR, DAILY, or MONTHLY.

list_blocked_users

List WhatsApp users blocked from messaging the credential's phone number. Cursor-paginated.

block_users

Block one or more WhatsApp users from messaging the credential's phone number. Pass user phone numbers in E.164 without '+'.

unblock_users

Unblock one or more previously-blocked WhatsApp users on the credential's phone number.

get_business_profile

Get the WhatsApp business profile for the credential's phone number. Returns about, address, description, email, websites, vertical, and profilepictureurl.

update_business_profile

Update the WhatsApp business profile (about, address, description, email, websites, vertical). Only provided fields are updated. Profile picture requires a handle from Meta's Resumable Upload API.

upload_media

Upload a media file (image/video/audio/document/sticker, up to 100MB) to WhatsApp. Returns a mediaid usable in sendmedia_message. Media persists for 30 days before being auto-deleted.

get_media_url

Get a signed download URL and metadata for a WhatsApp media ID. The URL is valid for ~5 minutes and must be fetched with the same access token.

delete_media

Delete a WhatsApp media object by ID. Deletion is permanent.

send_text_message

Send a plain-text WhatsApp message. The recipient must have messaged the business in the last 24 hours, or you must use sendtemplatemessage instead. Returns the accepted message ID.

send_media_message

Send a WhatsApp media message (image, video, audio, document, or sticker). Provide either mediaid (from uploadmedia) or a public HTTPS link. Caption supported for image/video/document; filename supported for document.

send_location_message

Send a location pin as a WhatsApp message. Requires latitude and longitude; name and address are optional.

send_contacts_message

Send one or more vCard-style contacts as a WhatsApp message. Each contact must have a 'name' object; phones/emails/addresses/org/urls are optional. Follows WhatsApp's contacts message schema.

send_template_message

Send an approved WhatsApp template message. Use listmessagetemplates to find valid names and languages. Components follow WhatsApp's template parameters schema.

send_interactive_message

Send a WhatsApp interactive message (reply buttons, list picker, CTA URL button, flow, catalog, product). Pass the full interactive payload including 'type' and type-specific action/body/header/footer.

send_reaction

React to an incoming WhatsApp message with a single emoji. Pass an empty emoji string to remove an existing reaction.

mark_message_as_read

Mark an incoming WhatsApp message as read. Optionally also send a typing indicator so the recipient sees that the business is composing a reply.

list_phone_numbers

List all WhatsApp phone numbers on the WhatsApp Business Account. Cursor-paginated — pass page_info.cursor as 'after' for the next page.

get_phone_number

Get details of a WhatsApp phone number. Defaults to the credential's configured phone number ID. Returns displayphonenumber, verifiedname, qualityrating, status, throughput, and messaging tier.

list_message_templates

List message templates on the WhatsApp Business Account. Use nameorcontent to search by substring; name is exact-match. Filter by name, language, status, or category. Cursor-paginated.

get_message_template

Get a single WhatsApp message template by ID. Use listmessagetemplates to find template IDs.

create_message_template

Create a WhatsApp message template (AUTHENTICATION, MARKETING, or UTILITY). Template goes through WhatsApp review before it can be used. Name must be lowercase letters/numbers/underscores; components follow WhatsApp's template schema.

update_message_template

Edit an existing WhatsApp message template. Edit rules vary by template status and field. Approved templates may be restricted to body/footer edits.

delete_message_template

Delete a WhatsApp message template. Without hsmid, deletes every language variant of the named template. Pass hsmid to delete only one language. Deletion is permanent.

validate_credential

Validate WhatsApp credentials by reading the WhatsApp Business Account. Returns success status and a human-readable message.

get_waba

Get WhatsApp Business Account details: name, currency, timezone, status, template namespace, verification status, country, and ownership type.

list_subscribed_apps

List apps subscribed to webhooks on the WhatsApp Business Account. Useful for confirming which Meta apps receive incoming message notifications.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}