Datagroup Messaging API (1.0.0)

Send WhatsApp and SMS messages from your own systems and check delivery status — the API behind Datagroup's messaging automation. Authenticate with a per-tenant API key created in the Datagroup portal (Admin → API keys). The same key works for every channel.

Channels. Every request and response carries an explicit channel field:

Omitting channel still defaults to whatsapp, so existing integrations are unaffected.

SMS is billed per segment. A message longer than 160 characters is split and billed as multiple segments (70 characters if it contains any non-GSM character, such as an emoji). The segments field on every SMS response tells you how many were billed.

Delivery-status webhooks — don't poll. Instead of calling GET /messages/{messageId} on a timer, register one HTTPS endpoint in the portal (Admin → API keys → Delivery webhook) and we POST every status change to it as it happens, for both channels. Polling still works, but at volume the webhook is the supported path.

Each POST carries:

{
  "event": "message.status",
  "messageId": "3f9c…",
  "providerMessageId": "wamid.HBg…",
  "channel": "whatsapp",
  "status": "Delivered",
  "to": "+27821234567",
  "templateName": "order_confirmation",
  "errorDetail": null,
  "occurredAt": "2026-08-09T13:04:31.6339263+00:00"
}

Verify the signature before trusting a payload. Two headers accompany the body:

Compute the HMAC with the signing secret shown once when you registered the endpoint, using the raw request body (not a re-serialised object — any whitespace difference changes the hash), and compare with a constant-time comparison. The timestamp is inside the signed string, so a captured payload cannot be replayed with a fresh one; reject anything older than a few minutes.

Delivery is at-least-once and unordered. Retries mean you may see the same status twice, and two transitions seconds apart can arrive out of order. Make your handler idempotent and trust occurredAt over arrival order. Return 2xx promptly — a non-2xx is retried five times, roughly a minute apart, after which the notification is dropped (your data is still available via GET /messages/{messageId}).

When to retry a failed send. Retry only failures that can succeed later. A send rejected because the recipient cannot receive WhatsApp, or because the request itself is wrong, fails identically every time — resending it wastes your rate limit and, on WhatsApp, a high failure rate lowers the sending number's quality rating and messaging limit.

On a 502 for WhatsApp, the message carries Meta's own error code:

Meta's full list is at WhatsApp Cloud API error codes. Treat any code not listed here as "fix first": log it and review before resending.

How to retry. Back off exponentially with jitter (2s, 4s, 8s, 16s, 32s) and cap attempts at about five, then record the failure. Reuse the same Idempotency-Key on every retry of a message — that is what lets us return the original result instead of sending a second message. A new key per attempt makes each retry a new send. Skip numbers that returned 131026 on later campaigns rather than retrying them, and if more than about 10% of a run fails, stop and check the recipient list before continuing.

Not yet available: free-text WhatsApp replies within the 24-hour window, WhatsApp Flows, and inbound SMS replies.