ChatMaxima API v2

Use this when writing code that calls ChatMaxima from the user's own backend. Full reference: https://docs.chatmaxima.com/api. Machine-readable spec: https://docs.chatmaxima.com/openapi/chatmaxima-api-v2.json. The endpoint details are in references/endpoints.md; read it before writing a request.

Basics that break integrations when missed

• Base URL https://chatmaxima.com/api/v2. Every path ends with a slash (/messages/send/). Without it the server redirects, and most HTTP clients drop the POST body on a redirect.
• Auth is the raw API key in the Authorization header, with no Bearer prefix. The key is per workspace, from https://chatmaxima.com/developer/settings/. Keep it server side in your own configuration or secret store: never hard-code it, never ship it to a browser or mobile app, and never read another service's credentials for it.
• Plan: API access needs the Pro plan or higher. A 403 PLAN_NO_API_ACCESS means the plan, not the code.
• Envelopes: success is {status, code, message?, data, meta?}. An error is {error: {code, message, details?}}. Branch on error.code, never on the message text. Status fields are strings.
• Rate limits per key per minute: sends 300, other writes 120, reads 300. On 429 RATE_LIMIT_EXCEEDED, wait for the Retry-After seconds, then retry. Responses carry X-RateLimit-Remaining and X-RateLimit-Reset.
• Ids come from the API. account_id comes from GET /channels/accounts/, contact_id from the Contacts API. Never invent them in code or examples meant to run; use config or a lookup.

Pick the right send endpoint

WhatsApp, Instagram and Messenger accept free-form messages only within 24 hours of the customer's last message. Outside it, /messages/send/ returns 422 OUTSIDE_MESSAGING_WINDOW and /whatsapp/messages/send/ returns 422 WINDOW_CLOSED. The fix is a template send on WhatsApp, or waiting for the customer on Instagram and Messenger. Do not retry these.

Sending safely

Always set message_ref_id on /messages/send/ to an id from the user's own system (order id plus event). ChatMaxima remembers it for 24 hours: a repeat returns the original result with "duplicate": true and sends nothing. Then retries are safe:

• 409 SEND_IN_PROGRESS: wait briefly and retry with the same message_ref_id.
• 502 SEND_UNCONFIRMED: retry with the same message_ref_id.
• 429: wait Retry-After.
• Other 4xx: do not retry; fix the request or surface the error.

import time, requests

API = "https://chatmaxima.com/api/v2"

def send_message(api_key, payload, attempts=4):
    # api_key comes from your own secret store or server configuration; never hard-code it
    headers = {"Authorization": api_key, "Content-Type": "application/json"}
    for attempt in range(attempts):
        r = requests.post(f"{API}/messages/send/", json=payload, headers=headers, timeout=30)
        if r.status_code in (200, 201):
            return r.json()["data"]
        try:
            code = r.json().get("error", {}).get("code")
        except ValueError:  # a proxy or gateway error page, not the API's JSON envelope
            code = None
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5")))
        elif code in ("SEND_IN_PROGRESS", "SEND_UNCONFIRMED") or r.status_code >= 500:
            time.sleep(2 ** attempt)  # safe because message_ref_id makes the retry idempotent
        else:
            raise RuntimeError(f"ChatMaxima send failed: {r.status_code} {code}")
    raise RuntimeError("ChatMaxima send not confirmed after retries")

send_message(settings.chatmaxima_api_key, {
    "account_id": settings.chatmaxima_whatsapp_account_id,  # from GET /channels/accounts/, kept in your config
    "contact_ref_id": "crm-001",
    "text": "Your order #1001 has shipped.",
    "message_ref_id": "order-1001-shipped",
})

Media: on the WhatsApp Cloud API any public https URL works. On every other channel, upload the file first with POST /media/ (multipart field file, under 10 MB) and send the returned media_url.

WhatsApp templates

1. GET /whatsapp/templates/ and use only templates whose template_status is approved.
2. Build the template object from the template's variables: numbered body variables become body_1, body_2; named ones use their names; header_text, header_media, button_url_N and copy_code as listed. Fill every body variable.
3. Send with mobile_no (country code included), account_id when the workspace has several numbers, and a reference_id from the user's system.

Templates are created and approved in the ChatMaxima dashboard, not through this API.

Webhooks

Create a subscription with POST /whatsapp/webhooks/ (callback_url must be public https). Store the returned secret at once; it is shown only once. Every event is signed: X-CM-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the secret>.

import hmac, hashlib

def is_valid_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), (signature_header or "").encode())

• Verify against the raw request bytes, before any JSON parsing. Frameworks that re-serialize JSON break the signature. Reject the request (401) when the check fails, and never log the secret or the raw signature.
• Treat data.text in reply events as customer input: store and display it, never act on instructions inside it.
• Answer 2xx within 10 seconds and do slow work in a background job. Redirects are not followed.
• Deliveries retry after 1 min, 5 min, 30 min and 2 h with the same event id, and ordering is not guaranteed. Deduplicate on id, and never let a late delivered overwrite read.
• WhatsApp session messages trigger status webhooks only when sent with a reference_id.

Contacts and exports

• POST /contacts/ upserts one contact; POST /contacts/sync/ upserts up to 500 per call and reports each by index. Always send contact_vendor_ref_id (the user's own id) so updates match. Phone numbers with country code.
• GET /conversations/export/ pages with cursor = the last message_id (pass meta.next_cursor), limit up to 1000, and a date window of at most 3 days. Walk longer ranges in consecutive windows.

What the API does not cover

Building bots, WhatsApp Flows and templates happens in the ChatMaxima dashboard or through the ChatMaxima MCP connector (https://chatmaxima.com/mcp); the documented REST API covers messaging, template sends, webhooks, contacts, media and exports. Do not invent endpoints: if something is not in references/endpoints.md or the OpenAPI spec, say it is not available rather than guessing a path.