Installing an SMS channel

It is possible to install an SMS channel via the connectors API.

Channels are created by first installing a new connector. Connectors are responsible for linking the MessageBird Engagements platform to third-party platforms.

Installing an SMS connector

In order to create an SMS connector, you must have a valid phoneNumberId and perform an HTTP request to the following endpoint with a valid access key.

Create a new connector from a template.

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

Body

application/json

namestringRequired

connectorTemplateRefstringOptional

channelConversationalStatusEnabledboolean · nullableOptional

invitationTokenstring · nullableOptional

Responses

201

OK

application/json

404

workspace not found

application/json

409

connector already exists

application/json

422

invalid data provided

application/json

post

/workspaces/{workspaceId}/connectors

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/connectors HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "name": "text",
  "connectorTemplateRef": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "securityArguments": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "channelConversationalStatusEnabled": true,
  "invitationToken": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "text",
  "description": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "channel": {
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "platform": "text"
  },
  "number": {
    "profileId": "123e4567-e89b-12d3-a456-426614174000",
    "numberId": "123e4567-e89b-12d3-a456-426614174000",
    "phoneNumber": "text",
    "variables": {},
    "capabilities": "mms-inbound,mms-outbound,sms-inbound,sms-outbound",
    "numberType": "mobile",
    "endpointType": "alpha-number",
    "country": "NL",
    "profileAttachments": [
      {
        "capability": "text",
        "profileId": "text",
        "variables": {
          "connectorId": "text"
        }
      }
    ]
  },
  "connectorTemplateSlug": "text",
  "connectorTemplateRef": "text",
  "dataFetching": {
    "schedule": "text",
    "streams": [
      {
        "eventName": "text",
        "streamName": "text",
        "eventStreamName": "text",
        "filter": "text",
        "initialState": "text",
        "endCondition": "text",
        "incremental": true,
        "duplicatesFilterCapacity": 1,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2026-01-29T00:07:20.456Z",
  "updatedAt": "2026-01-29T00:07:20.456Z"
}

Example request

To create an SMS channel, be aware that phoneNumberId and channelMessageType are required arguments.

Request

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "connectorTemplateRef": "sms-messagebird:1",
    "name": "My SMS channel",
    "arguments": {
        "phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29",
        "useCaseId": "be123b02-dacf-31f9-b3e5-50b18260bc23",
        "channelMessageType": "transactional"
    },
    "channelConversationalStatusEnabled": true
}'

Parameter description

Get your channel ID

Once you have created your SMS connector, this will create an SMS channel. You can then get your channel ID as follows:

Show the details of a specific connector.

get

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

connectorIdstring · uuidRequired

Responses

200

OK

application/json

404

connector not found

application/json

get

/workspaces/{workspaceId}/connectors/{connectorId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/connectors/{connectorId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "text",
  "description": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "channel": {
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "platform": "text"
  },
  "number": {
    "profileId": "123e4567-e89b-12d3-a456-426614174000",
    "numberId": "123e4567-e89b-12d3-a456-426614174000",
    "phoneNumber": "text",
    "variables": {},
    "capabilities": "mms-inbound,mms-outbound,sms-inbound,sms-outbound",
    "numberType": "mobile",
    "endpointType": "alpha-number",
    "country": "NL",
    "profileAttachments": [
      {
        "capability": "text",
        "profileId": "text",
        "variables": {
          "connectorId": "text"
        }
      }
    ]
  },
  "connectorTemplateSlug": "text",
  "connectorTemplateRef": "text",
  "dataFetching": {
    "schedule": "text",
    "streams": [
      {
        "eventName": "text",
        "streamName": "text",
        "eventStreamName": "text",
        "filter": "text",
        "initialState": "text",
        "endCondition": "text",
        "incremental": true,
        "duplicatesFilterCapacity": 1,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2026-01-29T00:07:20.456Z",
  "updatedAt": "2026-01-29T00:07:20.456Z"
}

Request

The following example will get the connector you have created in the previous step. Parse the channel.channelId to get the id of your new SMS channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors/<your-connector-id>' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'

Installation scenarios

Getting a valid phoneNumberId or useCaseId can have different prerequisites depending on the Endpoint type. See the quick starts for some common scenarios:

Country	Endpoint Type	Number type	Guide
🇺🇸 United States	Long code	Local	US 10DLC API Installation
🌐 Global	Long code, Alphanumeric & Short code	-	See below

Global installation scenario

The generic method for installing an SMS is described below. More specific scenarios are listed in the table above.

In principle, the following steps need to be followed to set up a channel programmatically:

1. Buy or request a sender: a phone number, alphanumeric sender, or short code (including the relevant KYC process, depending on the type of sender and country).

2. Set up a use case.

3. Link the use case to a sender.

4. Install the SMS channel.

1. Buy or Request a sender

For more in-depth information about this step, see the Numbers API Specifications.

2. Set up a use case

This step is documented at the SMS Use Cases documentation page.

3. Link the use case to a sender

Request

The following example will link the created use case to a sender.

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/endpoints/<your-endpoint-id>/compliance-requirements/use-case-sms' \
-X PUT \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data-raw '{
    "type": "use-case",
    "useCaseId": "<created-use-case-id>"
}'

More information about this can be found in the Update Workspace Compliance Requirements section.

4. Install the SMS channel

This final step is explained in more detail at the top of this page.