Messaging API Integration Guide: REST, SMPP and Webhooks

This guide is for backend developers, solution architects and CTOs integrating an application with a messaging provider for WhatsApp, SMS or email. It explains which interface to use, and how to handle authentication, idempotency, delivery receipts, retries, rate limits and testing, with illustrative request and response shapes. For syncing conversations into a CRM, see the companion guide on connecting a CRM with webhooks.

Which interface should you use: REST, SMPP or webhooks?

Use REST to send, webhooks to receive, and SMPP only for high-volume SMS where you already run SMPP. They are complementary rather than competing: most integrations combine REST calls out with webhooks back in.

SMPP (Short Message Peer-to-Peer) sessions start with a bind (transmitter, receiver or transceiver), send messages with submit_sm, receive delivery receipts and inbound SMS via deliver_sm, and stay alive with enquire_link. It is efficient but operationally heavier than HTTPS.

How should you authenticate?

Use the strongest method the provider offers, keep secrets out of code, and authenticate both directions.

• Outbound calls: API keys or OAuth 2.0 bearer tokens sent in the Authorization header over TLS. Store them in a secrets manager and rotate on a schedule and after staff changes.
• SMPP: system ID and password at bind time, typically restricted to allow-listed IP addresses and, where supported, over TLS.
• Inbound webhooks: verify a signature on every event. Meta signs WhatsApp Cloud API webhook payloads with an HMAC-SHA256 signature in the X-Hub-Signature-256 header, computed with your app secret; providers usually offer a similar scheme. Compute the signature over the raw body before parsing.

Use separate credentials per environment so a leaked test key cannot send production traffic.

How do you send a message safely?

Send through a queue, include an idempotency key, and treat the response as "accepted", not "delivered".

Illustrative send request

The shape below is pseudo-JSON for illustration, not a specific provider's API.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

Illustrative response

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

Store message_id against your own reference immediately. Everything that happens next arrives asynchronously.

Why does idempotency matter?

Because networks time out after the server has already acted. If your send request times out and you retry blindly, the customer may receive two OTPs or two shipping notices. An idempotency key lets the server recognise the retry and return the original result.

Rules that work:

1. Derive the key from the business event (for example order ID plus event type), not from a random value per attempt.
2. Reuse the same key for every retry of the same send.
3. Keep keys long enough to cover your retry window.
4. If the provider does not support keys, deduplicate on your side before sending.

The IETF's draft Idempotency-Key header standardises this pattern for HTTP APIs; providers' implementations vary, so read their documentation.

How do delivery receipts work?

Delivery status arrives later as events: from webhooks for WhatsApp and most REST APIs, and from deliver_sm receipts on SMPP. Status meanings differ by channel; our guide to message delivery status explains each one.

Illustrative status webhook

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

Handle status events defensively:

• Deduplicate on event_id, or on message ID plus status.
• Never regress a message from read back to delivered when events arrive out of order.
• Respond with 2xx quickly, then process from a queue.
• Record error codes for failed messages, and decide which are retryable.
• Expect gaps: some SMS routes return limited receipts, and read status depends on the channel and the user's settings.

How should you handle retries and rate limits?

Retry only what can succeed, back off exponentially with jitter, and respect the server's signals.

RFC 9110 defines the Retry-After header, which can carry seconds or a date. Put a client-side rate limiter in front of your sends so you stay under the provider's documented limits rather than discovering them through errors. WhatsApp also has Meta-side limits on how many unique customers you can message, described in messaging limits and quality rating.

How should you test before going live?

Test failure paths, not just the happy path.

Pre-production checklist

1. Send each template with real-length values, including Arabic text.
2. Force a timeout and confirm the retry does not duplicate.
3. Send to an invalid number and confirm the error is handled without retry.
4. Replay a webhook twice and out of order; confirm one final state.
5. Send a webhook with a bad signature; confirm it is rejected.
6. Trigger 429s with a load test against the sandbox, if allowed.
7. Rotate an API key and confirm no downtime.
8. Check logs contain message IDs but not full message bodies or OTP codes.
9. Run a small production pilot with internal numbers on each channel.

Sandboxes rarely reproduce carrier and Meta behaviour exactly, so keep monitoring in the first weeks of production.

Worked example: an OTP and order-notification service

"Qafilah Logistics" (synthetic), a parcel company in Saudi Arabia, sends WhatsApp order updates with SMS fallback and authentication OTPs.

• Architecture: order events go to a queue; a sender worker calls the REST API with an idempotency key of shipment-id:event.
• Fallback: if WhatsApp returns a failed status for a non-WhatsApp user, the worker sends an SMS with a new key, shipment-id:event:sms.
• OTP: codes expire quickly, so OTP sends are not retried after the expiry window; the user requests a new code instead. See the OTP authentication messages guide.
• Receipts: a webhook receiver verifies signatures, deduplicates events and updates a status table that never regresses.
• Limits: a token-bucket limiter caps send rate per channel below documented limits.

What are the common integration mistakes?

• Treating "accepted" as "delivered".
• Retrying with a new idempotency key on every attempt.
• Doing heavy processing inside the webhook request.
• Skipping signature verification on webhooks.
• Retrying 4xx validation errors in a loop.
• Logging OTP codes and full message content.
• Using production credentials in test environments.

How OmniChannels.ai helps

OmniChannels.ai, powered by BroadNet Technologies, offers a publicly documented REST/JSON API with an OpenAPI 3.1 spec and a TypeScript SDK, covering SMS, WhatsApp, RCS, Messenger, Instagram, Telegram, email and push, including WhatsApp authentication templates with one-tap, zero-tap and copy-code OTP. Webhooks report delivery statuses in one normalised format, SMPP 3.4 over TLS serves high-volume SMS, and an MCP server connects AI agents. Delivery reports with filters and CSV export help you reconcile what your integration sent. Start with the developer docs and the quickstart.