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

# Send Message

> Description of your new file.

The **Arnio API** follows REST principles. You can use it to send outbound iMessages globally.

### **Supported Endpoints**

* **Single message:** POST /send-message
* **Group message:** POST /send-group-message

### **Sending Files**

You can send media by including the media\_url parameter.

* The URL must point to a publicly accessible image or .caf (for voice notes).
* File size is capped at **5MB**.
* Signed URLs are not supported; use Arnio’s media object pattern for secure uploads.

Learn more here:  [https://docs.arnio.co/api-reference/endpoint/send-message](https://docs.arnio.co/api-reference/endpoint/send-message)

# **Status Callbacks**

Arnio will POST to your status\_callback endpoint when a message’s status changes.

Possible statuses:

* QUEUED
* SENT
* DELIVERED (iMessage only)
* READ (iMessage only)
* FAILED

You must respond to Arnio’s webhook to prevent duplicate notifications.

```json theme={null}
{
  "accountEmail": "support@arnio.co",
  "content": "Hello world!",
  "is_outbound": true,
  "status": "DELIVERED",
  "error_code": null,
  "error_message": null,
  "message_handle": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "date_sent": "2025-09-10T06:15:05.962Z",
  "date_updated": "2025-09-10T06:15:14.115Z",
  "from_number": "+15122164639",
  "number": "+19998887777",
  "to_number": "+19998887777",
  "was_downgraded": false,
  "plan": "enterprise"
}
```

> **Note:** Your server must return a response to Arnio’s callback to prevent duplicate webhook deliveries.

### **Callback Body Fields**

| **Field**       | **Type** | **Description**                                                  |
| --------------- | -------- | ---------------------------------------------------------------- |
| accountEmail    | string   | Associated Arnio account email                                   |
| content         | string   | Message content                                                  |
| is\_outbound    | boolean  | true if sent by your system, false if received from end user     |
| media\_url      | string   | A CDN link to any attached media                                 |
| status          | string   | Current status of the message                                    |
| error\_code     | int      | Error code if the message failed, null otherwise                 |
| error\_message  | string   | Human-readable error description                                 |
| message\_handle | string   | Unique Arnio message handle (used to query message status later) |
| date\_sent      | string   | ISO 8601 timestamp of when the message was created               |
| date\_updated   | string   | ISO 8601 timestamp of the last status update                     |
| from\_number    | string   | E.164-formatted Arnio phone number used to send the message      |
| number          | string   | E.164-formatted number of the end user (your contact)            |
| to\_number      | string   | E.164-formatted number of the intended recipient                 |
| was\_downgraded | boolean  | true if iMessage was unavailable and SMS was used instead        |
| plan            | string   | Arnio account plan associated with the request                   |

### **Message Status Values**

| Status    | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| QUEUED    | Message has been validated and queued for delivery                      |
| SENT      | Message was sent from Arnio’s servers                                   |
| DELIVERED | Delivery confirmed (iMessage only)                                      |
| READ      | End user has read the message (iMessage only)                           |
| FAILED    | Message failed to send (see error\_code and error\_message for details) |

## **Limits**

Messages sent through the **Arnio API** must be fewer than **18,996 characters** in length. For longer content, we recommend splitting it into multiple, smaller messages to ensure reliable delivery.

## **Useful Information**

### **From Number**

<Danger>
  **CAUTION:** Arnio prioritizes deliverability and end-user experience. Each of your customers will consistently interact with your brand through **one dedicated Arnio phone number**, ensuring continuity and trust.
</Danger>

However, depending on your setup and number pooling configuration, different customers may see different Arnio numbers assigned to them. Once assigned, all future conversations with that contact will remain tied to the same number.

The from\_number field is included in API responses for convenience, allowing you to:

* Track which number was used to send a given message.
* Inform customers which number they should expect messages from.

### **Handle**

Every message processed by Arnio includes a unique message\_handle. You can use this handle to:

* Query the current status of a message.
* Track messages in high-volume campaigns.
* Resolve situations where a message remains QUEUED or times out.