Mumble API Reference

Create a new customer. Marketing attribution fields (UTMs, click IDs, device info) and custom fields can be attached at creation. If the phone number already exists, the call does not fail: labels from source are added, the bot setting is applied and attribution fields are updated, but name and email are left unchanged (use edit-customer for those).

Update an existing customer. Fields not sent are unchanged, and empty values are ignored (a field can't be cleared through the API). Any key that isn't a standard field becomes a custom field on the customer (max 50 per account).

Permanently delete a customer and their related data. This can't be undone.

Get a single customer record: contact details, conversation status, all attribution fields, the customer's labels, and custom fields. For customers who came from a Click-to-WhatsApp ad, ctwa_clid holds the ad click ID (useful for sending conversions back to Meta); it is null otherwise. Custom fields are returned as top-level keys inside customer, by their field name.

Paginated list of all customers, 250 per page. Each item has name, phone and email; use get-customer for the full record. Parameters can be sent in the JSON body or the query string (?page=2&sort_by=date_created).

Update a customer's conversation status. The change is applied in the background right after the response, and triggers any automations set on status changes.

Route a customer's conversations to a specific agent, by ID or by name. Send "agent_id": "-1" to unassign the customer.

Route a customer's conversations to a team, by ID or by name.

Tag a customer with a label. The label must already exist; create it first with add-new-label. Label automations run after the response. Adding a customer to the Black List label blocks all template sends to them.

Remove a label from a customer. Customers can't be removed from the Black List label through the API; do that in the Mumble app.

Create a new label (list) in your account. A random color is assigned.

Delete a label. Customers in it are not deleted; they just lose the label.

List all labels in your account, as an array of label names.

Send a free-form text message. Requires an open 24-hour conversation window (see is-active-conv); outside it, send a template. Rate limited to 5/sec, 100/min, 2,000/hour per API key.

Send a media message (image, video, audio, document). Supports two modes: (A) file upload via multipart/form-data, or (B) public URL via JSON with media_url. Requires an open 24-hour window. The file type is taken from the file name's extension. Supported: jpg, jpeg, png, webp, mp4, mov, mp3, ogg, m4a, wav, opus, pdf, doc, docx, xls, xlsx, ppt, pptx, txt.

curl -X POST https://app.mumble.co.il/mumbleapi/send-media-message \
  -H "Mumble-Api-Key: your-api-key-here" \
  -F "file=@./brochure.pdf" \
  -F "customer_phone=972501234567" \
  -F "caption=Our brochure"

Send an approved message template that has no body variables. Use this to start a conversation outside the 24-hour window. Templates with {{1}}-style variables are rejected here; use send-template-text-variable. Rate limited to 5/sec, 100/min, 2,000/hour per API key.

Send an approved template that has body variables ({{1}}, {{2}}, …). Pass the values in order. Templates without variables are rejected here; use send-template. For AUTHENTICATION (OTP) templates, the first value in variable is the code. Rate limited to 5/sec, 100/min, 2,000/hour per API key.

Each item in button_variable fills one button. A plain string fills a URL button's {{1}} suffix, and its position in the array is used as the button index. Buttons are counted from 0 in the order they appear on the template, including quick-reply and phone buttons. If the URL button isn't the first button, send an object with an explicit index:

"button_variable": [
  { "index": 1, "text": "order-12345" }
]

Other button types use an object with sub_type:

{ "sub_type": "copy_code", "index": 0, "code": "SAVE20" }
{ "sub_type": "quick_reply", "index": 0, "payload": "confirm" }

Fetch a single message by its WhatsApp ID (the message_wa_id returned when sending). The response contains the full stored message record; use status to track delivery.

Conversation history for a customer, oldest first, 250 messages per page. An unknown number returns an empty list. Parameters can be sent in the JSON body or the query string.

Check whether a customer's 24-hour conversation window is currently open. If is_active is false, you can only reach them with an approved template.

List all agents (sub-users) in your account. Note that the list key contains a space: "agent list". An account with no agents returns 404.

List all teams in your account. Note that the list key contains a space: "team list". An account with no teams returns 404.

List the flow chatbots in your account. Each id is the value to pass as bot_token. When Dolores AI is enabled, it's included as {"name": "Dolores AI", "id": "AI"}. Accounts with no flow chatbots get a 404.

Assign a chatbot to an existing customer. Pass a flow chatbot's ID (from get-bots), "AI" for Dolores AI, or "turn_off" to disable bots for the customer. A flow chatbot starts from its first step.

List the approved WhatsApp message templates in your account. Pending and rejected templates are not returned. Use id as template_id when sending.

Create a new WhatsApp message template. Templates must be approved by Meta before they can be used (they show up in get-templates once approved). Supports body variables ({{1}}, {{2}}, …), a static TEXT header or a media header (IMAGE, VIDEO, DOCUMENT), and buttons (URL, QUICK_REPLY, PHONE_NUMBER). Does not support header variables, MPM, Carousels, or Catalogs.

Simple text. Basic template with body text only, no variables

{
  "name": "welcome_message",
  "language": "en_US",
  "category": "MARKETING",
  "body": "Welcome to our store! We're glad to have you."
}

Body variables. Template with body variables {{1}}, {{2}}, {{3}}

{
  "name": "order_update",
  "language": "en_US",
  "category": "UTILITY",
  "body": "Hi {{1}}! Your order {{2}} will arrive on {{3}}.",
  "body_examples": ["John", "#12345", "Jan 30"]
}

Image header. Template with image header (no header variables supported)

{
  "name": "summer_sale",
  "language": "en_US",
  "category": "MARKETING",
  "header": {"format": "IMAGE"},
  "body": "Summer Sale! Get {{1}} off.",
  "body_examples": ["25%"],
  "media_url": "https://example.com/banner.jpg"
}

PDF document. Template with PDF document header

{
  "name": "invoice",
  "language": "en_US",
  "category": "UTILITY",
  "header": {"format": "DOCUMENT"},
  "body": "Hi {{1}}, your invoice {{2}} is attached.",
  "body_examples": ["Customer", "INV-001"],
  "media_url": "https://example.com/invoice.pdf"
}

Quick reply buttons. Template with two quick reply buttons

{
  "name": "order_received",
  "language": "en_US",
  "category": "UTILITY",
  "body": "We received your order {{1}}. Confirm?",
  "body_examples": ["#12345"],
  "buttons": [
    {"type": "QUICK_REPLY", "text": "Yes, Confirmed"},
    {"type": "QUICK_REPLY", "text": "No, Cancel"}
  ]
}

Dynamic URL button. The {{1}} at the end of the URL is filled at send time with button_variable in send-template-text-variable. example is required for Meta review.

{
  "name": "track_order",
  "language": "en_US",
  "category": "UTILITY",
  "body": "Hi {{1}}, your order has shipped.",
  "body_examples": ["John"],
  "buttons": [
    {"type": "URL", "text": "Track Order", "url": "https://example.com/track/{{1}}", "example": "order-12345"}
  ]
}

Call button. Template with phone number button (CTA)

{
  "name": "customer_support",
  "language": "en_US",
  "category": "UTILITY",
  "body": "Need help with order {{1}}? Call us!",
  "body_examples": ["#12345"],
  "buttons": [
    {"type": "PHONE_NUMBER", "text": "Call Support", "phone_number": "+972501234567"}
  ]
}

Complete example. Image header + body variables + footer + button

{
  "name": "order_complete",
  "language": "en_US",
  "category": "UTILITY",
  "header": {"format": "IMAGE"},
  "body": "Hi {{1}}! Order {{2}} confirmed. Total: {{3}}. Delivery: {{4}}.",
  "body_examples": ["John", "#12345", "$99.99", "Jan 30"],
  "footer": "Thank you for your purchase!",
  "buttons": [{"type": "QUICK_REPLY", "text": "Contact Support"}],
  "media_url": "https://example.com/order-banner.jpg"
}