🏢 Maata Business Messaging API

Send messages from your software (school, bank, hospital, office, shop) to customers in the Maata app. Version 1.

1) Maata Business → More → Business messaging API → apply for verification. 2) Create a test key (mk_test_…) and try it on your own phone. 3) After verification, create a live key (mk_live_…). Keep keys on your server only — never in an app or web page.

Send a message

curl -X POST https://maataapp.com/v1/messages \
  -H "Authorization: Bearer mk_live_xxx" -H "Content-Type: application/json" \
  -d '{"to":"9876543210","template":"fee_reminder","variables":{"student_name":"Ravi","amount":"₹2,500","due_date":"20 Oct"},"idempotency_key":"fee-2026-10-ravi"}'

Response 202: {"id":"msg_…","status":"accepted",…}. Optional: "send_at":"2026-10-20T09:00:00+05:30" to schedule. Free text ("text":"…" instead of a template) is allowed only within 24 hours after the customer replied.

Message states

accepted / queued → sent → delivered (reached the phone) → read, or failed. Check with GET /v1/messages/{id}.

Other endpoints

GET /v1/templatesYour templates, status and variables.
GET /v1/usageToday's count and limits.
GET /v1/customers/{phone}Is the person on Maata, and can you message them?

Consent rules

Webhooks

Add an https address in the dashboard. Maata POSTs JSON events: message.delivered, message.read, message.received (customer reply), customer.opted_in, customer.opted_out, test.ping. Failed deliveries are retried (10 s, 1 min, 5 min, 30 min, 2 h).

Check the signature: header X-Maata-Signature: t=TIMESTAMP,v1=HEX where HEX = HMAC-SHA256(your whsec_… secret, TIMESTAMP + "." + raw body). Reject if older than 5 minutes.

// Node.js
const [t, v1] = sig.split(',').map(s => s.split('=')[1]);
const ok = crypto.createHmac('sha256', SECRET).update(t + '.' + rawBody).digest('hex') === v1;

Errors

not_on_maataThis number is not on Maata.
opted_outThe customer turned off messages from you.
no_consentThe customer has not opted in. Share your opt-in link or QR first.
no_marketing_consentMarketing needs the customer to choose "All messages" for your business.
not_verifiedYour business is not verified yet. Use a test key (mk_test_) until Maata verifies you.
test_only_teamTest keys can send only to your own team (owner and staff).
rate_limitedToo many messages. Slow down.
daily_limitDaily message limit reached.
bad_templateTemplate not found or not approved.
missing_variableA template variable is missing.
window_closedFree text is allowed only within 24 hours after the customer messaged you. Use a template.
suspendedMessaging for this business is suspended.

Limits

Test keys: 30/min, 200/day, only to your own team. Live keys: 300/min, 20000/day (can be raised).