Start with the Waaru Developer API

Use the Developer API when your own server should handle WhatsApp messages for one connected number. You can send messages, read conversations and message status, download permitted media, and receive signed callbacks. Each API key belongs to one workspace and is permanently bound to one WhatsApp number.

Use Node.js or call REST directly

For text and template sends from Node.js, start with the Waaru SDK quickstart and install @waaru/sdk from npm. The beta SDK wraps only those two send methods. Use the REST guides below for reads, media downloads, and signed callbacks.

Before you start

This path is for developers writing server-side code. You need a connected WhatsApp number, permission to manage its API keys, and a safe place to store secrets. For incoming event notifications, you also need a public HTTPS endpoint. If you only want your team to reply in the dashboard, follow the Inbox guide.

An API key identifies your integration. A scope is a permission on that key. A webhook is an event notification sent to your server; its signature lets your server check that Waaru sent it.

Production base URL

https://api.waaru.app/v1

Send an API key as a Bearer token from your server. Keep the secret out of browsers, source control, and logs. The key determines the sending number; do not add a workspace or instance identifier to a message payload.

Complete the setup in order

An Admin or Developer can manage keys, inbound handling, and webhooks for permitted numbers. Ask an Admin or Manager to connect the number first if needed.

1. Create your workspace and connect a WhatsApp number.
2. Open Settings > Developer > Webhooks and choose that WhatsApp number. Prepare a public HTTPS callback if your server will respond to inbound messages. Follow webhook setup and verification.
3. Open API keys for the same number. In Choose one inbound handler, select Use Developer API and confirm the change. The number must be connected. Active flow conversations or scheduled steps must finish before the switch can complete.
4. On API keys, select Create API key, and choose a name, the exact number, and the required scopes. For this walkthrough, choose messages:send and messages:read. Add media:read only if you need to download attachments. Copy the secret once. See API key management.
5. Make the read-only authentication check. An empty conversation list is a valid result.
6. Send an inbound message from a permitted test account. Confirm the callback, then send a reply within the open service window.
7. Read the returned message identifier or use delivery events to confirm the outcome. Test human takeover and callback recovery before relying on the integration.

You have completed the walkthrough when the conversation request returns 200, an incoming test message reaches your webhook, and your reply returns a messageId whose later status you can read. Check the test phone to confirm delivery; a queued response alone does not confirm it.

Choose who handles incoming messages

An inbound handler is the system that responds to incoming WhatsApp messages: your Developer API integration or a Logic Flow. Choose one for each number.

Switching to Developer API stops Logic Flow and automatic replies for that number. Inbound conversations remain visible in Inbox. Callback failure does not start Logic Flow as a fallback.

Human takeover pauses API sends for that conversation. An authorized teammate must use Release to API in Inbox when the server should resume. Switching the number back with Use Logic Flow stops new Developer API requests and callbacks for it, including reads.

Find the contract you need

Contacts, segments, broadcast management, workflow editing, and workspace settings remain dashboard tasks. An API key does not grant access to every route used by the dashboard.

Additional references

• Choose a WhatsApp API message format