Send an SMS message

This guide provides instructions for setting up and sending SMS messages using Bird CRM.

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 section to learn more. To send a message, set it up as shown below.

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 section, accessible through Developer Cloud:

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.

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.

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:

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"
    }
  }
}'

{
    "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
}

Upon successful submission, you can check the message status.

Step 5: Checking message status

You can verify the message status through the following mechanisms:

1. UI

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

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.

2. API

To retrieve message details via the API, refer to the Messaging API Documentation. 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. Example configuration:

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 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:

To send messages, simply switch the endpoint to:

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"
    }
  }
}'

{
    "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"
            }
        ]
    }
}

Last updated 6 months ago

Was this helpful?