TL;DR
The Mumble API has over 30 endpoints that give you full control of your account from code — creating customers, sending free-form messages, sending templates with variables, assigning to agents and teams, creating new templates, checking the conversation window, and more. In this article you’ll find how to generate an API key, the authentication structure (important — not a bearer token!), cURL examples for sending, and the difference between a free-form message and a template in the API.
When to use the API instead of Make or Zapier
There are three ways to connect Mumble to an external system: Make.com, Zapier, and the direct API. When it’s worth moving to the API:
- Deep integration — your own app that uses Mumble data as part of its core logic
- Performance — sending thousands of messages in a short time, or an instant response with no overhead from an intermediary platform
- Security — keeping sensitive data inside a single system, without passing through third-party services
- Control — access to endpoints not exposed in Make/Zapier (creating templates, assigning to specific agents, custom fields)
For everything else — simple automations, connecting ready-made services, creating leads from a form — Make or Zapier are more convenient and don’t require developers.
Initial setup
Generating an API key
- Open the right-hand menu and click Settings.
- Go to the Technical profile tab.
- In the API key section, click Copy.
This key is the “password” of your sending account. Whoever holds it can send messages from your number, read conversations, and create customers. Don’t store it in open documents, in a public Git repo, or anywhere that isn’t an encrypted vault. If the key leaks, go back to the Technical profile and click Copy again — this issues a new key and invalidates the old one.
Base URL
All endpoints originate from https://app.mumble.co.il/mumbleapi/
Authentication — important!
Mumble does not use Authorization: Bearer <token> like most APIs. Instead, there’s a custom header:
Mumble-Api-Key: YOUR_TOKEN_HERE Content-Type: application/json
Both of these headers are required on every request. If you try to send the key as a Bearer token, you’ll get a 401 Unauthorized.
Sending messages
Free-form message – POST /send-text-message
Sends free-form text to a customer. Must be within the 24-hour conversation window.
curl -X POST https://app.mumble.co.il/mumbleapi/send-text-message \
-H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"customer_phone": "972501234567",
"text": "Thanks for reaching out! How can I help?"
}'
Required parameters: customer_phone (international format with no + and no leading 0), text.
Response on success:
{"id": 1, "message_wa_id": "wamid.abc123", "success": true}
Response when the conversation window is closed:
{"error": true, "is_active": false, "message": "Conversation is closed"}
Template – POST /send-template
Sends an approved template with no variables. Valid at any time, including outside the conversation window.
curl -X POST https://app.mumble.co.il/mumbleapi/send-template \
-H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"customer_phone": "972501234567",
"template_id": "template-uuid-here"
}'
Required parameters: customer_phone, template_id.
Note: template_id is the template’s UUID, not its name. To get the UUID, use GET /get-templates, which returns all the templates in the account along with their ids.
Template with variables – POST /send-template-text-variable
Sends a template while injecting values into {{1}}, {{2}}, {{3}}, etc.
curl -X POST https://app.mumble.co.il/mumbleapi/send-template-text-variable \
-H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"customer_phone": "972501234567",
"template_id": "template-uuid-here",
"variable": ["Daniel", "ORD-12345", "5 business days"]
}'
Required parameters: customer_phone, template_id, variable (an array).
The order of the values in variable matches the order of {{1}}, {{2}}, {{3}} in the template’s body. Three variables in a template = three values in the array.
Checking whether the conversation window is open – GET /is-active-conv
Before sending a free-form message, it’s worth checking whether the conversation window is open. Otherwise you’ll get a 400 error.
curl -X GET https://app.mumble.co.il/mumbleapi/is-active-conv \
-H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"customer_phone": "972501234567"}'
Response:
{"is_active": true, "success": true}
The recommended pattern in an automation: call is-active-conv. If is_active is true, send free-form text via send-text-message. If false, send a template via send-template or send-template-text-variable. That way the same code works in every situation, both inside the window and outside it.
Usage limits
Mumble counts your API calls against a monthly quota that depends on your plan (you can see the current quota on the main page, in the API messages sent meter). As you approach the quota, you can buy an additional operations pack via Upgrade operations or move to a higher plan.
Beyond the monthly quota, you also need to account for Meta’s rate limits — not Mumble’s. Meta imposes limits on how many messages you can send per unit of time, and those limits depend on the sending account’s Quality Rating and its current Tier. Practical guidance:
- When sending in large volumes (an automated campaign from the API), add a small delay between sends — half a second to a second between messages is safe.
- Handle 429 (Too Many Requests) errors if you get them, with retry and exponential backoff.
- Don’t open thousands of parallel connections. 2–5 workers running in series is enough.
Common mistakes
Using Authorization: Bearer instead of Mumble-Api-Key
What happens: you get a 401 Unauthorized on every request, even when the key is correct.
Fix: Mumble doesn’t use a bearer token. The header must be exactly Mumble-Api-Key: YOUR_TOKEN_HERE. Many HTTP libraries automatically try to wrap it in Bearer — make sure you sent a raw header.
Wrong phone number format
What happens: you get a 400 or 404 (Customer not found) even though the customer exists.
Fix: WhatsApp requires international format with no + and no leading 0. Israeli: 972501234567. American: 15551234567. British: 447700900123. Normalize numbers before sending.
Using the template name instead of the template_id
What happens: you send “template_id”: “welcome_message” and get a 404 or 400.
Fix: template_id is a UUID, not a name. First use GET /get-templates to get the list, find the template you want by name, and take its id.
Sending a free-form message without checking the conversation window
What happens: if the customer hasn’t written in the last 24 hours, you get {“error”: true, “is_active”: false, “message”: “Conversation is closed”}. The message isn’t sent.
Fix: call is-active-conv first, or catch the error and send a template as a fallback. Don’t assume the window is open.
Not handling rate limits and transient errors
What happens: when sending in volume, some messages fail with 429 or 500 errors, and the automation moves on without retrying.
Fix: every serious API integration handles transient errors with retry + exponential backoff (1 second, 2, 4, 8). 4xx errors (other than 429) are problems with the request and shouldn’t be retried.
Related articles
- The 24-hour conversation window in WhatsApp Business
- When to use a template and when to use a free-form message
- Connecting Mumble to Make.com
- The full Mumble API documentation
The bottom line
The Mumble API is open to anyone who holds a key. The rules you must remember are Mumble-Api-Key as the header (not bearer), an international phone format with no +, and checking whether the conversation window is open before sending free-form text. Everything else is in the documentation.