# Raseel

> The messaging platform for serious builders.

Raseel is a unified WhatsApp messaging API with a Sandbox to try it, QR
onboarding, and an upgrade path to the Meta Cloud API. One HTTP contract; the
provider is a property of the channel you send from, not of the call you make.

## API

- Base URL: `https://whats.azzamkh.sa/api`
- Every customer-facing path begins with `/v1`. The health probes
  (`/health`, `/ready`) are unversioned.
- OpenAPI 3.1: [https://whats.azzamkh.sa/openapi.json](https://whats.azzamkh.sa/openapi.json)

## Authentication

- `Authorization: Bearer <credential>` and nothing else. **There is no
  `x-api-key` header.**
- The credential is either a workspace API key (`wa_test_…` / `wa_live_…`)
  or a user access token from `POST /v1/auth/login`.
- A user access token additionally requires `X-Workspace-Id: ws_…`. An API
  key already names its workspace and may omit it.
- Sandbox operations require a **test-mode** key; a live key is refused.

## Quickstart

- [https://whats.azzamkh.sa/en/docs/quickstart](https://whats.azzamkh.sa/en/docs/quickstart)
- Sign up → verify email → create a test API key → allocate a sandbox session
  and verify the recipient → `POST /v1/messages`.

## Documentation

- [Introduction: base URL, conventions, and what exists today](https://whats.azzamkh.sa/en/docs)
- [Quickstart: sign up, create a test key, connect a sandbox number, send](https://whats.azzamkh.sa/en/docs/quickstart)
- [Authentication: Bearer only, test vs live keys, X-Workspace-Id, scopes](https://whats.azzamkh.sa/en/docs/authentication)
- [Channels: sandbox, QR (unofficial), Meta (not yet available)](https://whats.azzamkh.sa/en/docs/channels)
- [Sending messages: POST /v1/messages, categories, idempotency, message states](https://whats.azzamkh.sa/en/docs/messages)
- [Webhooks: signature scheme, the event catalogue, retries, replay](https://whats.azzamkh.sa/en/docs/webhooks)
- [Contacts: CRUD, groups, tags, CSV/XLSX import and its dedupe rules](https://whats.azzamkh.sa/en/docs/contacts)
- [Templates: content model, variables, statuses](https://whats.azzamkh.sa/en/docs/templates)
- [Conversations: the inbox, replies, team scoping](https://whats.azzamkh.sa/en/docs/conversations)
- [Errors: the error envelope, every stable code, pagination, rate limits](https://whats.azzamkh.sa/en/docs/errors)
- [Limits: plan entitlements, HTTP rate limits, throughput, the QR safety cap](https://whats.azzamkh.sa/en/docs/limits)
- [OpenAPI and AI tools: the machine-readable document](https://whats.azzamkh.sa/en/docs/openapi)

Arabic is a full translation of every page: replace `/en/` with `/ar/`.

## Webhooks

- Register with `POST /v1/webhook-endpoints`; requires the
  `webhooks.manage` scope, which is NOT in an API key's default scope set.
- The inbound-message event is **`message.received`** (not
  `message.inbound`). Status events are `message.queued`, `message.sent`,
  `message.delivered`, `message.read` and `message.failed`.
- `GET /v1/webhook-event-types` returns the full catalogue at runtime.
- Signature: `X-Webhook-Signature: v1=<lowercase hex>`, HMAC-SHA256 over
  `"{X-Webhook-Timestamp}.{raw request body}"`. The header may carry several
  `v1=` entries during a secret rotation; accept if any matches.
- Docs: [https://whats.azzamkh.sa/en/docs/webhooks](https://whats.azzamkh.sa/en/docs/webhooks)

## Errors and rate limits

- Envelope: `{"error":{"code","message","request_id","details?"}}`. Branch on
  `code`; `message` is human text and is not stable.
- Validation failures are **422**, not 400.
- Rate limiting: `429` with `RateLimit-Limit`, `RateLimit-Remaining`,
  `RateLimit-Reset` and `Retry-After`, all in seconds.
- Pagination is cursor-based: `?limit=&after=`, response
  `{"data":[],"page":{"next_cursor","has_more"}}`.
- Docs: [https://whats.azzamkh.sa/en/docs/errors](https://whats.azzamkh.sa/en/docs/errors)

## Not yet available

Do not generate code against these; they have no endpoints and will 404.

- The Meta Cloud API provider, Meta onboarding, and template submission to Meta
- Sending media (images, documents, audio, video)
- Campaigns and automations
- Official SDKs and a published Postman collection

## Other pages

- [Home](https://whats.azzamkh.sa/en): product overview and a live `POST /v1/messages` sample
- [Pricing](https://whats.azzamkh.sa/en/pricing): launch plans and their real limits
- [Terms](https://whats.azzamkh.sa/en/terms): draft terms of service
- [Privacy](https://whats.azzamkh.sa/en/privacy): draft privacy policy

## Using this API from a coding agent

Read this file and `https://whats.azzamkh.sa/openapi.json` first. Authenticate with
`Authorization: Bearer $WA_API_KEY`, reading the key from the environment.
Never write a key into a source file.

## Contact

- Support: support@whats.azzamkh.sa