Skip to main content
Back to topics

Developer Guide

The MauKirim WhatsApp API: OTP, Notifications, and Messages from Your App

The MauKirim WhatsApp API is a REST API for sending OTP codes, templated notifications, and messages from a rented WhatsApp number, without running WhatsApp infrastructure yourself. This page explains how it works from a developer's side.

01

Authentication with scoped API keys

Every request goes to https://app.maukirim.com/api/v1 with an Authorization: Bearer header that carries an API key. You create keys in the dashboard under Developer, then API keys, and the value is shown once.

Each key has scopes: read, otp, notification, send, device, and webhook. Give each service only the scopes it needs.

02

Sending and verifying an OTP

POST /otp/send asks for a code for one phone number and one purpose: login, signup, payment, password reset, or phone change. MauKirim generates the six-digit code, stores only its hash, and delivers it over WhatsApp. POST /otp/verify checks what the user typed.

A code lasts five minutes and allows five attempts. A wrong code is not an error: the response is still 200, with verified set to false. Issuing is limited to five codes an hour for each phone number.

03

Templated notifications

Notifications are bound to a template that is approved for your account first. Each send through POST /messages/send names the template ID and fills in its variables. The variable names and their count must match the template exactly.

A template with a repeating block, such as the items in an order, is still one message and one charge. A template approved for attachments can carry a file on each send, such as a PDF invoice. Uploaded files expire after seven days.

04

Free-form messages and media from a rented number

From a number you rent, POST /devices/{id}/messages sends free-form text, an image with a caption, or a document. A document arrives under the file name you send. Use this route when the content depends on what the customer wrote.

A paid rental is not yet a ready number: it can send only once it is connected and logged in. The same API also sets the number's display name and profile photo.

05

Webhooks for incoming messages and acknowledgements

Set one URL for each number to receive events such as incoming messages (message) and message acknowledgements (message.ack). Each delivery is signed with HMAC-SHA256. Verify the signature over the raw body, before parsing the JSON.

MauKirim retries up to five times with backoff, and each attempt waits at most 10 seconds. The same delivery can arrive more than once, so store the delivery_id and drop duplicates.

06

Idempotency and error codes

Every send request must carry an idempotency key. Repeating the same request with the same key does not send a second message. Reusing a key with a different body is refused with status 409.

Every error carries a machine-readable code, for example insufficient_credits (402) when the balance is too low, device_not_connected (409) when the number is not ready, and rate_limited (429) when the OTP limit is exceeded.

07

Official SDKs and MCP

MIT-licensed SDKs are available for Node.js and TypeScript (npm install maukirim), PHP (composer require maukirim/sdk), and Go (go get github.com/MauKirim/sdk-go), plus a community node for n8n. They all cover OTP, templated notifications, rented-number operations, and webhook signature verification.

An AI assistant that supports MCP can connect to your account through the MauKirim MCP server, with the permissions of the API key scopes you grant.

Ready to Set Up a WhatsApp Gateway for Your Business?

Start without providing your own SIM card. MauKirim's team at PT Cipta Dua Saudara can discuss your system integration.

Frequently asked questions

Which programming languages are supported?

The API uses HTTP and JSON, so any language can call it. Official SDKs are available for Node.js, PHP, and Go, plus a community node for n8n.

How do I start trying the API?

Create an account at app.maukirim.com, create an API key under Developer, then API keys, and follow the API documentation in the dashboard.

Will a message be sent twice if my request is repeated?

No, as long as the idempotency key is the same. A repeated request with the same key and body counts as the same request.

Can I receive customer replies?

Yes. Set a webhook on your rented number to receive incoming messages and message acknowledgements on your server.

Related topics

whatsapp api indonesiawhatsapp otp apiwhatsapp webhookwhatsapp api sdk
View pricing

Start with MauKirim

Chats come in. The team closes.

Create an account to connect WhatsApp, Instagram, or Facebook and try the CRM, the API, or both.

Create a MauKirim account