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 a HTTP request to the following endpoint with a valid access key

Create a new connector from a template.

post

/workspaces/{workspaceId}/connectors

Authorizations

Path parameters

workspaceIdstring · uuidrequired

Body

namestringrequired

connectorTemplateRefstring

securityArgumentsobject | nullable

Provide the arguments required by the security scheme(s) on the connector template.

channelConversationalStatusEnabledboolean | nullable

invitationTokenstring | nullable

argumentsobject | nullable

Example: {"someArgument":"someValue"}

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/connectors' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "connectorTemplateRef": "text",
    "securityArguments": {
      "ANY_ADDITIONAL_PROPERTY": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    },
    "channelConversationalStatusEnabled": true,
    "invitationToken": "text",
    "arguments": {
      "someArgument": "someValue"
    }
  }'

201

404

409

422

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "text",
  "description": "text",
  "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"
      }
    ]
  },
  "createdAt": "2025-02-28T01:38:09.177Z",
  "updatedAt": "2025-02-28T01:38:09.177Z",
  "arguments": {
    "someArgument": "someValue"
  },
  "dataCapture": {
    "captureEndpoint": "text"
  }
}

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"
    },
    "channelConversationalStatusEnabled": true
}'

Property

Type

Description

connectorTemplateRef

string

Set as sms-messagebird:1

name

string

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

arguments.phoneNumberId

string

The ID of endpoint that will be installed

arguments.useCaseId

string

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

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

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

Authorizations

Path parameters

workspaceIdstring · uuidrequired

connectorIdstring · uuidrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url '/workspaces/{workspaceId}/connectors/{connectorId}' \
  --header 'Authorization: Bearer jwt'

200

404

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "text",
  "description": "text",
  "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"
      }
    ]
  },
  "createdAt": "2025-02-28T01:38:09.177Z",
  "updatedAt": "2025-02-28T01:38:09.177Z",
  "arguments": {
    "someArgument": "someValue"
  },
  "dataCapture": {
    "captureEndpoint": "text"
  }
}

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 pre-requisites 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

Last updated 4 months ago

Was this helpful?