Connect your system to MessageHub in minutes

Quickstart in 5 minutes #

Five steps: a key, a channel id, your first message, its status, then your customers’ replies.

1. Create an API key. In the dashboard open "Developer API", then "Keys", and create a key. The token is shown once only, so copy it and keep it on your server. The workspace needs API message balance, or requests answer with the code api_not_enabled.
2. Find the channel you will send from: GET /v1/numbers, then copy the id of a channel whose status is connected.
3. Send your first message: POST /v1/messages/send. The server answers at once with 202 and the message id. The actual sending happens after that.
4. Follow the status: GET /v1/messages/show/{id}. A message goes through queued, sent, delivered and read, or ends as failed.
5. Receive replies: in "Webhooks" add an HTTPS URL on your server and choose the event message.received. You get a signed POST for every new customer message.

Step 2: your channels

curl https://derha.net/api/v1/numbers \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

Step 3: your first message

curl -X POST https://derha.net/api/v1/messages/send \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821" \
  -d '{
  "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "to": "201014642581",
  "type": "text",
  "text": "Hello, your order #4821 has shipped."
}'

Step 4: the status

curl https://derha.net/api/v1/messages/show/3c9d8e7f-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

For AI models and tools #

This page is plain static HTML with no JavaScript needed, so any crawler or AI model can read it directly. For a lighter or machine-readable form, these public files exist:

Summary for a model writing code

• Base URL: https://derha.net/api/v1. JSON, UTF-8. HTTPS only.
• Authentication: header Authorization: Bearer <token> on every request. Never put the token in browser code.
• Every response is { success, message, data } on success and { success:false, code, message } on error. Branch on code, never on message.
• Sending is asynchronous: POST /messages/send answers 202 only, and the final result comes from GET /messages/show/{id} or a webhook.
• Send an Idempotency-Key with every send so a retry never duplicates the message.
• Name the recipient one way only: to with number_id, conversation_id alone, or contact_id with number_id.
• Verify the signature of every webhook before trusting it, and use the event id to skip duplicates.
• Do not invent endpoints or fields that are not listed here. The endpoints in this documentation are everything available.

Core concepts #

Authentication #

Every request carries the key token in the Authorization header as a Bearer token. The token is issued once, when the key is created, and cannot be retrieved afterwards. It starts with mh_live.

Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret

A key can be restricted to certain IP addresses or origins. A request from a place that is not allowed answers ip_not_allowed or origin_not_allowed. A request over plain HTTP is refused with insecure_transport.

Conventions #

Response envelope

Every response has the same shape. Success carries success=true with a data object. An error carries success=false with a stable code (safe to branch on) and a readable message.

// success
{ "success": true, "message": "...", "data": { } }

// error
{ "success": false, "code": "validation_failed", "message": "..." }

Idempotency

When sending, add an Idempotency-Key header with a value unique to the operation, such as the order number. If you replay the same request after a network drop you get the same result and the message is not sent twice. The same value with a different body answers idempotency_key_reused, and a request still being processed answers request_in_progress.

Rate limits

Requests are limited per key and per IP. Past the limit you get 429 with the code rate_limited and a Retry-After header holding the seconds to wait. Wait that long, then retry.

Pagination

List endpoints accept page and per_page (maximum 100) and return meta.pagination with total, per_page, current_page and last_page.

Numbers and dates

• Phone numbers are international digits without +, for example 201014642581.
• Dates are ISO 8601, for example 2026-10-03T08:30:00+00:00.
• Ids are UUIDs. Message text is stored and returned exactly as sent.

Endpoints #

curl https://derha.net/api/v1/businesses \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

{
  "success": true,
  "message": "...",
  "data": {
    "businesses": [
      {
        "id": "9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
        "name": "Al Amal Store",
        "numbers": [
          {
            "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
            "name": "Sales",
            "phone": "9665xxxxxxxx",
            "channel": "whatsapp",
            "status": "connected",
            "connected": true
          }
        ]
      }
    ]
  }
}

curl https://derha.net/api/v1/businesses/9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl https://derha.net/api/v1/numbers \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
        "business_id": "9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
        "name": "Sales",
        "phone": "201014642581",
        "channel": "whatsapp",
        "handle": null,
        "can_initiate": "any",
        "status": "connected",
        "connected": true,
        "official": true,
        "mode": "conversations",
        "created_at": "2026-09-01T10:00:00+00:00"
      }
    ]
  }
}

curl -X POST https://derha.net/api/v1/messages/send \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821" \
  -d '{
  "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "to": "201014642581",
  "type": "text",
  "text": "Hello, your order #4821 has shipped."
}'

curl -X POST https://derha.net/api/v1/messages/send \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation_id": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
  "text": "We received your message."
}'

const res = await fetch("https://derha.net/api/v1/messages/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.MESSAGEHUB_TOKEN,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-4821",
  },
  body: JSON.stringify({
    number_id: "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
    to: "201014642581",
    type: "text",
    text: "Hello, your order #4821 has shipped.",
  }),
})
const data = await res.json()
if (!data.success) throw new Error(data.code)

import os, requests

res = requests.post(
    "https://derha.net/api/v1/messages/send",
    headers={
        "Authorization": "Bearer " + os.environ["MESSAGEHUB_TOKEN"],
        "Idempotency-Key": "order-4821",
    },
    json={
        "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
        "to": "201014642581",
        "type": "text",
        "text": "Hello, your order #4821 has shipped.",
    },
    timeout=10,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(data["code"])

$response = Http::withToken(env('MESSAGEHUB_TOKEN'))
    ->withHeaders(['Idempotency-Key' => 'order-4821'])
    ->post('https://derha.net/api/v1/messages/send', [
        'number_id' => '7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b',
        'to'        => '201014642581',
        'type'      => 'text',
        'text'      => 'Hello, your order #4821 has shipped.',
    ]);

{
  "success": true,
  "message": "...",
  "data": {
    "message": {
      "id": "3c9d8e7f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "to": "201014642581",
      "type": "text",
      "status": "queued",
      "created_at": "2026-07-11T10:00:00+00:00"
    }
  }
}

curl https://derha.net/api/v1/custom-messages \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl -X POST https://derha.net/api/v1/messages/send-custom \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: otp-2026-09-03-1" \
  -d '{
  "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
  "to": "201014642581",
  "custom_message_id": "lib:otp",
  "values": { "2": "482913", "3": "10 minutes" }
}'

curl https://derha.net/api/v1/messages/show/3c9d8e7f-1a2b-3c4d-5e6f-7a8b9c0d1e2f \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

{
  "success": true,
  "message": "...",
  "data": {
    "message": {
      "id": "3c9d8e7f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "send_type": "single",
      "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "to": "201014642581",
      "type": "text",
      "text": "Hello, your order #4821 has shipped.",
      "status": "delivered",
      "failure_reason": null,
      "failure_category": null,
      "failure_message": null,
      "created_at": "2026-07-11T10:00:00+00:00",
      "sent_at": "2026-07-11T10:00:01+00:00",
      "delivered_at": "2026-07-11T10:00:04+00:00",
      "read_at": null,
      "failed_at": null,
      "history": [
        { "at": "2026-07-11T10:00:00+00:00", "event": "queued" },
        { "at": "2026-07-11T10:00:01+00:00", "event": "attempt", "attempt": 1 },
        { "at": "2026-07-11T10:00:01+00:00", "event": "sent" },
        { "at": "2026-07-11T10:00:04+00:00", "event": "delivered" }
      ]
    }
  }
}

curl "https://derha.net/api/v1/messages/list?number_id=7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b&status=delivered&per_page=25" \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl "https://derha.net/api/v1/messages/inbound?since=2026-10-03T00:00:00Z&per_page=50" \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl -o photo.jpg "https://derha.net/api/v1/media/01a0ff03-16e0-7350-a174-d09c254ee041" \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl https://derha.net/api/v1/balance \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

{
  "success": true,
  "data": {
    "api_enabled": true,
    "messages": { "granted": 10000, "used": 2310, "remaining": 7690, "unlimited": false },
    "ai_points": { "granted": 500, "used": 120, "remaining": 380, "unlimited": false }
  }
}

curl https://derha.net/api/v1/webhooks/events \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl https://derha.net/api/v1/webhooks \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl -X POST https://derha.net/api/v1/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl "https://derha.net/api/v1/webhooks/deliveries?status=failed" \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

curl -X POST https://derha.net/api/v1/webhooks/deliveries/DELIVERY_ID/redeliver \
  -H "Authorization: Bearer mh_live_xxxxxxxxxxxxxxxx_your_secret"

Sending rules per platform #

Platforms differ in who may speak first and for how long a reply is allowed. Read can_initiate on channels and reply_window on every message before you send.

Text formatting

Write text with WhatsApp's markers: *bold*, _italic_, ~strike~. Telegram receives them as formatting. Instagram, Messenger and TikTok receive the words without the markers. The stored text field stays as you sent it.

Customers who asked to stop

When a customer asks the business to stop, their identity on that platform is marked, and any API send to them is refused with 409 and the code contact_opted_out. The refusal is per platform: a customer who stopped on WhatsApp is still reachable on Telegram. If the message is about their own order, booking or account (a receipt, a visit reminder, a code) send "transactional": true. That is your statement and it does not lift the opt-out. An official WhatsApp template of category MARKETING is always refused for an opted-out customer.

Webhooks #

A webhook sends your server a signed POST request for every event: a new customer message, or a status change of a message you sent. You learn what happens at once, without polling. A webhook needs no API key.

Setup

1. In "Developer API", then "Webhooks", add a URL. It must be HTTPS, public, and accept POST.
2. Choose the events, then the channels: all of them or selected ones.
3. Turn on file download links if your system will download attachments.
4. Save the signing secret, shown once, then press Test to check.

Events

You receive only what you subscribe to. New event types may be added later, so ignore a type you do not know instead of rejecting it.

Event shape

Every event is a JSON object with id (the event id), type, api_version, created_at and data. Message events carry data.message, with the same shape for incoming and outgoing messages.

{
  "id": "evt_k3j9x2m8q1w7e5r4t6y0u2i8",
  "type": "message.received",
  "api_version": "v1",
  "created_at": "2026-10-03T08:30:00+00:00",
  "data": {
    "message": {
      "id": "01a0ff03-16e0-7350-a174-d09c254ee040",
      "direction": "inbound",
      "business_id": "9b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
      "number_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "channel": "whatsapp",
      "channel_id": "7f2a1c9e-3b4d-5e6f-7a8b-9c0d1e2f3a4b",
      "conversation_id": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f",
      "from": "201014642581",
      "to": "201111229562",
      "contact": { "id": "5e6f7a8b-9c0d-1e2f-3a4b-5c6d7e8f9a0b", "name": "Ahmed", "phone": "201014642581", "handle": null },
      "reply_window": { "state": "open", "closes_at": "2026-10-04T08:29:58+00:00", "remaining_messages": null, "reason": null },
      "source": "contact",
      "api_key_id": null,
      "type": "image",
      "text": "Is this one available?",
      "attachments": [
        {
          "id": "01a0ff03-16e0-7350-a174-d09c254ee041",
          "type": "image",
          "mime_type": "image/jpeg",
          "name": null,
          "size": 34191,
          "ready": true,
          "url": "https://derha.net/api/v1/media/01a0ff03-16e0-7350-a174-d09c254ee041"
        }
      ],
      "contacts": [],
      "reply_to": null,
      "status": "received",
      "failure_reason": null,
      "sent_at": "2026-10-03T08:29:58+00:00",
      "created_at": "2026-10-03T08:30:00+00:00"
    }
  }
}

data.message fields

Verifying the signature

Verify every request before trusting it. The X-MessageHub-Signature-256 header has the form t=<time>,v1=<signature>, where the signature is the HMAC-SHA256 of "time.body" with your signing secret, in hex. Reject a request whose time is more than 5 minutes from your clock: that stops an old request being replayed. Use the body exactly as received, without re-serializing it.

import crypto from 'node:crypto'

// Read the RAW body: app.post('/webhook', express.raw({ type: 'application/json' }), handler)
export function verifyMessageHub(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = header.split(',').map((p) => p.split('='))
  const t = parts.find(([k]) => k === 't')?.[1]
  const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v)
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false

  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  return signatures.some(
    (sig) => sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)),
  )
}

// verifyMessageHub(req.body.toString('utf8'), req.get('X-MessageHub-Signature-256'), process.env.MESSAGEHUB_WEBHOOK_SECRET)

<?php
function verifyMessageHub(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    $t = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
        if ($k === 't') { $t = $v; } elseif ($k === 'v1') { $signatures[] = $v; }
    }
    if ($t === null || abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t.'.'.$rawBody, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }
    return false;
}

$raw = file_get_contents('php://input');
if (! verifyMessageHub($raw, $_SERVER['HTTP_X_MESSAGEHUB_SIGNATURE_256'] ?? '', getenv('MESSAGEHUB_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
http_response_code(200); // answer first, then process the event in a queue

import hashlib, hmac, time

def verify_messagehub(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    t, signatures = None, []
    for part in header.split(','):
        key, _, value = part.partition('=')
        if key == 't':
            t = value
        elif key == 'v1':
            signatures.append(value)
    if t is None or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

# Flask: verify_messagehub(request.get_data(), request.headers.get('X-MessageHub-Signature-256', ''), SECRET)

Rotating the secret

When you generate a new secret the previous one stays valid for 24 hours and every request carries two v1 signatures, one per secret. Update your server within that window and no event is lost.

Delivery and retries

• An event counts as delivered when your server answers any 2xx within 5 seconds.
• 5xx, 429 or a network error: retried, honouring a Retry-After header if you send one.
• Any other 4xx, or a redirect: failed for good, not retried. Redirects are not followed.
• Retries after 10 seconds, then 1 minute, 5 minutes, 30 minutes, 1 hour, 3 hours and 6 hours.
• After 20 consecutive final failures the webhook is suspended and the workspace owner is alerted.
• A successful test event resumes a suspended webhook. Any event can be resent from the log.

Receiving well

• Answer 200 quickly, then process the event in the background.
• The same event can arrive more than once. Store its id and skip duplicates.
• Arrival order is not guaranteed. Rely on created_at and on the status order: sent, delivered, read.
• Check the signature and the time before doing anything else.
• Download files from url with your API key, and retry while ready is false.
• If your server was down, catch up with GET /v1/messages/inbound, or resend failed events from the log.

Full example: a Node.js receiver

import express from 'express'
import { verifyMessageHub } from './verify.js'

const app = express()
const seen = new Set() // use Redis or a database table in production

app.post('/messagehub', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8')
  if (!verifyMessageHub(raw, req.get('X-MessageHub-Signature-256') ?? '', process.env.MESSAGEHUB_WEBHOOK_SECRET)) {
    return res.sendStatus(401)
  }
  res.sendStatus(200) // answer first, within 5 seconds

  const event = JSON.parse(raw)
  if (seen.has(event.id)) return // the same event can arrive twice
  seen.add(event.id)

  if (event.type === 'message.received') {
    const m = event.data.message
    console.log('New message from', m.from, ':', m.text)
  }
})

app.listen(3000)

File download links

The attachment url needs an API key. If your system receives webhooks without a key, turn on "file download links" for the webhook: each attachment then carries a download_url that opens without a key until download_expires_at (24 hours by default). A signed link cannot be revoked, so whoever gets it opens the file until it expires. That is why it is off by default.

Errors #

Every error returns the same envelope with a stable code you can branch on. The HTTP status alone is not enough, because several codes share one (such as 404 and 422). Branch on code. Validation errors add an errors object with per-field details.

It is safe to retry on 429 and 5xx (with an Idempotency-Key the send is not duplicated). Other 4xx errors come from the request itself: fix it instead of repeating it unchanged.

FAQ #