Build customer messaging with Convert

Send to many recipients

POST /api/v1/messages/batch takes up to 1,000 recipients in one request, each with their own message. Use it instead of looping over /api/v1/messages: one request per recipient sends everything at the provider simultaneously, which is what earns rate-limit errors on a list of any size.

Convert queues the batch and releases it at the safe rate for whichever provider is carrying it — fast for Meta Cloud WhatsApp, deliberately slow and jittered for a connected Convert WhatsApp number, where bursts risk the number itself. Eighty messages are eighty separate sends, spaced out; you make one call.

Request body

These apply to the batch as a whole.

Each object in messages

One recipient, and what to send them.

Contact details

Optional, and saved to the contact record rather than used for this one send — so a recipient you reach through the API is a real contact afterwards, usable in campaigns and personalisation. Skip them if you already manage contacts through the contacts API.

Example — three personalised WhatsApp messages

IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST https://convert.ruut.chat/api/v1/messages/batch \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "messages": [
      { "to": "+2348012345678", "message": "Hi Ada, order #1201 shipped.",  "reference": "order-1201" },
      { "to": "+2348098765432", "message": "Hi Tobi, order #1202 ships tomorrow.", "reference": "order-1202" },
      { "to": "+2348055500011", "message": "Hi Nkem, order #1203 is ready for pickup.", "reference": "order-1203" }
    ]
  }'

Successful response — 202 Accepted

202 means queued, not sent. Validation, contact creation and the wallet reservation are all done by the time you get this — so the accepted list is a firm commitment — but no message has reached the provider yet.

{
  "success": true,
  "batch_id": "batch_9f2c7a1de0b34c85a6d1",
  "status": "queued",
  "channel": "whatsapp",
  "queued": 3,
  "rejected_count": 0,
  "counts": { "pending": 3, "sent": 0, "failed": 0, "skipped": 0 },
  "reserved_cost": 13.5,
  "accepted": [
    { "index": 0, "to": "+2348012345678", "reference": "order-1201", "channel": "whatsapp", "message_id": 90211, "cost": 4.5 },
    { "index": 1, "to": "+2348098765432", "reference": "order-1202", "channel": "whatsapp", "message_id": 90212, "cost": 4.5 },
    { "index": 2, "to": "+2348055500011", "reference": "order-1203", "channel": "whatsapp", "message_id": 90213, "cost": 4.5 }
  ],
  "rejected": []
}

Partial acceptance

One bad row does not sink the batch. Valid recipients queue, and each rejection comes back with the index of the entry in the array you sent, so you can fix and resubmit just those.

{
  "success": true,
  "batch_id": "batch_4b81ea22c7d94f60b3aa",
  "queued": 1,
  "rejected_count": 2,
  "rejected": [
    { "index": 1, "to": "not-a-phone", "error": "'not-a-phone' is not a valid phone number.", "error_code": "invalid_phone" },
    { "index": 2, "to": "+2348055500011", "error": "'message' is required when no template is given.", "error_code": "missing_message" }
  ]
}

Checking on a batch

GET /api/v1/messages/batch/:batch_id returns the running counts and every recipient's outcome. Delivery also fires the usual message.* webhooks, which is the better option if you would otherwise poll.

{
  "success": true,
  "batch_id": "batch_9f2c7a1de0b34c85a6d1",
  "status": "partially_failed",
  "counts": { "pending": 0, "sent": 2, "failed": 1, "skipped": 0 },
  "messages": [
    { "message_id": 90211, "reference": "order-1201", "to": "+2348012345678", "status": "delivered",
      "channel": "whatsapp", "provider_message_id": "wamid.XXXX", "cost": 4.5 },
    { "message_id": 90213, "reference": "order-1203", "to": "+2348055500011", "status": "failed",
      "channel": "whatsapp", "error": "not_on_whatsapp", "cost": 0.0 }
  ]
}

Billing

The whole batch is reserved against your wallet when it is accepted, and each message is captured when it sends or refunded when it fails. If your balance runs out partway through, the remaining recipients are rejected with insufficient_balance rather than silently dropped. One wallet entry covers the batch.

Send with a template

Design a message once in Templates — choose how it looks, add {{variables}}, and pick a type (transactional or promotional). Each template gets an immutable ID like tpl_x83k29sk. Send it by passing that template id plus a variables object — Convert renders your saved design and uses smart routing unless you explicitly choose a channel. Provider-specific Meta parameters are generated behind the scenes; API callers supply only the variables displayed by Convert. Email templates also store a subject, preview text, from name, and reply-to address.

Open any template and click Use via API to copy its ID and ready-made snippets (cURL, Node, Python, PHP, Flutter, Go).

Example — send an OTP template

IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST https://convert.ruut.chat/api/v1/messages \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2348012345678",
    "template": "tpl_x83k29sk",
    "channel": "smart",
    "variables": {
      "first_name": "Ada",
      "otp": "638492",
      "expiry": "10",
      "company_name": "Acme"
    }
  }'

Successful response — 201 Created

The response echoes the template id that was sent.

{
  "success": true,
  "channel": "whatsapp",
  "status": "sent",
  "message_id": "wamid.XXXX",
  "cost": 5.0,
  "template": "tpl_x83k29sk",
  "to": "+2348012345678"
}

Validation

Caller-facing variables marked required must be supplied (and non-empty). Optional ones may be omitted and fall back to their configured default. Meta component aliases such as authentication button parameters are resolved by Convert and never appear as API requirements. Missing caller-facing variables return 422 with the list of what's missing:

{
  "success": false,
  "error": "Missing required variable(s): otp.",
  "error_code": "missing_variables",
  "missing": ["otp"]
}

Contacts

Manage the people you message. Add them one at a time over the API, in bulk from a file, or let the send API create them automatically.

Create or enrich a contact

POST /api/v1/contacts

curl -X POST https://convert.ruut.chat/api/v1/contacts \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+2348012345678",
    "first_name": "Ada",
    "last_name": "Obi",
    "email": "[email protected]"
  }'

Phone numbers are normalized to E.164 and emails to lowercase. A matching normalized phone, email, or external customer ID enriches the existing organisation contact instead of creating a duplicate.

Update a contact

PATCH /api/v1/contacts/:id

Replace :id with the numeric contact ID. This is a partial update: omitted fields keep their existing values. The API key can update only contacts in its organisation.

curl -X PATCH https://convert.ruut.chat/api/v1/contacts/1042 \
  -H "Authorization: Bearer rk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Adanna",
    "email": "[email protected]",
    "tags": ["customer", "vip"],
    "custom_fields": { "tier": "platinum" }
  }'

Returns 200 OK, 404 Not Found for an unknown or cross-organisation ID, or 422 Unprocessable Entity for invalid or duplicate identifiers.

Remove a contact

DELETE /api/v1/contacts/:id

Permanently removes the contact from the API key's organisation.

curl -X DELETE https://convert.ruut.chat/api/v1/contacts/1042 \
  -H "Authorization: Bearer rk_live_xxx"

Returns 204 No Content with no response body. Deletion also removes dependent recipient delivery records; use an opt-out when the customer and history should remain.

Bulk upload

For large lists, import a CSV or Excel (.xlsx) file from Contacts → a list → Add contacts. You map your columns to fields (phone, first name, last name, email, and any custom fields) and Convert imports them in the background, checking each number against WhatsApp.

To bulk-load programmatically, loop the single-contact endpoint:

const contacts = [
  { phone_number: "+2348010000001", first_name: "Ada" },
  { phone_number: "+2348010000002", first_name: "Uche" }
];

for (const c of contacts) {
  await fetch("https://convert.ruut.chat/api/v1/contacts", {
    method: "POST",
    headers: {
      "Authorization": "Bearer rk_live_xxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(c)
  });
}

Custom fields

Attach your own attributes via custom_fields. These become available as merge tags (e.g. {{order_id}}) in messages.

{
  "phone_number": "+2348012345678",
  "first_name": "Ada",
  "custom_fields": {
    "order_id": "ORD-1042",
    "tier": "gold"
  }
}

Routing strategies

Campaigns route every contact using one of these strategies (the send API mirrors them via channel):

Message state progresses from sent (provider accepted) to delivered when a delivery event arrives. Email can also become bounced or unsubscribed. Campaign Email adds first-open and first-click timestamps; opens can be under-counted by client privacy controls and prefetching can inflate them.

Webhooks

Get notified in real time when things happen. Add an endpoint under Webhooks and pick the events you want. Convert sends a POST with a JSON body for each event.

Events

Payload

{
  "event": "message.delivered",
  "created_at": "2026-06-29T12:00:00Z",
  "data": {
    "message_id": 8841,
    "to": "+2348012345678",
    "channel": "whatsapp",
    "status": "delivered",
    "provider_message_id": "wamid.XXXX",
    "cost": 5.0
  }
}

Verifying signatures

Each request carries X-Convert-Signature: sha256=<hmac> — an HMAC-SHA256 of the raw body using your endpoint's signing secret (shown on the endpoint page). Recompute and compare to confirm authenticity:

# Rails example
expected = "sha256=" + OpenSSL::HMAC.hexdigest(
  "SHA256", ENV["CONVERT_WEBHOOK_SECRET"], request.raw_post
)
verified = ActiveSupport::SecurityUtils.secure_compare(
  expected, request.headers["X-Convert-Signature"].to_s
)

Respond with any 2xx to acknowledge. Non-2xx (or timeouts) are retried with backoff.

Errors

Failed requests return a JSON body with error and a stable error_code:

{
  "success": false,
  "error": "Insufficient wallet balance to send this message.",
  "error_code": "insufficient_balance"
}