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.
POST
/workspaces/{workspaceId}/connectors
Create a new connector from a template.
Verzoek-payload
name
string
verplicht
connectorTemplateRef
string
arguments
object
For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.
securityArguments
object
Provide the arguments required by the security scheme(s) on the connector template.
channelConversationalStatusEnabled
boolean
invitationToken
string
Antwoord-payload
id
string
verplicht
The ID of this connector.
workspaceId
string
The ID of the workspace this connector belongs to.
routingKey
string
name
string
verplicht
The Name of this connector.
region
string
The Region in which this connector was installed in.
description
string
The Description of this connector.
arguments
object
Pre-configured arguments for this connector.
channel
object
Onderliggende attributen tonen
channel.channelId
string
verplicht
channel.platform
string
verplicht
number
object
Onderliggende attributen tonen
number.profileId
string
verplicht
number.numberId
string
verplicht
number.phoneNumber
string
number.variables
object
number.capabilities
string
Capabilities of a number. That would be represented with joined string of capabilities with comma.
number.numberType
string
Type of the number; could be mobile, tollfree, local, etc.
number.endpointType
string
Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc.
number.country
string
Country code of the number.
number.profileAttachments
array of object
Onderliggende attributen tonen
number.profileAttachments.capability
string
number.profileAttachments.profileId
string
number.profileAttachments.variables
object
Onderliggende attributen tonen
number.profileAttachments.variables.connectorId
string
connectorTemplateSlug
string
The slug for the template this connector is based on.
connectorTemplateRef
string
The ref for the template this connector is based on.
dataFetching
object
Onderliggende attributen tonen
dataFetching.schedule
string
dataFetching.streams
array of object
Onderliggende attributen tonen
dataFetching.streams.eventName
string
dataFetching.streams.streamName
string
dataFetching.streams.eventStreamName
string
dataFetching.streams.filter
string
dataFetching.streams.initialState
string
dataFetching.streams.endCondition
string
dataFetching.streams.incremental
boolean
dataFetching.streams.duplicatesFilterCapacity
number
dataFetching.streams.cursorField
string
dataCapture
object
Onderliggende attributen tonen
dataCapture.captureEndpoint
string
createdAt
string
verplicht
When the connector was created.
updatedAt
string
When the connector was last updated.
Codevoorbeeld
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/connectors' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'Example request
To create an SMS channel, be aware that phoneNumberId and channelMessageType are required arguments.
Codevoorbeeld
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 | No | 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:
GET
/workspaces/{workspaceId}/connectors/{connectorId}
Show the details of a specific connector.
Antwoord-payload
id
string
verplicht
The ID of this connector.
workspaceId
string
The ID of the workspace this connector belongs to.
routingKey
string
name
string
verplicht
The Name of this connector.
region
string
The Region in which this connector was installed in.
description
string
The Description of this connector.
arguments
object
Pre-configured arguments for this connector.
channel
object
Onderliggende attributen tonen
channel.channelId
string
verplicht
channel.platform
string
verplicht
number
object
Onderliggende attributen tonen
number.profileId
string
verplicht
number.numberId
string
verplicht
number.phoneNumber
string
number.variables
object
number.capabilities
string
Capabilities of a number. That would be represented with joined string of capabilities with comma.
number.numberType
string
Type of the number; could be mobile, tollfree, local, etc.
number.endpointType
string
Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc.
number.country
string
Country code of the number.
number.profileAttachments
array of object
Onderliggende attributen tonen
number.profileAttachments.capability
string
number.profileAttachments.profileId
string
number.profileAttachments.variables
object
Onderliggende attributen tonen
number.profileAttachments.variables.connectorId
string
connectorTemplateSlug
string
The slug for the template this connector is based on.
connectorTemplateRef
string
The ref for the template this connector is based on.
dataFetching
object
Onderliggende attributen tonen
dataFetching.schedule
string
dataFetching.streams
array of object
Onderliggende attributen tonen
dataFetching.streams.eventName
string
dataFetching.streams.streamName
string
dataFetching.streams.eventStreamName
string
dataFetching.streams.filter
string
dataFetching.streams.initialState
string
dataFetching.streams.endCondition
string
dataFetching.streams.incremental
boolean
dataFetching.streams.duplicatesFilterCapacity
number
dataFetching.streams.cursorField
string
dataCapture
object
Onderliggende attributen tonen
dataCapture.captureEndpoint
string
createdAt
string
verplicht
When the connector was created.
updatedAt
string
When the connector was last updated.
Codevoorbeeld
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/connectors/{connectorId}' \
-H 'Authorization: AccessKey YOUR_ACCESS_KEY'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
Codevoorbeeld
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.md |
| 🌐 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.
Codevoorbeeld
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.