Developer API endpoint reference
Find the supported Waaru external API routes, required scopes, success responses, and links to message, conversation, pagination, and media examples.
Reviewed
These are the routes available to a Waaru Developer API key. Prefix each path with https://api.waaru.app. All require a connected number using Developer API handling and a key bound to that number.
| Method and path | Required scope | Successful response |
|---|---|---|
POST /v1/messages | messages:send | 202 JSON with messaging_product, messageId, and status: "queued". |
GET /v1/messages/:messageId | messages:read | 200 JSON with a message object. |
GET /v1/conversations | messages:read | 200 JSON with items and nextCursor. Query: limit, after. |
GET /v1/conversations/:conversationId/messages | messages:read | 200 JSON with items and nextCursor. Query: limit, before. |
GET /v1/media/:id | media:read | 200 attachment bytes with content headers. |
Replace path placeholders with identifiers returned by Waaru. A messageId is the Waaru message identifier, not a Meta message identifier. A media ID must refer to an attachment accessible to the key's number.
Identify the right value to use
| Identifier | Where it comes from and what it is for |
|---|---|
messageId or a message’s id | Returned by Waaru. Use it to read a message or match its status updates. It is not Meta’s message ID. |
conversationId | Returned in conversation or message data and relevant callbacks. Use it to read that conversation’s messages. |
| Media ID | The attachment reference returned in message data. Use it to download media that the key’s number can access. |
Webhook event id | Identifies an event notification. Use it to avoid processing the same event twice. |
X-Waaru-Request-Id | Identifies an HTTP request for troubleshooting. It is not a message ID or a duplicate-send prevention key. |
Follow the detailed examples
- Send messages: request envelope, supported formats, template variables, safety checks, and queued acceptance.
- Read conversations and media: response fields, cursor direction, message status, and downloads.
- Receive webhooks: event envelope, HMAC signature verification, callback tests, and retries.
- Handle errors and limits: stable error codes, rate-limit headers, and uncertain outcomes.
Manage the rest in the dashboard
Create keys, choose the inbound handler, and configure callbacks in Settings > Developer. Manage contacts and segments, templates and broadcasts, Logic Flows, and exports in their dashboard pages.
An external key cannot create contacts through /v1/contacts, upload files through /v1/media/upload, edit workflows, or administer a workspace. For outbound media, use a supported public HTTPS link in the message request. Do not copy dashboard calls into a server integration merely because their path starts with /v1.