Send WhatsApp messages from your own systems

What you'll need

Before making your first API call, make sure you have these in place:

• A Drusy workspace with a connected WhatsApp channel
• A plan that includes API access. Check that your plan allows API keys
• An approved template in WhatsApp Manager (optional; only needed to send outside the reply window)
• A test recipient WhatsApp number you control (there's no sandbox; every send is real)

How it works

Understanding these three concepts makes everything else click:

Quick start

Get a message sent in under five minutes. Create an API key in the dashboard, then pick one of the examples below.

Send a free-form reply

The simplest way to get started. Only works if the customer messaged you recently (within the reply window).

curl -X POST "https://api.drusy.ai/v1/messages" \
  -H "Authorization: Bearer dk_live_your_key_here" \
  -H "Idempotency-Key: support-reply-42" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": {
      "body": "Hi Ada, your order is on the way!"
    }
  }'

Send a template message

Use templates for order updates, reminders, or any message outside the reply window.

curl -X POST "https://api.drusy.ai/v1/messages" \
  -H "Authorization: Bearer dk_live_your_key_here" \
  -H "Idempotency-Key: order-1234-shipped" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "parameters": { "body.1": "ORD-1234" }
    },
    "consentBasis": "transactional"
  }'

Authentication

Every API request requires an API key. Keys are created in the Drusy dashboard and follow a straightforward format. The plaintext secret is shown only once when you create it. If you lose it, revoke and create a new one.

Key format

dk_live_<keyId>_<secret>

How to send it

Include your key using either header (both are equivalent):

Authorization: Bearer dk_live_a1b2c3d4_...

X-API-Key: dk_live_a1b2c3d4_...

Scopes (permissions)

Each key has scopes that control what it can do. Follow the principle of least privilege: give each integration only the permissions it needs.

Rate limits

Rate limits protect the system and are applied per API key:

If you exceed the limit, you'll receive a 429 RATE_LIMITED response. Check the Retry-After header to know when to retry.

Send free-form text

POST /v1/messages (scope: messages:send)

Free-form messages let you write anything you want, but only during the reply window (within ~23 hours of the customer's last message to you). Use these for custom support replies and personalized follow-ups.

Request body fields

Required headers

Example

curl -X POST "https://api.drusy.ai/v1/messages" \
  -H "Authorization: Bearer dk_live_your_key_here" \
  -H "Idempotency-Key: support-followup-42" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "text",
    "text": {
      "body": "Hi Ada,\n\nYour order is out for delivery.\n\nOrder: ORD-1234\nETA: Today, before 6 PM\n\nReply here if you need anything."
    }
  }'

Formatting your messages

The text.body field is a JSON string. Use escape sequences and WhatsApp's built-in formatting for clear, readable messages:

Example with formatting:

{
  "to": "+2348012345678",
  "type": "text",
  "text": {
    "body": "Hi Ada,\n\n*Your order is out for delivery.*\n\nOrder: `ORD-1234`\nETA: _Today, before 6 PM_\n\n~Old ETA: 4 PM~\nNew ETA: *6 PM*"
  }
}

What the customer sees on WhatsApp:

WhatsApp removes the formatting markers and applies the styles in the app. The preview below shows how the message above appears on the customer's phone.

A successful send returns a message ID. The API returns 201 Created when Meta accepts it inline, 202 Accepted when retry is pending, or 200 OK for an idempotent replay. See Send response for the full response shape (shared by both message types).

Send a template

POST /v1/messages (scope: messages:send)

Template messages use pre-approved formats from WhatsApp Manager. They're the only way to start a conversation with a customer or reach them outside the reply window.

Request body fields

Required headers

Same as free-form sends: Idempotency-Key, Content-Type, and your API key. See Send free-form text for details on idempotency.

Full example

curl -X POST "https://api.drusy.ai/v1/messages" \
  -H "Authorization: Bearer dk_live_your_key_here" \
  -H "Idempotency-Key: order-1234-shipped" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "parameters": { "body.1": "ORD-1234", "body.2": "tomorrow" }
    },
    "consentBasis": "transactional"
  }'

Template variables

Templates have placeholders (like {{1}} in the body or header). You fill these with the parameters object. Each key identifies which placeholder to fill:

For body-only templates, you can use the shorthand (just "1"). Use the qualified format when your template also has a header or link button.

{
  "to": "+2348012345678",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": "en",
    "parameters": {
      "header.1": "ORD-1234",
      "body.1": "Ada",
      "button.0.1": "trk_9f2c"
    }
  }
}

Send response

Both free-form and template sends return the same response shape. A successful send returns 201 Created when Meta accepts it inline, 202 Accepted when retry is pending, or 200 for idempotent replays):

{
  "id": "66a1b2c3d4e5f6789012345",
  "status": "sent",
  "to": "2348012345678",
  "category": "utility",
  "kind": "template",
  "duplicate": false,
  "providerMessageId": "wamid.HBgNMjM0ODAxMjM0NTY3OA==",
  "sentAt": "2026-07-28T18:00:00.000Z",
  "error": null
}

The kind field reflects what you sent: "text" for free-form, "template" for templates.

Track delivery

After sending, poll these endpoints to check whether your messages were delivered. The message ID from the send response is your lookup key.

Get a single message

GET /v1/messages/:id (scope: messages:read)

Returns the full detail for one message, including delivery status, provider pricing, and the parameters you sent.

GET /v1/messages/66a1b2c3d4e5f6789012345
Authorization: Bearer dk_live_...

{
  "id": "66a1b2c3d4e5f6789012345",
  "status": "delivered",
  "to": "2348012345678",
  "kind": "template",
  "templateName": "order_shipped",
  "sentAt": "2026-07-28T18:00:00.000Z",
  "delivery": {
    "pricing": { "category": "utility", "model": "CBP" },
    "conversation": { "id": "conv_..." }
  }
}

List all messages

GET /v1/messages (scope: messages:read)

Lists your API-sent messages (newest first), with cursor-based pagination and optional filters.

Query parameters

GET /v1/messages?limit=25&status=failed
Authorization: Bearer dk_live_...

{
  "messages": [
    {
      "id": "66a1...",
      "channelId": "66b2...",
      "to": "2348012345678",
      "status": "delivered",
      "kind": "template",
      "templateName": "order_shipped",
      "languageCode": "en",
      "category": "utility",
      "source": "api",
      "attempts": 1,
      "providerMessageId": "wamid....",
      "sentAt": "2026-07-28T18:00:00.000Z",
      "createdAt": "2026-07-28T17:59:50.000Z",
      "error": null
    }
  ],
  "nextCursor": null
}

List templates

GET /v1/templates (scope: templates:read)

Lists all templates synced from your WhatsApp Business Account. Use this to confirm which templates are approved and what parameter keys they need before sending.

GET /v1/templates
Authorization: Bearer dk_live_...

{
  "templates": [
    {
      "name": "order_shipped",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "parameters": [
        { "component": "header", "index": 1, "example": "ORD-1234" },
        { "component": "body", "index": 1, "example": "Ada" },
        {
          "component": "button",
          "subType": "url",
          "buttonIndex": 0,
          "index": 1,
          "example": "https://example.com/t/9f2c"
        }
      ],
      "lastSyncedAt": "2026-07-28T12:00:00.000Z"
    }
  ]
}

How to build parameter keys from this response: Combine the component and index fields. For buttons, add the buttonIndex. The example above gives you header.1, body.1, and button.0.1.

Consent & opt-out

Drusy enforces consent rules to protect your customers and your reputation. The rules depend on the type of message you're sending and whether the recipient has opted in.

Free-form text messages are categorized as service. They only require an open reply window and don't need explicit consent fields. Template messages follow the matrix below:

Message lifecycle

Every message progresses through these statuses. You can track them via the GET /v1/messages/:id endpoint or the dashboard Activity tab.

Error reference

All errors follow the same envelope format. The code field is machine-readable (use it in your code), and message is human-readable (good for logs and debugging).

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "code": "MACHINE_READABLE_CODE",
    "requestId": "abc-123"
  }
}

Each response also includes an x-request-id header you can use when contacting support.

Integration checklist

Follow these steps to go from zero to production-ready messaging. Each step builds on the previous one.

Billing & metering

Understanding how messages are counted helps you plan costs and stay within your allowance.

Dashboard tools

Not everything requires code. The Drusy dashboard provides visual tools for managing keys, inspecting templates, and monitoring delivery. Useful for both technical and non-technical team members.

Dashboard access uses your regular login session. It's completely separate from API keys. Team members who need to monitor delivery or manage templates don't need API keys.