Channel connectors
The following endpoints are part of 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. This documentation will provide details on how to interact with these endpoints.
Create a connector
POST /workspaces/{workspaceId}/connectors HTTP/1.1
Host:
Authorization: Bearer jwt
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-07-05T19:08:45.650Z",
"updatedAt": "2025-07-05T19:08:45.650Z"
}
Supported channel connectors
Currently we support creating the following channel connectors
Properties
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 the phone number to be installed. See
arguments.useCaseId
string
The ID of the use case. Required for 10DLC numbers. See
arguments.channelMessageType
string
The type of traffic that will be sent through this channel. It is a required field.
channelConversationalStatusEnabled
boolean
If true incoming messages will create new conversations in Inbox
Example request
{
"connectorTemplateRef": "sms-messagebird:1",
"name": "My SMS channel",
"arguments": {
"phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29",
"useCaseId": "be123b02-dacf-31f9-b3e5-50b18260bc23",
"channelMessageType": "promotional"
},
"channelConversationalStatusEnabled": true
}
List connectors
Filter connectors by template ref
Limits the number of results to return
10
Pagination token that keeps of track of the current position in the list
Order in which to retrieve the results
false
Include internal ReleaseStatus in the result
false
GET /workspaces/{workspaceId}/connectors HTTP/1.1
Host:
Authorization: Bearer jwt
Accept: */*
{
"results": [
{
"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-07-05T19:08:45.650Z",
"updatedAt": "2025-07-05T19:08:45.650Z"
}
],
"nextPageToken": "text"
}
Filter by channel connector template
To filter connectors by a certain channel type use the templateRef as below:
SMS
sms-messagebird:1
whatsapp:1
instagram:1
Facebook messenger
facebook:1
Telegram
telegram:1
Line
line:1
email-messagebird:1
Get a connector
GET /workspaces/{workspaceId}/connectors/{connectorId} HTTP/1.1
Host:
Authorization: Bearer jwt
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-07-05T19:08:45.650Z",
"updatedAt": "2025-07-05T19:08:45.650Z"
}
Check the readiness of a connector and its channel to send SMS
GET /workspaces/{workspaceId}/connectors/{connectorId}/status HTTP/1.1
Host:
Authorization: Bearer jwt
Accept: */*
{
"checks": {
"runAt": "2025-07-05T19:08:45.650Z",
"results": [
{
"name": "text",
"displayName": "text",
"status": "invalid",
"assertions": [
{
"name": "text",
"status": "invalid",
"message": "text"
}
]
}
]
},
"channel": {
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"platformName": "text",
"status": "ok",
"stage": "active",
"errorMessage": "text"
},
"dataCapture": {
"status": "ok",
"stage": "active",
"errorMessage": "text"
},
"dataFetching": {
"schedule": "text",
"streams": "text",
"status": "ok",
"stage": "active",
"disabled": true,
"disabledAt": "text",
"errorMessage": "text",
"lastExecution": {
"status": "text",
"startedAt": "2025-07-05T19:08:45.650Z",
"endedAt": "2025-07-05T19:08:45.650Z",
"duration": 1,
"errorMessage": "text"
}
},
"engagements": {
"lakeletId": "123e4567-e89b-12d3-a456-426614174000",
"status": "ok",
"stage": "active",
"errorMessage": "text"
},
"number": {
"numberId": "123e4567-e89b-12d3-a456-426614174000",
"profileId": "123e4567-e89b-12d3-a456-426614174000",
"phoneNumber": "text",
"status": "ok",
"stage": "active",
"errorMessage": "text"
},
"dataFlows": {
"status": "ok",
"stage": "active",
"errorMessage": "text",
"dataFlows": {
"ANY_ADDITIONAL_PROPERTY": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"disabled": true,
"disabledAt": "2025-07-05T19:08:45.650Z",
"schedule": "text",
"lastRun": {
"id": "text",
"dataFlowId": "text",
"workspaceId": "text",
"organizationId": "text",
"status": "text",
"startedAt": "2025-07-05T19:08:45.650Z",
"endedAt": "2025-07-05T19:08:45.650Z",
"duration": 1,
"message": "text"
}
}
}
}
}
Delete a connector
Deleting a connector will also delete the associated channel. Messaging for the related channel connector will be interrupted. Be sure you want to delete the connector before proceeding
DELETE /workspaces/{workspaceId}/connectors/{connectorId} HTTP/1.1
Host:
Authorization: Bearer jwt
Accept: */*
No content
(Optional) create a workspace subscription to list to channel related events
You can create a workspace subscription to listen to Channel Status changes and/or to be informed about new channel creations via webhooks
To start receiving notifications via webhooks, the first step is to create a subscription. A webhook subscription specifies the destination URL for events and defines how they should be filtered. During setup, you can select which events to send to the specified URL. You can create multiple webhook subscriptions to route different types of events to various URLs as needed. Event filters are applied using AND operators, meaning that all specified criteria must be met for an event to be sent. If you want to handle multiple interactionTypes, you’ll need to create separate webhook subscriptions for each.
The ID for the workspace.
b4e02c85-c6d2-4b15-8885-e09671799c61
The ID for the organization.
cb28a94e-8557-4394-80ea-5bbd2170d434
POST /organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions HTTP/1.1
Host:
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 243
{
"service": "channels",
"event": "sms.outbound",
"eventFilters": [
{
"key": "channelId",
"value": "58c44c1d-a6a0-4cb6-9f78-05308de87451"
}
],
"template": "text",
"url": "https://example.com/webhook",
"signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "cb28a94e-8557-4394-80ea-5bbd2170d434",
"workspaceId": "b4e02c85-c6d2-4b15-8885-e09671799c61",
"service": "channels",
"event": "sms.outbound",
"eventFilters": [
{
"key": "channelId",
"value": "clicked"
}
],
"template": "twilio",
"url": "https://example.com/webhook",
"signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=",
"status": "active",
"createdAt": "2025-07-05T19:08:45.650Z",
"updatedAt": "2025-07-05T19:08:45.650Z"
}
Channel creation Subscription
The example below will create a workspace wide subscription tracking all channel creations. this will inform you of any new channel being created and will return you the number / sender identifier
the connectorId
and the channelId
associated with it.
curl --location 'https://api.bird.com/organizations/<your-organization-id>/workspaces/<your-workspace-id>/webhook-subscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
"service": "channels",
"event": "channel.created",
"url": "myURL.com",
"signingKey": "mysecretkey",
"eventFilters": [
]
}'
Channel Updates Subscription
The example below will create a workspace wide subscription tracking all updates regarding your channels. This is particularly useful when waiting for a channel to become active as a status update will always trigger an update event
curl --location 'https://api.bird.com/organizations/<your-organization-id>/workspaces/<your-workspace-id>/webhook-subscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
"service": "channels",
"event": "channel.updated",
"url": "myURL.com",
"signingKey": "mysecretkey",
"eventFilters": [
]
}'
Last updated
Was this helpful?