Dialogwa REST API Integration Guide

We eat our own dog food. The REST API you integrate is the same one our dashboard calls, so nothing is hidden behind a UI-only feature. If the dashboard can do it, your code can do it, and vice versa. This guide is the shortest path from zero to your first delivered message, written the way we would have wanted it on day one.

Authentication

Every request carries your session token. Keep it server-side. We never expect a token in the browser, and neither should you. Treat it like a password, because to a connected number it effectively is one.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Sending a message

POST /api/send
{
  "session": "sales-line",
  "to": "6281234567890",
  "message": "Your order is confirmed"
}

Media works the same way with a media field pointing at a URL or base64 payload. Images, PDFs, and documents all travel through one endpoint, so your sending code does not branch by type.

Receiving messages

You do not poll us. Set a webhook URL and we push inbound events to you the moment they arrive. The payload is flat and predictable, which keeps your parser boring and your on-call calm:

{
  "session": "sales-line",
  "from": "6281234567890",
  "message": "Where is my order?",
  "timestamp": 1710000000
}

Idempotency and retries

Webhooks can arrive more than once on a flaky network. We send a stable event id; dedupe on your side. We also retry with backoff, so a briefly dead endpoint is not a lost message. Build your handler to be safe when called twice, and most production incidents simply disappear.

A note on throughput

The API is fast, but the number behind it is not infinite. Respect the rate you configured, batch where you can, and surface session status in your UI. The cleanest integrations are the ones that degrade gracefully when a SIM drops.

The caveat

A gateway is only as reliable as the number behind it. If the WhatsApp session goes offline, sends queue and we surface the failure. Build your UI to show session status, and alert someone when a line drops. The API is solid; the SIM is the weak link, and we are honest about that.

Error handling you will thank yourself for

The integration that survives production is the one that assumes the number will go offline. We wrap every send in a check on session status and queue the message when it is down, rather than throwing. We also cap retries so a dead webhook cannot loop forever. None of this is glamorous, but it is the difference between a feature your team trusts and one it bypasses with copy-paste into the app.

Version your integrations

Because the webhook contract is plain JSON, we keep it in the same repo as the rest of the backend and review changes like any other code. When a payload field shifts, the diff is obvious and the on-call engineer is not deciphering a mystery at 3 a.m. Treat the gateway as a real dependency, pin the version you expect, and you avoid the classic failure where a silent format change quietly breaks every reply for a day.

Where to start

Send one message from a script, then add the webhook, then wrap both in error handling. That order keeps each step debuggable, and it is exactly how we onboard our own engineers.