# Send an SMS message

In order to send an SMS message in Bird CRM you will need to setup a few things. 

## Step 1: Setup your API key

To send SMS messages, you must create an Access key with the `Application Developer` role. Refer to the [Access Management](https://docs.bird.com/api/api-access/api-authorization) section to learn more. To send a message, set it up as shown below.

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FxfuuTUwJ9xZatiqcuThq%2FScreenshot%202024-12-03%20at%2010.29.36.png?alt=media&#x26;token=adcdf64f-0e1d-42f7-a630-3cd3ccae79f5" alt="" width="375"><figcaption><p>Access key setup</p></figcaption></figure>

The ability to create Access keys can be found in `Settings` -> `Security` -> `Access Keys`.

## Step 2: Setup your number

Before sending messages, ensure you have an active number. Bird CRM offers four types of numbers, you can find more details in [Numbers API](https://docs.bird.com/api/numbers-api) section, accessible through Developer Cloud:

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FdqOJpekDpgZbAzlKpBpL%2FScreenshot%202024-12-03%20at%2010.34.00.png?alt=media&#x26;token=9b8b927b-19f1-4110-9e54-3745780c61d1" alt="" width="125"><figcaption><p>Developer cloud</p></figcaption></figure>

After purchasing a number via the UI, you'll gain access to its configurations. Numbers must meet Compliance requirements, be approved, and active. Verify compliance before proceeding.

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FmH3SCqP8IHRTDkiT7Upj%2FScreenshot%202024-12-03%20at%2010.36.02.png?alt=media&#x26;token=595b01c0-7d89-46da-bad8-cd16046ff30c" alt="" width="563"><figcaption><p>Number configuration</p></figcaption></figure>

Next, set up the SMS channel by clicking `Install Channel`.

## **Step 3: Setup your channel**

The SMS channel allows message sending. After selecting `Install Channel`, complete any required compliance details for your number type. Ensure the channel is active and in good health after creation. Note that both your number and channel may take a few minutes to reach a healthy/active state.

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FOEiM2y1htgZAhOsj5Klr%2Fchannel.gif?alt=media&#x26;token=81e897a2-94d2-4478-807a-02cdf82766bd" alt="" width="375"><figcaption><p>Channel</p></figcaption></figure>

## Step 4: Send a message

With the Access key and Channel set up, you’re ready to send messages. Use the following example cURL request to send an SMS using your API key, Workspace ID and channel ID:

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/channels/123e4567-e89b-12d3-a456-426614174000/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "receiver": {
    "contacts": [
      {
        "identifierValue": "+17077066620"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "Hey, I am a message"
    }
  }
}'
```

{% endtab %}

{% tab title="Response (202 - Accepted)" %}

```json
{
    "id": "f67bc25c-3d20-4c4f-aee1-eb3a29e1f2fd",
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "sender": {
        "connector": {
            "id": "3f113682-5fa9-416e-ae2f-5314e0103505",
            "identifierValue": "+5519997193005"
        }
    },
    "receiver": {
        "contacts": [
            {
                "id": "e218e98e-ebb7-4798-b49a-ec61c0879aea",
                "identifierKey": "phonenumber",
                "identifierValue": "+17077066620",
                "platformAddress": "+17077066620",
                "countryCode": "US"
            }
        ]
    },
    "body": {
        "type": "text",
        "text": {
            "text": "Hey, I'm a message"
        }
    },
    "meta": {},
    "reference": "",
    "parts": [],
    "status": "accepted",
    "validity": 600,
    "reason": "",
    "direction": "outgoing",
    "context": {},
    "lastStatusAt": "2024-12-03T13:00:00.000Z",
    "createdAt": "2024-12-03T13:00:00.000Z",
    "updatedAt": "2024-12-03T13:00:00.000Z",
    "notification": {},
    "batchId": null
}
```

{% endtab %}
{% endtabs %}

Upon successful submission, you can check the message status.

## Step 5: Checking message status

You can verify the [message status](https://docs.bird.com/api/channels-api/message-status-and-interactions) through the following mechanisms:

### 1. UI

In the developer console, you can easily access the `Message Log` under the `SMS` section.

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FeiIGd6OADhbZz8Mf88Zr%2FScreenshot%202024-12-03%20at%2011.50.29.png?alt=media&#x26;token=a4fc7378-4458-4b9d-9fe3-2e2a2d2dbfa5" alt=""><figcaption><p>SMS Log</p></figcaption></figure>

Alternatively, you can navigate to `Manage Channels`, select `SMS`, and then choose the channel you used. After that, switch to the `Logs` tab to view the message logs.

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FZVitnChjiNhVRN494gdB%2FScreenshot%202024-12-03%20at%2011.52.03.png?alt=media&#x26;token=1904a182-e10e-49e8-9e7c-e6d981e137af" alt=""><figcaption><p>Channel Logs</p></figcaption></figure>

### 2. API

To retrieve message details via the API, refer to the [Messaging API Documentation](https://docs.bird.com/api/channels-api/api-reference/messaging#retrieving-messages). You can find more information on the available endpoints, request formats, and required parameters.

### 3. Webhook

Subscribe to the `channels` service and the `sms.outbound` event in Developer Cloud to receive updates. For additional information, refer to the [Notifications API](https://docs.bird.com/api/notifications-api). Example configuration:

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2Fb0yFr11aAth9puAlHesK%2FScreenshot%202024-12-03%20at%2010.56.38.png?alt=media&#x26;token=40b20b4d-a2a4-4516-a931-fafa9cea0aa0" alt="" width="375"><figcaption><p>Webhook</p></figcaption></figure>

## Step 6: Send a message using navigator

In addition to channels, you can also use `Navigator` to send messages. `Navigator` is a mechanism that selects the most appropriate `SMS` channel for your message and it's always recommended as the way to send SMS messages, refer to [Navigators documentation](https://docs.bird.com/api/channels-api/api-reference/navigators) for more details. The API operates similarly, but you will need to choose one of the available navigators.

In Developer Cloud, your navigators are listed as follows:

<figure><img src="https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FJwHlNckXbPXk7JpBd1lH%2FScreenshot%202024-12-03%20at%2013.41.56.png?alt=media&#x26;token=4545998a-b711-42b9-b37f-d03e27cc845b" alt=""><figcaption><p>Navigators</p></figcaption></figure>

To send messages, simply switch the endpoint to:

{% tabs %}
{% tab title="Request" %}

```bash
curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/navigators/123e4567-e89b-12d3-a456-426614174000/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "receiver": {
    "contacts": [
      {
        "identifierValue": "+17077066620"
      }
    ]
  },
  "body": {
    "type": "text",
    "text": {
      "text": "Hey, I am a message"
    }
  }
}'
```

{% endtab %}

{% tab title="Response (202 - Accepted)" %}

```json
{
    "id": "f67bc25c-3d20-4c4f-aee1-eb3a29e1f2fd",
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "sender": {
        "connector": {
            "id": "3f113682-5fa9-416e-ae2f-5314e0103505",
            "identifierValue": "+5519997193005"
        }
    },
    "receiver": {
        "contacts": [
            {
                "id": "e218e98e-ebb7-4798-b49a-ec61c0879aea",
                "identifierKey": "phonenumber",
                "identifierValue": "+17077066620",
                "platformAddress": "+17077066620",
                "countryCode": "US"
            }
        ]
    },
    "body": {
        "type": "text",
        "text": {
            "text": "Hey, I'm a message"
        }
    },
    "meta": {
        "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
        "navigatorMessageId": "f7261fa6-4c53-42e2-9771-84494d70ea6b"
    },
    "reference": "",
    "parts": [],
    "status": "accepted",
    "validity": 600,
    "reason": "",
    "direction": "outgoing",
    "context": {},
    "lastStatusAt": "2024-12-03T13:00:00.000Z",
    "createdAt": "2024-12-03T13:00:00.000Z",
    "updatedAt": "2024-12-03T13:00:00.000Z",
    "notification": {},
    "batchId": null,
    "navigatorData": {
        "attempts": [
            {
                "channelId": "5065d7a3-cefc-5cb4-ba02-ca533ece09b3",
                "platformId": "sms-messagebird",
                "messageId": "13ac9d82-ac52-4e43-bcdd-cfa0ae73a6fa",
                "attempt": 1,
                "status": "accepted",
                "createdAt": "2024-12-03T13:00:00.000Z"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/api/quickstarts/send-an-sms-message.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.