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

Path parameters

workspaceIdstring · uuidRequired

Body

namestringRequired

connectorTemplateRefstringOptional

channelConversationalStatusEnabledboolean | nullableOptional

invitationTokenstring | nullableOptional

Responses

201

application/json

404

workspace not found

application/json

409

connector already exists

application/json

422

invalid data provided

application/json

post

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": "2025-10-16T01:19:02.557Z",
  "updatedAt": "2025-10-16T01:19:02.557Z"
}

Example request

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

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

Property

Type

Required

Description

connectorTemplateRef

string

Yes

Set as sms-messagebird:1

name

string

Yes

The name of your connector e.g. My SMS channel.

arguments.phoneNumberId

string

Yes

The ID of the endpoint that will be installed.

arguments.useCaseId

string

Conditional

The ID of the use case. Required for endpoint type longcode + local + US.

arguments.channelMessageType

string

Yes

The message type for the channel to be created. Possible values: promotional, 2fa, conversational, transactional, emergency. Required for all SMS channels.

channelConversationalStatusEnabled

boolean

If true, incoming messages will create new conversations in Inbox.

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

Path parameters

workspaceIdstring · uuidRequired

connectorIdstring · uuidRequired

Responses

200

application/json

404

connector not found

application/json

get

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": "2025-10-16T01:19:02.557Z",
  "updatedAt": "2025-10-16T01:19:02.557Z"
}

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:

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).
Set up a use case.
Link the use case to a sender.
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

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.

Last updated 12 days ago

Was this helpful?