# MessageHub API

> A public guide, no login needed, to connect your system to MessageHub: send WhatsApp, Messenger, Instagram, Telegram and TikTok messages, and receive customer replies with signed webhooks, with ready examples in cURL, Node.js, Python and PHP.

MessageHub is a messaging platform. Its public REST API (v1) sends messages over WhatsApp, Messenger, Instagram, Telegram and TikTok, reports delivery status, and notifies your server of customer replies through signed webhooks. Base URL: https://derha.net/api/v1. Authentication: `Authorization: Bearer <token>`. All bodies are JSON (UTF-8). Sending is asynchronous: `POST /v1/messages/send` answers 202 and the final status comes from `GET /v1/messages/show/{id}` or a webhook. Branch on the error `code`, never on `message`. No login is needed to read this documentation.

## Documentation

- [Full documentation, English (one Markdown file)](https://derha.net/llms-full.txt): every endpoint, parameter, webhook event, signature verification code and error code. Read this first.
- [Full documentation, Arabic (one Markdown file)](https://derha.net/llms-full.ar.txt): the same content in Arabic.
- [OpenAPI 3.1 specification](https://derha.net/api-docs/openapi.json): machine-readable endpoints for client generation and tool definitions.
- [Documentation page, English](https://derha.net/api-docs/en/): the same content as HTML.
- [Documentation page, Arabic](https://derha.net/api-docs/): the same content as HTML.

## Endpoints

- `GET /v1/businesses`: List businesses and channels
- `GET /v1/businesses/{id}`: Business details
- `GET /v1/numbers`: Channels
- `POST /v1/messages/send`: Send a message
- `GET /v1/custom-messages`: Custom messages
- `POST /v1/messages/send-custom`: Send a custom message
- `GET /v1/messages/show/{id}`: Message status
- `GET /v1/messages/list`: List sent messages
- `GET /v1/messages/inbound`: Incoming messages
- `GET /v1/media/{id}`: Download a file
- `GET /v1/balance`: Balance
- `GET /v1/webhooks/events`: Webhook events
- `GET /v1/webhooks`: List webhooks
- `POST /v1/webhooks/{id}/test`: Send a test event
- `GET /v1/webhooks/deliveries`: Delivery log
- `POST /v1/webhooks/deliveries/{id}/redeliver`: Resend an event

## Rules to follow when writing code against this API

- Name the recipient one way only: `to` with `number_id`, or `conversation_id` alone, or `contact_id` with `number_id`.
- Send an `Idempotency-Key` header with every send so a retry never duplicates the message.
- Phone numbers are international digits with the country code and no plus sign, for example 201014642581.
- Verify `X-MessageHub-Signature-256` (HMAC-SHA256 of "timestamp.rawBody") on every webhook, reject timestamps older than 5 minutes, and skip event ids already processed.
- Answer webhooks with 2xx within 5 seconds, then process in the background.
- Instagram, Messenger and TikTok do not let the business write first; read `can_initiate` from `GET /v1/numbers`.
- Webhooks are created in the dashboard only, not through the API. Bulk sending is not available.
- Do not use endpoints or fields that are not documented here.

## Optional

- [Error codes](https://derha.net/api-docs/en/#errors): 33 stable codes with HTTP status and meaning.