> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send SMS

> Send a plain text message over SMS or WhatsApp to one or more recipients with the Dojah Messaging API.

<div className="dj-endpoint">
  <span className={`dj-method dj-method-post`}>POST</span>
  <code>/api/v1/messaging/sms</code>
</div>

Send a plain text message over SMS or WhatsApp to one or more recipients. The response returns a message\_id you can pass to Message Status to track delivery.

## Headers

| Header          | Required | Description                                         |
| --------------- | -------- | --------------------------------------------------- |
| `Authorization` | Yes      | Your app's secret key, sent as-is — *not* `Bearer`. |
| `AppId`         | Yes      | The App ID from your dashboard.                     |
| `Content-Type`  | Yes      | `application/json`                                  |

## Body parameters

| Parameter     | Type    | Required | Description                                                                  |
| ------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `destination` | string  | Yes      | Recipient phone number. Send to several at once by comma-separating numbers. |
| `message`     | string  | Yes      | The body of the message to send.                                             |
| `channel`     | string  | Yes      | Delivery channel: `sms`, `whatsapp`, or `voice`.                             |
| `sender_id`   | string  | No       | A registered Sender ID to send from.                                         |
| `priority`    | boolean | No       | Send in priority mode. Default `false`.                                      |

## Response

Returns an `entity` with the queued message’s identifiers. Keep the `message_id` — it’s what you pass to [Message Status](/api-reference/messaging/message-status).

| Field          | Type   | Description                                                              |
| -------------- | ------ | ------------------------------------------------------------------------ |
| `status`       | string | Queue status of the message, e.g. `Sent`.                                |
| `mobile`       | string | The recipient number the message was sent to.                            |
| `message_id`   | string | Unique ID for the message — pass it to Message Status to check delivery. |
| `reference_id` | string | Reference for this send.                                                 |

## Errors

| Code  | Meaning                                                                                                             |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request — a required field is missing or malformed.                                                             |
| `401` | Unauthorized — check your `Authorization` key and `AppId`.                                                          |
| `402` | Payment required — your wallet balance is too low. [Fund your wallet](/api-reference/core-concepts/wallet-billing). |
| `422` | Unprocessable — e.g. an unregistered `sender_id` or invalid `channel`.                                              |
| `429` | Too many requests — slow your request rate and retry.                                                               |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.dojah.io/api/v1/messaging/sms" \
    -H "Authorization: {{secret_key}}" \
    -H "AppId: {{app_id}}" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": "Dojah",
      "destination": "2348012345678",
      "channel": "sms",
      "message": "Your order has shipped."
    }'
  ```

  ```js Node.js theme={null}
  const res = await fetch("https://api.dojah.io/api/v1/messaging/sms", {
    method: "POST",
    headers: {
      Authorization: process.env.DOJAH_SECRET_KEY,
      AppId: process.env.DOJAH_APP_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sender_id: "Dojah",
      destination: "2348012345678",
      channel: "sms",
      message: "Your order has shipped.",
    }),
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  res = requests.post(
      "https://api.dojah.io/api/v1/messaging/sms",
      headers={
          "Authorization": os.environ["DOJAH_SECRET_KEY"],
          "AppId": os.environ["DOJAH_APP_ID"],
      },
      json={
          "sender_id": "Dojah",
          "destination": "2348012345678",
          "channel": "sms",
          "message": "Your order has shipped.",
      },
  )
  data = res.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.dojah.io/api/v1/messaging/sms");
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: " . getenv("DOJAH_SECRET_KEY"),
      "AppId: " . getenv("DOJAH_APP_ID"),
      "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "sender_id"   => "Dojah",
      "destination" => "2348012345678",
      "channel"     => "sms",
      "message"     => "Your order has shipped.",
    ]),
  ]);
  $data = json_decode(curl_exec($ch), true);
  ```
</RequestExample>

<ResponseExample>
  ```json POST /api/v1/messaging/sms theme={null}
  {
    "entity": {
      "status": "Sent",
      "mobile": "2349069278034",
      "message_id": "dj_c8095767-c69f-4bd7-aa52-7cb469effb51",
      "reference_id": "cc7f9a23-959a-4708-ac6e-5cffec7682ba"
    }
  }
  ```
</ResponseExample>