Mumble API Documentation

Authentication

Every request must include your API key in the Mumble-Api-Key header. You can generate and manage keys from your Mumble account settings.

Mumble-Api-Key: your-api-key-here
Content-Type: application/json

Requests without a valid key return 401 Unauthorized.

Rate limits

Every endpoint is protected by two rate-limit buckets — whichever trips first returns 429 Too Many Requests:

Per API key — global default limits per authenticated key.
Per IP — a lower bucket applied to the calling IP address.

Messaging endpoints (send-text-message, send-template, send-template-text-variable) have an additional tighter limit of 5 requests per second, 100 per minute, and 2,000 per hour per API key.

If you need higher limits for production workloads, contact support@mumble.co.il.

Errors & conventions

All responses are JSON. Successful responses include "success": true. Errors include "error": true and a "message" field.

Common status codes:

Code	Meaning
`200`	Request succeeded
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — invalid or missing API key, or blocked usage
`404`	Resource not found (customer, label, template, agent, team, bot, or message)
`409`	Conflict — e.g. a label with that name already exists
`429`	Rate limit hit
`500`	Unexpected server error — retry with backoff

Phone numbers should be sent as international digits without +, spaces, or dashes (e.g. 972501234567). Non-digit characters are stripped server-side.

Customers

POST /mumbleapi/add-new-customer Create a new customer.

Create a new customer. Marketing attribution fields (UTMs, click IDs, device info) can be attached at creation.

Request fields

customer_phonestringrequired

E.164-style phone digits, e.g. 972501234567.

namestringoptional

Display name.

emailstringoptional

Customer email.

sourcestringoptional

Comma-separated label names — becomes tags. If none provided, the customer is added to "New Leads".

bot_tokenstringoptional

Assign a chatbot at creation: a flow chatbot’s bot ID (from the chatbot’s settings), "AI" for Dolores AI, or "turn_off" to disable bots for this customer.

*tracking fields*stringoptional

See Marketing Attribution Fields.

Example requestJSON

{
  "customer_phone": "972501234567",
  "name": "John Doe",
  "email": "john@example.com",
  "source": "web",
  "bot_token": "AI",
  "utm_source": "google",
  "utm_campaign": "summer_sale"
}

Example success responseJSON

{
  "success": true,
  "message": "added successfully"
}

Responses

200Customer added

400Phone number is required.

400Failed to add customer due to invalid input

401Unauthorized

500An unexpected error occurred

POST /mumbleapi/edit-customer Update an existing customer.

Update an existing customer. Fields not sent are unchanged. Any extra keys not in the standard field list become custom fields on the customer (max 15 per account).

Request fields

customer_phonestringrequired

namestringoptional

emailstringoptional

sourcestringoptional

Comma-separated labels.

bot_tokenstringoptional

*custom fields*anyoptional

Any additional keys are stored as custom fields (max 15).

Example requestJSON

{
  "customer_phone": "972501234567",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "company_size": "50-100",
  "lead_score": "85"
}

Example success responseJSON

{
  "success": true,
  "message": "Customer updated successfully",
  "custom_fields_processed": [
    "company_size",
    "lead_score"
  ]
}

Responses

200Updated

400Phone number is required.

400Failed to update customer due to invalid input

400Cannot add more than 15 custom fields per account

401Unauthorized

404Customer not found

500An unexpected error occurred

DELETE /mumbleapi/delete-customer Permanently delete a customer.

Permanently delete a customer.

Request fields

customer_phonestringrequired

Example requestJSON

{
  "customer_phone": "972501234567"
}

Example success responseJSON

{
  "success": true,
  "message": "Customer deleted successfully"
}

Responses

200Deleted

400Phone number is required.

401Unauthorized

404Customer not found

GET /mumbleapi/get-customer Get a single customer record including custom fields.

Get a single customer record including custom fields.

Request fields

customer_phonestringrequired

Example requestJSON

{
  "customer_phone": "972501234567"
}

Example success responseJSON

{
  "success": true,
  "customer": {
    "id": "uuid",
    "name": "John Doe",
    "phone": "972501234567",
    "email": "john@example.com",
    "country": "IL",
    "conversation_status": "new",
    "last_interaction": "2026-06-29T00:00:00"
  }
}

Responses

200OK

401Unauthorized

404Customer not found

GET /mumbleapi/get-all-customers Paginated list of all customers (250 per page).

Paginated list of all customers (250 per page).

Request fields

pageintoptional

Page number (default 1)

Example requestJSON

{
  "page": 1
}

Example success responseJSON

{
  "success": true,
  "customers": [],
  "total": 250,
  "pages": 2,
  "current_page": 1,
  "per_page": 250,
  "total_pages": 2
}

Responses

200OK

401Unauthorized

500An unexpected error occurred

POST /mumbleapi/edit-customer-conv-status Update a customer's conversation status.

Update a customer's conversation status.

Request fields

customer_phonestringrequired

statusstringrequired

One of the conversation status values (English canonical key only).

Example requestJSON

{
  "customer_phone": "972501234567",
  "status": "in_progress"
}

Example success responseJSON

{
  "success": true,
  "message": "Customer conversation status updated successfully"
}

Responses

200Updated

400Phone number is required.

400Invalid conversation status.

401Unauthorized

404Customer not found

POST /mumbleapi/assign-customer-to-agent Route a customer's conversations to a specific agent.

Route a customer's conversations to a specific agent.

Request fields

customer_phonestringrequired

agent_idstringrequired

Agent UUID — from GET /mumbleapi/get-agents.

Example requestJSON

{
  "customer_phone": "972501234567",
  "agent_id": "agent-uuid"
}

Example success responseJSON

{
  "success": true,
  "message": "Customer assigned to agent successfully"
}

Responses

200Assigned

400Phone number is required.

400Agent ID is required.

401Unauthorized

404Customer not found

404Agent not found

POST /mumbleapi/assign-customer-to-team Route a customer's conversations to a team.

Route a customer's conversations to a team.

Request fields

customer_phonestringrequired

team_idstringrequired

Team UUID — from GET /mumbleapi/get-teams.

Example requestJSON

{
  "customer_phone": "972501234567",
  "team_id": "team-uuid"
}

Example success responseJSON

{
  "success": true,
  "message": "Customer assigned to team successfully"
}

Responses

200Assigned

400Phone number is required.

400Team ID is required.

401Unauthorized

404Customer not found

404Team not found

Labels

POST /mumbleapi/add-customer-to-label Tag a customer with a label.

Tag a customer with a label.

Request fields

customer_phonestringrequired

label_namestringrequired

Example requestJSON

{
  "customer_phone": "972501234567",
  "label_name": "VIP customers"
}

Example success responseJSON

{
  "success": true,
  "message": "added successfully"
}

Responses

200Added

400Phone number is required.

400Label name is required.

401Unauthorized

404Customer not found

404Label not found

DELETE /mumbleapi/remove-customer-from-label Remove a label from a customer.

Remove a label from a customer.

Request fields

customer_phonestringrequired

label_namestringrequired

Example requestJSON

{
  "customer_phone": "972501234567",
  "label_name": "VIP customers"
}

Example success responseJSON

{
  "success": true,
  "message": "removed successfully"
}

Responses

200Removed

400Phone number is required.

400Label name is required.

400Customer is not in the label

401Unauthorized

404Customer not found

404Label not found

POST /mumbleapi/add-new-label Create a new label (list) in your account.

Create a new label (list) in your account.

Request fields

label_namestringrequired

Example requestJSON

{
  "label_name": "VIP customers"
}

Example success responseJSON

{
  "success": true,
  "message": "Label 'VIP customers' created successfully"
}

Responses

200Created

400Label name is required.

401Unauthorized

409Label already exists

DELETE /mumbleapi/delete-label Delete a label.

Delete a label.

Request fields

label_namestringrequired

Example requestJSON

{
  "label_name": "VIP customers"
}

Example success responseJSON

{
  "success": true,
  "message": "Label 'VIP customers' deleted successfully"
}

Responses

200Deleted

400Label name is required.

401Unauthorized

404Label not found

GET /mumbleapi/get-labels List all labels in your account.

List all labels in your account.

Example requestJSON

(no body)

Example success responseJSON

{
  "success": true,
  "labels": []
}

Responses

200OK

401Unauthorized

Messaging

POST /mumbleapi/send-text-message Send a free-form text message.

Send a free-form text message. Requires an active 24-hour conversation window (see is-active-conv). Rate limited to 5/sec, 100/min, 2000/hour per API key.

Request fields

customer_phonestringrequired

textstringrequired

sourcestringoptional

Attach labels.

bot_tokenstringoptional

Assign a bot alongside the message.

namestringoptional

emailstringoptional

Example requestJSON

{
  "customer_phone": "972501234567",
  "text": "Hello!"
}

Example success responseJSON

{
  "success": true,
  "id": 1,
  "message_wa_id": "wamid.abc123"
}

Responses

200Sent

400Missing required parameters.

400Conversation is closed (send a template instead)

400Failed to send text message.

401Unauthorized

401User not authorized to send text messages.

POST /mumbleapi/send-media-message Send a media message (image, video, audio, document).

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 active 24-hour window. Supported: jpg, jpeg, png, webp, mp4, mov, mp3, ogg, m4a, wav, opus, pdf, doc, docx, xls, xlsx, ppt, pptx, txt.

Request fields

filefileoptional

Binary file (Mode A). Either file or media_url is required.

media_urlstringoptional

Public URL (Mode B). Either file or media_url is required.

customer_phonestringrequired

captionstringoptional

filenamestringoptional

Override display filename. Required for media_url if the URL has no file extension.

sourcestringoptional

bot_tokenstringoptional

namestringoptional

emailstringoptional

Example requestJSON

{
  "customer_phone": "972501234567",
  "media_url": "https://example.com/photo.jpg",
  "caption": "Check this out!",
  "filename": "photo.jpg"
}

Example success responseJSON

{
  "success": true,
  "id": 1,
  "message_wa_id": "wamid.abc123"
}

Responses

200Sent

400Either file upload or media_url is required.

400Missing required parameter: customer_phone

400Unsupported file type: .xyz

400Conversation is closed (send a template instead)

400Failed to send media message.

401Unauthorized

500Failed to upload media file.

POST /mumbleapi/send-template Send an approved message template.

Send an approved message template. Use this to start a conversation outside the 24-hour window. Rate limited to 5/sec, 100/min, 2000/hour per API key.

Request fields

customer_phonestringrequired

template_idstringrequired

UUID of an approved template — from GET /get-templates.

button_variablesarrayoptional

Values for dynamic URL buttons.

media_linkstringoptional

Override the template's media header (image/video/document).

sourcestringoptional

bot_tokenstringoptional

namestringoptional

emailstringoptional

Example requestJSON

{
  "customer_phone": "972501234567",
  "template_id": "template-uuid",
  "button_variables": [
    "offer25"
  ],
  "media_link": "https://example.com/banner.jpg"
}

Example success responseJSON

{
  "success": true,
  "message": "Template message sent successfully"
}

Responses

200Sent

400Phone number is required.

400Template ID is required.

401Unauthorized

404Customer not found

POST /mumbleapi/send-template-text-variable Send an approved template that has body variables ({{1}}, {{2}}, …).

Send an approved template that has body variables ({{1}}, {{2}}, …). Pass the variable values in order. Rate limited to 5/sec, 100/min, 2000/hour per API key.

Request fields

customer_phonestringrequired

template_idstringrequired

variablearrayrequired

Body variable values, in order.

button_variablesarrayoptional

Values for dynamic URL buttons.

sourcestringoptional

bot_tokenstringoptional

namestringoptional

emailstringoptional

Example requestJSON

{
  "customer_phone": "972501234567",
  "template_id": "template-uuid",
  "variable": [
    "John Doe",
    "#12345"
  ],
  "button_variables": [
    "offer25"
  ]
}

Example success responseJSON

{
  "success": true,
  "message": "Template message sent successfully"
}

Responses

200Sent

400Phone number is required.

400Template ID is required.

400Variables are required.

401Unauthorized

404Customer not found

GET /mumbleapi/get-message Fetch a single message by its WhatsApp ID (the message_wa_id returned when se…

Fetch a single message by its WhatsApp ID (the message_wa_id returned when sending).

Request fields

message_wa_idstringrequired

Example requestJSON

{
  "message_wa_id": "wamid.abc123"
}

Example success responseJSON

{
  "success": true,
  "message": {
    "id": 1,
    "text": "Hello",
    "status": "delivered"
  }
}

Responses

200OK

400Message WhatsApp Id is required

401Unauthorized

404Message not found

Conversations

GET /mumbleapi/get-conversation Paginated conversation history for a customer.

Paginated conversation history for a customer.

Request fields

customer_phonestringrequired

pageintoptional

Example requestJSON

{
  "customer_phone": "972501234567",
  "page": 1
}

Example success responseJSON

{
  "success": true,
  "messages": [
    {
      "id": 1,
      "from": "972501234567",
      "to": "972501111111",
      "text": "Hello",
      "is_img": false,
      "is_video": false,
      "is_audio": false,
      "is_pdf": false,
      "is_sticker": false,
      "is_geo_location": false,
      "media_url": "https://example.com",
      "timestamp": 1751200000
    }
  ],
  "total": 1,
  "pages": 1,
  "current_page": 1
}

Responses

200OK

401Unauthorized

401Customer not found

GET /mumbleapi/is-active-conv Check whether a customer's 24-hour conversation window is currently open.

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.

Request fields

customer_phonestringrequired

Example requestJSON

{
  "customer_phone": "972501234567"
}

Example success responseJSON

{
  "success": true,
  "is_active": true
}

Responses

200OK

400Phone number is required.

401Unauthorized

404Customer not found

Agents & Teams

GET /mumbleapi/get-agents List all agents (sub-users) in your account.

List all agents (sub-users) in your account.

Example requestJSON

(no body)

Example success responseJSON

{
  "success": true,
  "agents": [
    {
      "name": "Agent Name",
      "id": "uuid"
    }
  ]
}

Responses

200OK

401Unauthorized

GET /mumbleapi/get-teams List all teams in your account.

List all teams in your account.

Example requestJSON

(no body)

Example success responseJSON

{
  "success": true,
  "teams": [
    {
      "name": "Team Name",
      "id": "uuid"
    }
  ]
}

Responses

200OK

401Unauthorized

Bots

GET /mumbleapi/get-bots List all chatbots in your account.

List all chatbots in your account.

Example requestJSON

(no body)

Example success responseJSON

{
  "success": true,
  "bots": []
}

Responses

200OK

401Unauthorized

POST /mumbleapi/assign-bot Assign a chatbot to a customer.

Assign a chatbot to a customer. Works with both bot types: pass a flow chatbot’s bot ID (found in that chatbot’s settings), or "AI" for Dolores AI. Use "turn_off" to disable bots for the customer.

Request fields

customer_phonestringrequired

bot_tokenstringrequired

A flow chatbot’s bot ID (from the chatbot’s settings), "AI" for Dolores AI, or "turn_off".

Example requestJSON

{
  "customer_phone": "972501234567",
  "bot_token": "AI"
}

Example success responseJSON

{
  "success": true,
  "message": "Bot assigned successfully"
}

Responses

200Assigned

400Phone number is required.

400Bot token is required.

401Unauthorized

404Bot not found.

Templates

GET /mumbleapi/get-templates List all WhatsApp message templates in your account.

List all WhatsApp message templates in your account.

Example requestJSON

(no body)

Example success responseJSON

{
  "success": true,
  "templates": []
}

Responses

200OK

401Unauthorized

POST /mumbleapi/create-template Create a new WhatsApp message template.

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

Request fields

namestringrequired

Template name (lowercase, snake_case, no spaces).

languagestringrequired

Language code, e.g. en_US, he.

categorystringrequired

MARKETING, UTILITY, or AUTHENTICATION.

template_typestringoptional

Set to custom for standard templates.

bodystringrequired

Body text with optional {{1}}, {{2}}, … variables.

body_examplesarrayoptional

Example values matching the body variables (required by Meta review).

headerobjectoptional

{"format": "IMAGE" | "VIDEO" | "DOCUMENT" | "AUDIO"}.

footerstringoptional

buttonsarrayoptional

Array of button objects. See examples.

media_urlstringoptional

Sample media for the header format.

Recipes

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"}
  ]
}

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"
}

Example requestJSON

{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "MARKETING",
  "header": {
    "format": "IMAGE"
  },
  "body": "Hi {{1}}! Your order {{2}} has been confirmed. Total: {{3}}.",
  "body_examples": [
    "John Doe",
    "#12345",
    "$99.99"
  ],
  "footer": "Thank you for shopping!",
  "buttons": [
    {
      "type": "URL",
      "text": "Track Order",
      "url": "https://example.com/track/{{1}}",
      "example": "order-12345"
    }
  ],
  "media_url": "https://example.com/banner.jpg"
}

Example success responseJSON

{
  "error": false,
  "message": "Template created successfully",
  "data": {
    "id": "1234567890",
    "status": "PENDING"
  }
}

Responses

200Created (PENDING approval by Meta)

400Template name is required

400Template name already exists

400Body text is required

400Invalid template configuration

400Media link is not valid

401Unauthorized

500An unexpected error occurred

Conversation status values

Used by POST /mumbleapi/edit-customer-conv-status. The API accepts only the English canonical key (left column). Localized display strings are used only in the Mumble UI.

Status key (API)	Display
`new`	New — freshly created
`open`	Open
`closed`	Closed
`waiting`	Waiting
`waiting_for_agent`	Waiting for Agent
`reopened`	Reopened
`solved`	Solved
`in_progress`	In Progress
`in_process`	In Process
`spam`	Spam
`being_handled`	Being Handled
`not_relevant`	Not Relevant
`appointment_scheduled`	Appointment Scheduled
`pending_customer`	Pending Customer
`escalated`	Escalated
`follow_up`	Follow Up
`duplicate`	Duplicate
`require_review`	Require Review

Marketing attribution fields

The following optional fields are recognised on add-new-customer and edit-customer. Any of them can be sent to capture where the customer came from — UTMs, ad platform click IDs, ad ID, device, and page context.

Field	Purpose
`utm_source`	UTM source
`utm_medium`	UTM medium
`utm_campaign`	UTM campaign
`utm_content`	UTM content
`utm_term`	UTM term
`placement`	Ad placement
`adset_id`	Meta ad set ID
`ga_id`	Google Analytics client ID
`ga_session_id`	GA session ID
`campaign_id`	Ad campaign ID
`keyword_id`	Google Ads keyword ID
`gclid`	Google Ads click ID
`wbraid`	Google Ads web click ID (iOS 14+)
`gbraid`	Google Ads app click ID (iOS 14+)
`fbclid`	Meta / Facebook click ID
`msclickid`	Microsoft Ads click ID
`ttcid`	TikTok click ID
`yclid`	Yandex click ID
`obcid`	Outbrain click ID
`li_fat_id`	LinkedIn first-party ad tracking
`tblci`	Taboola click ID
`twclid`	X / Twitter click ID
`current_url`	Landing page URL
`user_agent`	User-agent string
`ip`	Origin IP address
`fbc`	Meta CAPI browser cookie
`fbp`	Meta pixel cookie
`cid`	Generic client ID
`matchtype`	Ad match type
`device`	desktop / mobile / tablet
`layer`	Custom layer / segment label
`network`	Ad network
`form`	Form ID

Support

Questions or need higher rate limits? Email support@mumble.co.il.

Mumble API Reference

Authentication

Rate limits

Errors & conventions

Customers

Labels

Messaging

Conversations

Agents & Teams

Bots

Templates

Conversation status values

Marketing attribution fields

Support