# Getting started with the Twilio Communications API

## Prerequisites

Before you begin, ensure you have the following:

1. A Twilio account: [Sign up for a free account](https://www.twilio.com/try-twilio).
2. An approved and compliant phone number or sender for SMS, MMS, WhatsApp, or RCS in your target region(s).
3. Opt-out configuration as per your regional requirements: To configure advanced opt-out see the [Customizing User's Opt-in and Opt-out Experience with Advanced Opt-Out](/docs/messaging/tutorials/advanced-opt-out). This functionality is not currently supported natively in this API.

## Authenticate your requests

The API uses basic authentication, just like our existing APIs. To authenticate, include the Basic Authentication header whose username:password pair is one of the following:

* Your Account SID and Auth Token
* Your API Key SID and API Key Secret

## Send your first message

> \[!NOTE]
>
> For this Private Beta release, the base URI for this API is `https://comms.twilio.com/preview/`. The API accepts JSON requests and returns JSON responses.

Now that you're authenticated, let's send your first message.

```bash
curl -X POST 'https://comms.twilio.com/preview/Messages' \
--header 'Content-Type: application/json' \
--data '{
    "from": {
        "address": "<Your Purchased Twilio Phone Number>",
        "channel": "SMS"
    },
    "to": [{
        "address": "+12065551337",
        "channel": "PHONE"
    }],
    "content": {
        "text": "What day is it?"
    }
}' \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

You can deliver the same message to up to 10,000 recipients in a single API request by adding more entries to the `to` array.

```bash
curl -X POST 'https://comms.twilio.com/preview/Messages' \
--header 'Content-Type: application/json' \
--data '{
    "from": {
        "address": "<Your Purchased Twilio Phone Number>",
        "channel": "SMS"
    },
    "to": [
        {
            "address": "+19143188062",
            "channel": "PHONE"
        },
        {
            "address": "+19143188063",
            "channel": "PHONE"
        }
    ],
    "content": {
        "text": "Ahoy!"
    }
}' \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

### Possible values for `channel`

When describing who you are sending `to`, the possible values are:

* `WHATSAPP`
* `PHONE`: The phone represents the text messaging app on a user's device. This is the same identifier for both RCS and SMS/MMS messages.

When describing what numbers and addresses you are sending `from`, we split RCS and SMS, so that it is possible to specify when you want to use RCS, text message, or both. The possible values in those scenarios are:

* `SMS`
* `RCS`
* `WHATSAPP`

See the [Messages API reference](/docs/api/comms/preview/Messages) for more details.

## Check message request status with the Operation resource

After sending a message, especially to many recipients, retrieving the operation lets you monitor and manage the outcome, providing transparency and control over message delivery.

When you send a message with the Create Message endpoint, the response headers include an `operationId`. Use this value to track the delivery status of the message by sending a `GET` request to the Operations endpoint.

**Request sample**:

```bash
curl -X GET "https://comms.twilio.com/preview/Messages/Operations/comms_operation_01h9krwprkeee8fzqspvwy6nq8" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
```

**Sample response**:

```json
  {
  "id": "comms_operation_01h2xcejqtf2nbrexx3vqjhp41",
  "status": "COMPLETED",
  "stats": {
    "total": 1,
    "recipients": 1,
    "attempts": 1,
    "unaddressable": 0,
    "queued": 0,
    "sent": 0,
    "scheduled": 0,
    "delivered": 1,
    "read": 0,
    "undelivered": 0,
    "failed": 0,
    "canceled": 0
  },
  "createdAt": "2024-04-05T06:20:00Z",
  "updatedAt": "2024-04-05T06:20:00Z"
}
```

For more details, see the [Fetch a Message Operation API](/docs/api/comms/preview/Messages#fetch-message-operation) reference.

## Next steps

* Learn [Operations and Message Tracking](./comms/operations-and-message-tracking).
* See the [Message Operation API reference](/docs/api/comms/preview/Messages#fetch-message-operation)