Developer API quickstart

Use the Developer API to observe WhatsApp conversations or let your server handle replies for one 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 directlyCopy Anchor Link

For a server integration or your own customer console, start with the Waaru SDK guide. The guide distinguishes the published package from newer REST operations, so you can choose examples that match your installed version. Keep keys on your server and authorize your console users before proxying requests.

For an external AI client, follow MCP setup and permission review. MCP uses separate OAuth approval; a Developer API key is not an MCP credential. Neither reading data nor connecting an AI client changes who handles incoming replies.

Before you startCopy Anchor Link

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 URLCopy Anchor Link

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 orderCopy Anchor Link

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. Choose your integration authority. For read-only observation, keep Use Logic Flow and grant the required read scopes. To receive supported events from all message origins while retaining Logic Flow, explicitly enable all-origin observation (observeAllOrigins: true) in callback settings. For autonomous API replies, select Use your server and confirm. The number must be connected, and active flow conversations or scheduled steps must finish before that 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. For observation, reconcile retained history and message changes. For an explicitly server-managed sender, 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.

Observation setup is complete when a scoped read returns 200 and your persisted changes cursor or verified callback can reconcile events without changing the responder. For server-managed replies, also confirm a permitted reply returns messageId and reaches its test phone. A queued response alone does not confirm delivery.

Choose who handles incoming messagesCopy Anchor Link

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 Your server 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 back with Use Logic Flow stops autonomous API sends. Scoped reads remain available, and explicitly opted-in all-origin callbacks can continue. Reads and callbacks never change assignment, Flow state, human ownership or reply authority.

Find the contract you needCopy Anchor Link

Contacts, label lifecycle, static segments, cached template lifecycle discovery, read-only campaign results, activity reports and webhook management are available through the resource endpoints. Broadcast management, workflow editing, key management and workspace settings remain dashboard tasks. An API key does not grant access to every route used by the dashboard.

Additional referencesCopy Anchor Link

• Choose a WhatsApp API message format
• Use the official Node.js SDK
• Connect an MCP client
• Find an MCP tool by task
• Review MCP authoring and campaign controls

Browse resource payloadsCopy Anchor Link

• Number status and capabilities
• Contacts and labels
• Static segments
• Template discovery
• Activity reports
• Webhook management
• Observe events while keeping Logic Flow

Download OpenAPI or Postman. Each endpoint reference includes required scopes, path/query fields, request and response JSON, and full field schemas. The complete operation list also explains capabilities without a public API-key endpoint.

• Campaign summaries and recipient outcomes