MazBot API Developer Documentation

Introduction

Welcome to the official MazBot Developer Hub. Our unified RESTful API empowers developers to establish robust integrations between their external CRMs, ticket modules, and WhatsApp Cloud accounts.

Unified API Standards

All requests must target our verified subdomain endpoints. The system enforces strict dual-layer authentication (API Key & JSON Web Token), structured validation error schemas, and standard JSON response envelopes.

Base Domain & Versioning

The API is deployed globally on the primary server. There is no /v1 prefix in route paths. Documentation is hosted at https://api.mazbot.net/ (read-only); always call the API at https://mazbot.net/api, not the docs subdomain.

OFFICIAL BASE URL: https://mazbot.net/api

Developer Quick Checklist

Verify your account **API Key** from your Profile dashboard page.
Use clean numbers without `+` symbols (**International Format**).
Manage high-throughput requests within the **60 req/min** limit.
Re-login when JWT returns 401 (token expired or invalid).
Confirm locale prefix if routes return 404 (see Locale Prefix).
Template variable arrays start at index 1, not 0.

Quick Start Guide

Connect your codebase to MazBot in under 3 minutes following these three simple milestones:

1
Acquire API Credentials
Log in to the Client Panel and navigate to your user Profile to generate your secure, case-insensitive `apikey`.
2
Obtain Session JWT
Submit your login credentials alongside your `apikey` to generate an access Bearer Token.
3
Fire a WhatsApp Message
Call `POST /whatsapp/send-template` with your template details or `POST /send-message` for direct chats.

# Step 1: Exchange credentials and apikey for JWT Access Token

curl -X POST "https://mazbot.net/api/login" \

  -H "apikey: YOUR_API_KEY_HERE" \

  -H "Content-Type: application/json" \

  -d '{

    "email": "[email protected]",

    "password": "your_secure_password"

  }'

Locale Prefix

Routes are registered under an optional locale segment. When your MazBot instance default language is English, paths are:

https://mazbot.net/api/login

When the default language is not English (e.g. Arabic), the same route may be:

https://mazbot.net/ar/api/login

404 troubleshooting

If a call to /api/... returns 404, retry with /{locale}/api/... using your dashboard default locale (or the locale in your browser URL when logged in).

Examples

EN: POST /api/login
AR: POST /ar/api/login
AR: GET /ar/api/chat-rooms

Authentication Flow

MazBot enforces a Dual-Layer Authentication Scheme to insulate system routes. All private endpoints verify access authorization tokens sequentially:

Layer 1: apiKey Header

Required for every single API request, including logins. This header is evaluated in a case-insensitive manner (you can pass `apikey`, `apiKey`, or `APIKEY`).

Situation	HTTP	Message
Header missing	401	api_key_missing
Invalid key	403	API key invalid

Layer 2: JWT Bearer Token

Generated dynamically by standard logins. Must be supplied as a `Authorization: Bearer ` header in all state-changing endpoints (sending messages, pulling staff details).

Token Lifespans & Expirations

JWT Lifespan: Token TTL is configured server-side (JWT_TTL). Many installs use 60 minutes; some may use non-expiring tokens if unset.
Refresh Token: Not supported. Re-login via POST /login when you receive HTTP 401.
Login rate limit: POST /login is limited to 5 requests/minute per IP (independent of the 60/min API limit).

POST /login

Exchange platform credentials and a valid `apikey` for a session JWT.

Staff-Only Authentication:

This endpoint authenticates client-staff users only. Account owners (client-admin) must use the dashboard to access the system. Attempting to login with an owner account will return 401 Unauthorized.

Parameter	Type	Requirement	Description
email	string	Required	Your registered MazBot account email.
password	string	Required	Your primary MazBot account password.

POST /api/login HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Accept: application/json

Content-Type: application/json

{

  "email": "[email protected]",

  "password": "your_secure_password"

}

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Accept' => 'application/json',

])->post('https://mazbot.net/api/login', [

    'email' => '[email protected]',

    'password' => 'your_secure_password'

]);

if ($response->successful()) {

    $jwtToken = $response->json()['data']['token'];

}

import requests

url = "https://mazbot.net/api/login"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Accept": "application/json"

}

payload = {

    "email": "[email protected]",

    "password": "your_secure_password"

}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:

    jwt_token = response.json()['data']['token']

const axios = require('axios');

axios.post('https://mazbot.net/api/login', {

  email: '[email protected]',

  password: 'your_secure_password'

}, {

  headers: {

    'apikey': 'YOUR_API_KEY_HERE',

    'Accept': 'application/json'

  }

})

.then(response => {

  const jwtToken = response.data.data.token;

});

Success Response Format 200 OK

{

  "success": true,

  "message": "login_successfully",

  "data": {

    "id": 5,

    "name": "Migo Developer",

    "role_id": 2,

    "client_id": 1,

    "phone": "201012345678",

    "email": "[email protected]",

    "openai_api_key": "...",

    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

  }

}

Security:

Treat the login response as sensitive. It may include openai_api_key and the session JWT. Do not log full responses in production.

Common Integration Mistakes

Mistake	Correct approach
Using `is_seen` backwards	`is_seen=1` = unread; `is_seen=0` = read / no unread
Confusing contact ID with chat room ID	`GET /message/{id}` uses contacts.id
Expecting a flat message array	Messages are grouped by date in `data.messages`
Session messages outside 24h	Check `can_not_reply` first, or use templates
Template variables starting at 0	Use `body_values[1]`, not `[0]`
Missing `password_confirmation`	Required on `POST /team-store` (min 6 chars)
Owner account API login	Only client-staff can use API login
Ignoring `success: false` on HTTP 200	Always parse JSON body for subscription/limit errors
Wrong API host	Call `mazbot.net/api`, not `api.mazbot.net`
Missing locale prefix	Try `/{locale}/api/login` if 404
Polling too aggressively	10–30s interval; not faster than every 5s
API key error status codes	Missing key → 401; invalid key → 403

Rate Limiting & Error Management

MazBot implements rigorous traffic throttling thresholds on all router profiles to maintain high system availability.

Rate Throttling Details

Limiter	Limit	Keyed by
api	60 / minute	User ID (authenticated routes)
login_api	5 / minute	IP address
auth_public_api	10 / minute	IP address (forgot/reset password)

When exceeded: 429 Too Many Requests

Throttler Response Headers

Header Title	Description
X-RateLimit-Limit	Total capacity allocation assigned to the endpoint (60).
X-RateLimit-Remaining	Remaining permissible transactions inside the current timeframe.
X-RateLimit-Reset	Epoch UNIX timestamp indicating when the counter resets back to full.
Retry-After	Number of seconds to hold off before attempting requests again (HTTP 429).

HTTP Response Reference

The API returns standard HTTP status envelopes. Every error response uses a consistent, structured payload:

HTTP Code	Meaning	Typical Triggers / Response Payloads
200 / 201	Success	Request executed successfully. Returns `success: true` and the requested data wrapper.
400	Bad Request	Malformed JSON, invalid message parameters, or invalid reply ID triggers.
401	Unauthorized	Missing API key; expired, invalid, or missing JWT Bearer token.
403	Forbidden	Invalid API key; insufficient permissions; conversation limit.
404	Not Found	Target database records (like contact ID or room ID) do not exist or belong to another client.
422	Validation Error	Missing required fields, or invalid phone layout parameters.
429	Too Many Requests	Exceeded the maximum permitted limit of 60 requests per minute.
500	Server Error	Internal system exception, or failure communicating with Meta's Graph API.

HTTP 200 with `success: false`

Some business-rule failures return HTTP 200 with success: false (not 4xx). This applies especially to no active subscription or insufficient campaign/conversation limits on template send. Always check the success field, not only the status code.

Structured Error Envelope (422) 422 Unprocessable

{

  "success": false,

  "message": "Validation failed",

  "data": {

    "receiver_id": [

      "The receiver id field is required."

    ]

  }

}

Common Error Payloads (400, 401, 403, 404, 429) Error Reference

HTTP 400 Bad Request:

{

  "success": false,

  "message": "Invalid reply message ID.",

  "data": []

}

HTTP 401 Unauthorized:

{

  "success": false,

  "message": "Token is expired",

  "data": []

}

HTTP 403 Forbidden:

{

  "success": false,

  "message": "API key invalid",

  "data": []

}

HTTP 404 Not Found:

{

  "success": false,

  "message": "Contact not found",

  "data": []

}

HTTP 429 Too Many Requests:

{

  "success": false,

  "message": "Too many requests. Please wait before retrying.",

  "data": []

}

Meta Graph API Errors

In addition to internal validation checks, our backend intercepts callbacks directly from Meta (e.g. WhatsApp code 131060 "Message unavailable"). When such a transaction failure is caught, the descriptive Meta payload is appended directly into the message's database error field, visible when calling GET /message/{contact_id}.

Phone Number Formatting

MazBot integrates high-durability, automated sanitization algorithms via its core WhatsApp engine traits before passing records to Meta.

Backend Regex Sanitization

When numbers are processed, the system executes double regex normalization matches under the hood:

Laravel Clean Regex Normalizer

$phone = preg_replace('/\D+/', '', (string) $phone); // Strips all non-digit chars

$phone = preg_replace('/^0{2,}/', '', $phone); // Trims extra leading double zeros

Formatting Guidelines

We highly recommend sending sanitized, clean parameters directly in international format:

Clean Layout (Preferred): `201012345678` (Egypt), `966512345678` (Saudi Arabia)
Sanitized Automatically: `+20 101-234-5678` is fully parsed by the backend to `201012345678`

Sanitization Lifecycle

Input String: +20 10-123-45-678

Database State: 201012345678

Send Session (Normal) Message

Utilize this endpoint to send text or media documents directly to open chat sessions. This works dynamically outside of meta templates, provided a 24-hour customer service window is currently active.

24-HOUR CUSTOMER SERVICE WINDOW

Session messages (normal messages) can only be sent when the customer is inside the messaging window:

Customer messaged or replied within the last 24 hours, or
A Click-to-WhatsApp referral message exists within the last 72 hours

Before sending, call GET /message/{contact_id} and check data.can_not_reply: can_not_reply: false → safe to send; true → use POST /whatsapp/send-template instead. The send endpoint does not always block expired windows before queueing; Meta may reject delivery.

POST /send-message

Required MIME-Type Encoding:

Requests to this endpoint **must** be sent as multipart/form-data binary uploads rather than standard JSON objects if you are attaching images or documents.

Field	Type	Required	Description
receiver_id	integer	Yes	The integer ID of the contact in the database (`contacts.id`).
message	string	Optional*	Text string body. Required if image or document parameters are missing.
image	file (binary)	Optional*	Upload a JPEG/PNG image binary (Max 5MB).
document	file (binary)	Optional*	Upload a PDF invoice or doc sheet binary (Max 10MB).

Success Response Format 200 OK

{
  "success": true,
  "message": "message_sent_successfully",
  "data": {
    "message_type": "text",
    "conversation_id": 47,
    "remaining_conversations": 249
  }
}

Media Storage & Delivery Pipeline

Binary Validation: The backend intercepts the multipart parameter and validates the file's MIME type extension.
Storage Upload: The file is written to our local media directories or wasabi cloud space to generate a permanent static URL.
Meta API Forwarding: The public asset URL is structured inside a dynamic message payload and pushed directly to Meta API servers for cellular delivery.

POST /api/send-message HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

Content-Type: multipart/form-data; boundary=boundary123

--boundary123

Content-Disposition: form-data; name="receiver_id"

142

--boundary123

Content-Disposition: form-data; name="message"

Hello from the REST API!

--boundary123

Content-Disposition: form-data; name="document"; filename="invoice.pdf"

Content-Type: application/pdf

[BINARY_DATA]

--boundary123--

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept' => 'application/json',

])->attach(

    'document',

    file_get_contents('/path/to/invoice.pdf'),

    'invoice.pdf'

)->post('https://mazbot.net/api/send-message', [

    'receiver_id' => 142,

    'message' => 'Hello from the REST API!'

]);

import requests

url = "https://mazbot.net/api/send-message"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE",

    "Accept": "application/json"

}

files = {

    'document': ('invoice.pdf', open('/path/to/invoice.pdf', 'rb'), 'application/pdf')

}

payload = {

    "receiver_id": "142",

    "message": "Hello from the REST API!"

}

response = requests.post(url, headers=headers, data=payload, files=files)

const axios = require('axios');

const FormData = require('form-data');

const fs = require('fs');

const form = new FormData();

form.append('receiver_id', '142');

form.append('message', 'Hello from the REST API!');

form.append('document', fs.createReadStream('/path/to/invoice.pdf'));

axios.post('https://mazbot.net/api/send-message', form, {

  headers: {

    ...form.getHeaders(),

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept': 'application/json'

  }

});

Send Template Message

Pushes registered Meta WhatsApp templates directly to targets. Supports rich media headers (images, documents, videos) and complex variable binding arrays.

CRITICAL PAYLOAD REQUIREMENT

Both body_values and body_matchs arrays **MUST** use indexes starting at 1 (e.g. body_values[1] instead of body_values[0]).

Why? The local preview renderer and Laravel dashboard log-sync services fail to compile, truncate, or substitute custom attributes if index 0 is present.

POST /whatsapp/send-template

Field Name	Type	Required	Description
template_id	integer	Yes	The template configuration ID registered in your client dashboard.
mobile	string	Optional*	Clean target number (`201002345678`). Required if `contact_id` is blank.
contact_id	integer	Optional*	Existing database contact ID (`contacts.id`). Required if `mobile` is blank.
body_matchs	array	No	Maps dynamic placeholders (e.g. `{{1}}`). Accepts: `"input_value"`: Use custom manual input. `"contact_name"`: Replace with database contact name. `"contact_phone"`: Replace with database contact number.
body_values	array	No	The raw string parameters to map when using `input_value` matches.
button_matchs	array	No	Used to bind dynamic buttons (e.g. dynamic URL or copy code buttons). Accepts `"input_value"`. Array key represents the variable index (e.g. `"1"` for the first button).
button_values	array	No	The actual value (text or code) to pass to the dynamic button when using `"input_value"`.
image	file (binary)	No	Header image — max 2 MB (jpeg, png, jpg).
document	file (binary)	No	Header PDF — max 5 MB.
video	file (binary)	No	Header MP4 — max 10 MB.
audio	file (binary)	No	Header MP3 — max 5 MB.

JSON Payload Example (Without Media Header)

If your template does not require media headers (e.g., a simple OTP template with dynamic buttons or text body values), you can send the request using application/json encoding:

{

  "template_id": 42,

  "mobile": "201012345678",

  "body_matchs": {

    "1": "input_value"

  },

  "body_values": {

    "1": "123456"

  },

  "button_matchs": {

    "1": "input_value"

  },

  "button_values": {

    "1": "123456"

  }

}

POST /api/whatsapp/send-template HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

Content-Type: multipart/form-data; boundary=boundary555

--boundary555

Content-Disposition: form-data; name="template_id"

42

--boundary555

Content-Disposition: form-data; name="mobile"

201012345678

--boundary555

Content-Disposition: form-data; name="body_matchs[1]"

input_value

--boundary555

Content-Disposition: form-data; name="body_values[1]"

Ahmed Mohamed

--boundary555

Content-Disposition: form-data; name="button_matchs[1]"

input_value

--boundary555

Content-Disposition: form-data; name="button_values[1]"

123456

--boundary555

Content-Disposition: form-data; name="document"; filename="report.pdf"

Content-Type: application/pdf

[BINARY_PDF_DATA]

--boundary555--

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept' => 'application/json',

])->attach(

    'document',

    file_get_contents('/path/to/report.pdf'),

    'report.pdf'

)->post('https://mazbot.net/api/whatsapp/send-template', [

    'template_id' => 42,

    'mobile' => '201012345678',

    'body_matchs' => [

        1 => 'input_value'

    ],

    'body_values' => [

        1 => 'Ahmed Mohamed'

    ],

    'button_matchs' => [

        1 => 'input_value'

    ],

    'button_values' => [

        1 => '123456'

    ]

]);

import requests

url = "https://mazbot.net/api/whatsapp/send-template"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE",

    "Accept": "application/json"

}

files = {

    'document': ('report.pdf', open('/path/to/report.pdf', 'rb'), 'application/pdf')

}

payload = {

    "template_id": "42",

    "mobile": "201012345678",

    "body_matchs[1]": "input_value",

    "body_values[1]": "Ahmed Mohamed",

    "button_matchs[1]": "input_value",

    "button_values[1]": "123456"

}

response = requests.post(url, headers=headers, data=payload, files=files)

const axios = require('axios');

const FormData = require('form-data');

const fs = require('fs');

const form = new FormData();

form.append('template_id', '42');

form.append('mobile', '201012345678');

form.append('body_matchs[1]', 'input_value');

form.append('body_values[1]', 'Ahmed Mohamed');

form.append('button_matchs[1]', 'input_value');

form.append('button_values[1]', '123456');

form.append('document', fs.createReadStream('/path/to/report.pdf'));

axios.post('https://mazbot.net/api/whatsapp/send-template', form, {

  headers: {

    ...form.getHeaders(),

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept': 'application/json'

  }

});

Success Response Format 200 OK

{

  "success": true,

  "message": "message_sent_successfully",

  "data": {

    "message_id": 9821,

    "remaining_conversations": 248,

    "message_details": {

      "template": { "id": 42, "name": "otp_code", "components": [] },

      "contact": { "id": 142, "name": "Ahmed", "phone": "201012345678", "type": "whatsapp" },

      "message": {

        "type": "template",

        "status": "scheduled",

        "created_at": "2026-06-12T10:00:00.000000Z",

        "schedule_at": "2026-06-12T10:00:00.000000Z"

      }

    }

  }

}

Limit / subscription errors

May return HTTP 200 with success: false and insufficient_conversation_limit.

AI Auto-Reply Configuration

Connect external scripts to toggle your OpenAI automated responders or prioritize auto-replies across global channels.

POST /ai/contact/toggle-auto-reply

Enable, disable, or reverse the current AI responder status for a designated contact ID.

Field	Type	Required	Description
contact_id	integer	Yes	Target integer contact ID.
ai_reply_enabled	boolean	No	Set `true` to enable or `false` to turn off. If omitted, the server will switch the current state to the opposite values.

POST /ai/reply-priority

Set responder routing priority order (AI Agent vs Local Flow Builder rules).

Field	Type	Required	Description
reply_priority	string	Yes	Accepts strictly: `"ai_first"` (route to AI Agent first) or `"flow_first"` (route to local keywords flows first).

POST /api/ai/contact/toggle-auto-reply HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

Content-Type: application/json

{

  "contact_id": 125,

  "ai_reply_enabled": true

}

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE'

])->post('https://mazbot.net/api/ai/contact/toggle-auto-reply', [

    'contact_id' => 125,

    'ai_reply_enabled' => true

]);

import requests

url = "https://mazbot.net/api/ai/contact/toggle-auto-reply"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE"

}

payload = {

    "contact_id": 125,

    "ai_reply_enabled": True

}

response = requests.post(url, headers=headers, json=payload)

const axios = require('axios');

axios.post('https://mazbot.net/api/ai/contact/toggle-auto-reply', {

  contact_id: 125,

  ai_reply_enabled: true

}, {

  headers: {

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE'

  }

});

Toggle Success Response 200 OK

{

  "success": true,

  "message": "AI auto-reply enabled for this contact",

  "ai_reply_enabled": true,

  "contact_id": 125

}

Team Management & Access Limits

Query team rosters or register new organizational workers. These routes enforce tight plan boundaries and role permissions.

ROLE-BASED PERMISSION GATE

Only the primary Client Owner is permitted to access write endpoints (POST /api/team-store & POST /api/team-update/{id}).

If an API request is initiated by a worker account with a client-staff role, the server halts execution automatically, throwing an HTTP 403 Forbidden alongside an unauthorized_access error message wrapper.

PRIVILEGE ESCALATION PREVENTION

To ensure system integrity and prevent Privilege Escalation, the backend strictly ignores any custom role parameters passed during employee creation. All new records created via POST /api/team-store are hardcoded to the worker role (role_id: 3, user type: client-staff) and locked to the current client tenant account.

Plan Limits Enforcement

Adding team members triggers automated checks against your subscription plan boundary (team_limit). If your roster size matches or exceeds this, the server rejects inputs, returning a 422 Unprocessable status with an insufficient_team_limit validation error message.

POST /team-store

Parameter	Type	Required	Description
first_name	string	Yes	Employee's first name.
last_name	string	Yes	Employee's last name.
email	string	Yes	Unique workplace email address.
password	string	Yes	Secure credential password (minimum 6 chars).
password_confirmation	string	Yes	Must match the password exactly.
phone	string	No	Clean telephone number.

POST /api/team-store HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

Content-Type: application/json

{

  "first_name": "Ahmed",

  "last_name": "Mohamed",

  "email": "[email protected]",

  "password": "securePassword123",

  "password_confirmation": "securePassword123",

  "phone": "201012345678"

}

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE'

])->post('https://mazbot.net/api/team-store', [

    'first_name' => 'Ahmed',

    'last_name' => 'Mohamed',

    'email' => '[email protected]',

    'password' => 'securePassword123',

    'password_confirmation' => 'securePassword123',

    'phone' => '201012345678'

]);

import requests

url = "https://mazbot.net/api/team-store"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE"

}

payload = {

    "first_name": "Ahmed",

    "last_name": "Mohamed",

    "email": "[email protected]",

    "password": "securePassword123",

    "password_confirmation": "securePassword123",

    "phone": "201012345678"

}

response = requests.post(url, headers=headers, json=payload)

const axios = require('axios');

axios.post('https://mazbot.net/api/team-store', {

  first_name: 'Ahmed',

  last_name: 'Mohamed',

  email: '[email protected]',

  password: 'securePassword123',

  password_confirmation: 'securePassword123',

  phone: '201012345678'

}, {

  headers: {

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE'

  }

});

Success Response Format 200 OK

{

  "success": true,

  "message": "Created successfully",

  "data": ""

}

Contact Records & Pagination

Query, register, or block active platform customer profiles. List endpoints return robust metadata layouts mapping standard page listings.

Laravel LengthAware Pagination

Query listings (e.g. `GET /whatsapp-contact?page=2`) response envelopes feature a robust, nested `paginate` metadata object mapping the full listing boundary indices:

Metadata Field	Type	Description
total	integer	Total record instances available inside the query database.
current_page	integer	Current active page view index returned.
per_page	integer	Number of records packaged inside each single page response block.
last_page	integer	Maximum page threshold indices computed dynamically.
next_page_url	string \| null	API endpoint string URL mapping to pull the immediate next dataset, or `null` if boundary is hit.

GET /whatsapp-contact

Query all system contacts with a standard 10-item limit pagination buffer.

POST /whatsapp-contact-store

Create a new customer profile. Requires phone (numeric, min 11 digits) and country_id (integer). The name field is optional.

POST /whatsapp-contact-update/{id}

Update an existing contact profile. Accepts same parameters: phone (required, numeric min 11 digits), country_id (required), name (optional).

GET /contact/add-blacklist/{id}

Block/unblock the designated record identifier to intercept inbound traffic handlers.

Get Contacts Response 200 OK

{

  "success": true,

  "message": "data_retrieved_successfully",

  "data": {

    "contacts": [

      {

        "id": 101,

        "name": "Ahmed Mohamed",

        "phone": "201012345678",

        "email": "[email protected]",

        "type": "whatsapp",

        "status": 1

      }

    ],

    "paginate": {

      "total": 35,

      "current_page": 1,

      "per_page": 10,

      "last_page": 4,

      "prev_page_url": null,

      "next_page_url": "https://mazbot.net/api/whatsapp-contact?page=2",

      "path": "https://mazbot.net/api/whatsapp-contact"

    }

  }

}

Incoming Messages & Polling Flow

MazBot receives WhatsApp messages in real time inside the MazBot dashboard and mobile app using persistent WebSockets.

For external systems, incoming messages can currently be synchronized using the REST API by polling:

Get Chat Rooms List: GET /api/chat-rooms
Get Chat Room Messages: GET /api/message/{contact_id}

NO EXTERNAL WEBHOOKS SUPPORTED

External real-time Webhooks for forwarding incoming WhatsApp messages to external URLs are not currently supported in our public API schema. Outgoing traffic is handled exclusively via WebSockets inside the official client apps.

To sync responses securely into external CRMs or dashboards, you must execute the recommended REST Polling strategy below.

Recommended Polling Architecture

Pull Activity: Call `GET /chat-rooms` periodically.
Scan Timestamps: Compare the returned last_conversation_at timestamp against your local stored variables.
Fetch Room Logs: If a room's timestamp indicates new traffic, trigger GET /message/{contact_id} to retrieve its full transcript.
Deduplicate & Write: Verify incoming values against your database by performing unique indices matches on the message id parameter to filter out redundant records before writing.

Polling Frequencies & Rate Blocks

Set a moderate polling frequency interval of 10 to 30 seconds.

STRICT LIMIT: Do not pool more than once every 5 seconds. Triggering faster cycles will saturate resources, instantly kicking off rate limiters and returning persistent `429` status exceptions.

Polling Flowchart

[1] GET /chat-rooms (Every 15s)

[2] Compare last_conversation_at values

[3] GET /message/{contact_id} (Active Rooms)

[4] Unique Index Check & Save Local

Retrieve Chat Rooms

Queries active conversation profiles, providing search filters, assignee constraints, and overall unread status counts.

GET /chat-rooms

Query Field	Type	Required	Description
q	string	No	Filter rooms by matching names or phone digits.
type	string	No	Filter by system network type (e.g. `"whatsapp"`, `"telegram"`).
assignee_id	integer	No	Filter conversations assigned to specific staff ID.
tag_id	integer	No	Filter rooms matching custom categorization tag IDs.
is_seen	boolean/int	No	Unread filter — `1` = has unread inbound messages; `0` = no unread.
is_blacklist	boolean	No	Filter blacklisted contacts.

GET /api/chat-rooms?type=whatsapp&is_seen=1 HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept' => 'application/json'

])->get('https://mazbot.net/api/chat-rooms', [

    'type' => 'whatsapp',

    'is_seen' => 1

]);

import requests

url = "https://mazbot.net/api/chat-rooms"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE",

    "Accept": "application/json"

}

params = {

    "type": "whatsapp",

    "is_seen": "1"

}

response = requests.get(url, headers=headers, params=params)

const axios = require('axios');

axios.get('https://mazbot.net/api/chat-rooms', {

  params: {

    type: 'whatsapp',

    is_seen: 1

  },

  headers: {

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept': 'application/json'

  }

});

Chat Rooms Response 200 OK

{

  "success": true,

  "message": "chat_retrieved_successfully",

  "data": {

    "chat_rooms": [

      {

        "id": 12,

        "receiver_id": 12,

        "name": "John Doe",

        "phone": "201012345678",

        "last_conversation_at": "2026-06-12T12:00:00.000000Z",

        "has_unread_conversation": true,

        "assignee_id": 5,

        "assignee_name": "Staff Name",

        "type": "whatsapp",

        "message": {

          "title": "Hello there",

          "is_seen": false,

          "created_at": "2 minutes ago"

        },

        "tags": []

      }

    ],

    "total_unread_messages": 3,

    "next_page_url": true,

    "user_permissions": ["global_inbox"]

  }

}

Retrieve Chat Messages

Queries the transcript logs inside a targeted conversation room. Supports content category filters and provides granular payload keys.

CRITICAL ROUTING NOTICE

In previous versions, documentation listed the messages log path as `/api/chatroom-messages/{id}`.

The **only valid, active endpoint** in our Laravel backend routing engine is strictly:

GET https://mazbot.net/api/message/{contact_id}

Path parameter is contacts.id (contact ID). id and receiver_id in chat room list items are also the contact ID — there is no separate chat-room primary key.

GET /message/{contact_id}

Fetch messages for a contact. Returns messages grouped by date (Today, Yesterday, or dd/mm/yyyy) plus data.user and data.can_not_reply.

Query Parameter	Type	Required	Description
type	string	No	Filters log records by attachment category. Accepts: `"media"`: Retrieve images, audios, and videos. `"files"`: Retrieve PDF, doc, and sheet files. `"links"`: Filter messages holding web URLs.

POST /assign-staff

Assigns a targeted chat room to a specific employee for direct inbox handling.

Assigning Permissions Gate:

Requires global_inbox permission to assign conversations freely to any registered worker.
If a staff member holds only assign_chat_to_self, they are strictly restricted to assigning conversations to themselves, and cannot reassign active rooms from other operators.

Body Parameter	Type	Required	Description
contact_id	integer	Yes	Database ID representing the conversation contact.
staff_id	integer	Yes	Database User ID representing the employee assignee.

GET /chat/clear/{contact_id}

Clears the message records history for the designated contact profile.

Security Constraint:

Requires room control permissions. This endpoint enforces strict tenant isolation, preventing any cross-client history modification.

DELETE /chat/delete/{message_id}

Deletes a specific message instance permanently from the platform database.

Tenant Isolated:

Access is strictly guarded; users can only delete message records belonging directly to their own client tenant identity.

Granular API Response Mappings

type (Direction Key): Maps direct message directions. Value 2 signifies **Inbound** replies received from customers. Value 1 signifies **Outbound** payloads delivered by your team or AI system.
is_seen: Boolean state showing if the conversation was viewed.
header_document / header_image: Active URLs mapping to uploaded message media assets.

GET /api/message/12?type=media HTTP/1.1

Host: mazbot.net

apikey: YOUR_API_KEY_HERE

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Accept: application/json

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([

    'apikey' => 'YOUR_API_KEY_HERE',

    'Authorization' => 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept' => 'application/json'

])->get('https://mazbot.net/api/message/12', [

    'type' => 'media'

]);

import requests

url = "https://mazbot.net/api/message/12"

headers = {

    "apikey": "YOUR_API_KEY_HERE",

    "Authorization": "Bearer YOUR_JWT_TOKEN_HERE",

    "Accept": "application/json"

}

params = {

    "type": "media"

}

response = requests.get(url, headers=headers, params=params)

const axios = require('axios');

axios.get('https://mazbot.net/api/message/12', {

  params: {

    type: 'media'

  },

  headers: {

    'apikey': 'YOUR_API_KEY_HERE',

    'Authorization': 'Bearer YOUR_JWT_TOKEN_HERE',

    'Accept': 'application/json'

  }

});

Chat Messages Response 200 OK

{

  "success": true,

  "message": "messages_retrieved_successfully",

  "data": {

    "messages": [

      {

        "date": "Today",

        "items": [

          {

            "id": 4825,

            "type": 2,

            "message": "Yes, please send the invoice",

            "header_document": null,

            "is_seen": 1,

            "created_at": "2026-06-12T12:05:00.000000Z"

          }

        ]

      }

    ],

    "user": {

      "id": 12,

      "receiver_id": 12,

      "name": "John Doe",

      "phone": "201012345678",

      "last_conversation_at": "2026-06-12T12:05:00.000000Z",

      "ai_reply_enabled": true

    },

    "can_not_reply": false,

    "next_page_url": false

  }

}

Media Requirements & FFmpeg

Ensure uploaded attachments fit within WhatsApp Cloud constraints. Files exceeding size or codec specifications fail cellular delivery.

Template Header Limits (`POST /whatsapp/send-template`)

Type	Max	Formats
image	2 MB	jpeg, png, jpg
document	5 MB	pdf
video	10 MB	mp4
audio	5 MB	mp3

WhatsApp Cloud (General)

Media Category	Max Permitted Size	Recommended Format Standards
Images	5 MB	JPEG, PNG, JPG, WebP.
Documents	10 MB	PDF (highly recommended), DOCX, XLSX, XLS.
Audio	16 MB	MP3, AAC, OGG, AMR.
Videos	16 MB	MP4 or 3GP only. Under strict 16MB file limit. Requires H.264 (Main or Baseline profile) video codec and AAC audio codec encoding.

VIDEO BLACK-SCREEN FIX

Issue: High-definition video attachments, HEVC/H.265 encoding, H.264 High Profile, or multiple audio streams will fail to play (displaying a black screen) or fail delivery on mobile devices.

Requirements:

Container Format: MP4 or 3GP container.
File Size Cap: Strict 16 MB maximum ceiling.
Video Stream: H.264 video codec encoded on Main or Baseline profiles. Avoid H.265/HEVC entirely.
Audio Stream: AAC audio codec (Single stream, stereo or mono).
Color Space: yuv420p chroma subsampling (8-bit depth).

# Standard Recode (H.264 & AAC standard profile):

ffmpeg -i input.mp4 -c:v libx264 -profile:v main -level 3.1 -pix_fmt yuv420p -preset veryfast -crf 28 -c:a aac -b:a 128k -ac 2 -movflags +faststart output.mp4

# High Compression (Scale dimensions and cap bitrate):

ffmpeg -i input.mp4 -vf "scale='min(720,iw)':-2" -c:v libx264 -profile:v main -level 3.1 -pix_fmt yuv420p -b:v 900k -maxrate 1000k -bufsize 2000k -c:a aac -b:a 96k -ac 2 -movflags +faststart output_small.mp4

Postman Sandbox Configuration

Import environment presets directly into Postman to expedite request testing without custom coding layers.

Required Environment Keys

Variable Key	Value / Configuration	Scope
base_url	`https://mazbot.net/api`	Global
api_key	Supply your verified account dashboard API Key.	Global / Login
jwt_token	Populated automatically via `/login` response hooks.	Bearer Auth

Pre-Request Folder Hierarchy

Authentication: holds `POST {{base_url}}/login` (Headers: `apikey: {{api_key}}`)
WhatsApp Messages: holds templates and normal direct message dispatches.
Chat Logs Polling: holds chat rooms listings and chat message queries.

Postman Login Tests (Auto-Set Token) JavaScript Test Script

// Automatically extract and assign JWT on successful login

const response = pm.response.json();

if (response.success && response.data.token) {

    pm.environment.set("jwt_token", response.data.token);

    console.log("JWT Session token updated successfully!");

}

Developer FAQ & Coexistence

Review core operational architectural limitations to prevent synchronization bottlenecks.

Business Coexistence Mode

If your cellular line simultaneously operates active sessions inside both the WhatsApp Business Application and MazBot Dashboard:

Inbound Replies Routing: Cellular incoming messages are pushed directly and instantly to your physical WhatsApp mobile application device.
REST Database Latency: MazBot synchronizes message items programmatically, but Meta Graph replication limits might introduce a slight lag (1 to 3 seconds). Rely strictly on the Polling strategies checklist to fetch absolute states.

Interactive Developer FAQ

Integration Execution Checklist

H Base URL updates & Session token generation.
H REST message polling flows & deduplication checks.
M Template variable array indexes starting from 1.
M Video Recoding standards (FFmpeg).
L AI toggling routes & team owner permission gates.

Endpoint Index

Quick reference. Private routes need apikey + Authorization: Bearer. Rate limit: 60/min per user; login: 5/min per IP.

Method	Path	Auth	Summary
POST	/login	apikey	Staff JWT login
POST	/logout	both	Logout
GET	/profile	both	User profile
POST	/profile-update	both	Update profile
GET	/whatsapp-contact	both	List contacts
POST	/send-message	both	Session message
POST	/whatsapp/send-template	both	Template message
GET	/chat-rooms	both	Inbox list
GET	/message/{contact_id}	both	Message history
POST	/team-store	both	Add staff (owner only)
POST	/ai/contact/toggle-auto-reply	both	Toggle AI per contact
POST	/flow-builder/trigger	both	Trigger flow
POST	/appointments	both	Create appointment
POST	/contacts/{id}/capi-event	both	Meta CAPI event
GET	/country/list	apikey	Countries lookup

See Additional Endpoints for the full list including Telegram, segments, notes, tags, and Fawaterk.

Additional Endpoints Reference

The following endpoints are active and supported in the platform but not covered in the main guides above. All require dual-layer authentication (apikey + Authorization: Bearer token).

GET /contacts-by-client

Returns a paginated list of active contacts with optional filters: type, assignee_id, q (search), tag_id, is_seen.

GET /contacts-details/{id}

Returns the full profile details of a contact by ID, including notes, tags, and Meta CAPI attribution events.

GET /staffs-by-client

Returns a list of all active staff members/employees for the authenticated client.

GET /whatsapp/get-template

Retrieve single template details. Pass template_id as a query parameter.

GET /whatsapp-templates

Returns all approved WhatsApp templates for the client.

GET /shared-files/{id}

Returns shared media/files for a contact ID. Optional query parameter type: media, files, links.

DELETE /delete-file/{id}

Permanently deletes a specific shared file by its message ID.

POST /send-forward-message

Forward an existing message to one or more contacts.

Auth & Profile

POST /logout, GET /profile, POST /profile-update, POST /forgot-password, POST /verify-otp, POST /reset-password (password reset routes: 10/min per IP).

Flow Builder

GET /flow-builder/list, POST /flow-builder/trigger

Appointments

POST /appointments, POST /appointments/{id}/reschedule, POST /appointments/{id}/cancel, GET /appointments/{id}, GET /conversations/{conversationId}/appointments

Meta CAPI

POST /contacts/{id}/capi-event — dispatch conversion event (throttled).

Payments (Fawaterk)

GET, POST /fawaterk/manual-verify — apikey only, no JWT.

Reference / Lookup Endpoints

These endpoints require only the apikey header (no JWT Bearer token needed):

Method	Endpoint	Description
GET	/country/list	Returns all supported countries (used with contact `country_id`).
GET	/department/list	Returns all support departments (used with ticket `department_id`).
GET	/timezone/list	Returns all available timezones for profile configuration.
GET	/currency/list	Returns all supported currencies.

send-template: Additional Fields

The following optional fields are supported on template dispatches:

Field	Type	Description
mobile	string	Phone number (alternative to contact_id). Creates contact if not found.
body_values	array	Custom values for body placeholders.
body_matchs	array	Mapping of keys to sources: `input_value`, `contact_name`, `contact_phone`.
button_values	array	Custom dynamic values for templates button URLs.
image	file	Header image — max 2 MB (jpeg, png, jpg).
document	file	Header PDF — max 5 MB.
video	file (mp4)	Upload video header media (max 10MB).
audio	file (mp3)	Upload audio header media (max 5MB).

System Changelog

Review the latest API engine modifications and layout upgrades.

v1.2.1 Stable Released: June 12, 2026

Fixed rate limit documentation: 60 req/min (authenticated API), 5/min login, 10/min password reset.
Corrected is_seen filter semantics (unread vs read).
Documented GET /message/{contact_id} real response shape and contact ID parameter.
Documented 24-hour window: use can_not_reply before session sends; 72h referral exception.
Fixed team-store: password_confirmation, minimum password 6 characters.
Separated API key errors: missing → 401, invalid → 403.
Removed duplicate/conflicting send-message success examples.
Updated template media limits (image 2 MB, document 5 MB, video 10 MB).
Added locale prefix guidance, endpoint index, common mistakes, and expanded additional endpoints.

v1.2.0 Stable Released: May 18, 2026

Unified base domain reference paths to `https://mazbot.net/api`, deprecating old `api.` subdomain routes.
Stabilized `POST /send-message` to upload documents and validate MIME types dynamically.
Enforced strict 16MB file limit validations on WhatsApp campaign video parameters.
Standardized localized template preview compilers to handle indexes starting at 1.
Created `/ai/contact/toggle-auto-reply` and `/ai/reply-priority` API routes.

v1.1.5 Beta Released: April 10, 2026

Upgraded JWT token expiration ceiling limits to 60 minutes.
Implemented standard validation response formats under `ApiReturnFormatTrait`.

Integration Complete!

You are fully prepared to orchestrate powerful CRM systems with MazBot! Connect with our developer assistance staff via [email protected] if you require real-time pipeline troubleshooting.

Introduction

Unified API Standards

Base Domain & Versioning

Developer Quick Checklist

Quick Start Guide

Locale Prefix

404 troubleshooting

Examples

Authentication Flow

Layer 1: apiKey Header

Layer 2: JWT Bearer Token

Token Lifespans & Expirations

POST /login

Common Integration Mistakes

Rate Limiting & Error Management

Rate Throttling Details

Throttler Response Headers

HTTP Response Reference

HTTP 200 with success: false

Meta Graph API Errors

Phone Number Formatting

Backend Regex Sanitization

Formatting Guidelines

Sanitization Lifecycle

Send Session (Normal) Message

24-HOUR CUSTOMER SERVICE WINDOW

POST /send-message

Media Storage & Delivery Pipeline

Send Template Message

CRITICAL PAYLOAD REQUIREMENT

POST /whatsapp/send-template

JSON Payload Example (Without Media Header)

AI Auto-Reply Configuration

POST /ai/contact/toggle-auto-reply

POST /ai/reply-priority

Team Management & Access Limits

ROLE-BASED PERMISSION GATE

PRIVILEGE ESCALATION PREVENTION

Plan Limits Enforcement

POST /team-store

Contact Records & Pagination

Laravel LengthAware Pagination

GET /whatsapp-contact

POST /whatsapp-contact-store

POST /whatsapp-contact-update/{id}

GET /contact/add-blacklist/{id}

Incoming Messages & Polling Flow

NO EXTERNAL WEBHOOKS SUPPORTED

Recommended Polling Architecture

Polling Flowchart

Retrieve Chat Rooms

GET /chat-rooms

Retrieve Chat Messages

CRITICAL ROUTING NOTICE

GET /message/{contact_id}

POST /assign-staff

GET /chat/clear/{contact_id}

DELETE /chat/delete/{message_id}

Granular API Response Mappings

Media Requirements & FFmpeg

Template Header Limits (POST /whatsapp/send-template)

WhatsApp Cloud (General)

VIDEO BLACK-SCREEN FIX

Postman Sandbox Configuration

Required Environment Keys

Pre-Request Folder Hierarchy

Developer FAQ & Coexistence

Business Coexistence Mode

Interactive Developer FAQ

Integration Execution Checklist

Endpoint Index

Additional Endpoints Reference

GET /contacts-by-client

GET /contacts-details/{id}

GET /staffs-by-client

GET /whatsapp/get-template

GET /whatsapp-templates

GET /shared-files/{id}

DELETE /delete-file/{id}

POST /send-forward-message

HTTP 200 with `success: false`

Template Header Limits (`POST /whatsapp/send-template`)