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

A-Sync : this will start a background process that may require some time to complete. A Get call may be required to retrieve the final result.

Create a new connector from a template.

post
Authorizations
Path parameters
workspaceIdstring · uuidRequired
Body
namestringRequired
connectorTemplateRefstringOptional
channelConversationalStatusEnabledboolean | nullableOptional
invitationTokenstring | nullableOptional
Responses
201
OK
application/json
post
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

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

Get list of available connectors for this workspace.

get
Authorizations
Path parameters
workspaceIdstring · uuidRequired
Query parameters
templateRefstringOptional

Filter connectors by template ref

limitinteger · max: 100Optional

Limits the number of results to return

Default: 10
pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false
includeInternalbooleanOptional

Include internal ReleaseStatus in the result

Default: false
Responses
200
OK
application/json
Responseall of
get
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:

Channel Connector
templateRef

SMS

sms-messagebird:1

WhatsApp

whatsapp:1

Instagram

instagram:1

Facebook messenger

facebook:1

Telegram

telegram:1

Line

line:1

Email

email-messagebird:1

Get a connector

Show the details of a specific connector.

get
Authorizations
Path parameters
workspaceIdstring · uuidRequired
connectorIdstring · uuidRequired
Responses
200
OK
application/json
get
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

Show the status of a specific connector.

get
Authorizations
Path parameters
workspaceIdstring · uuidRequired
connectorIdstring · uuidRequired
Responses
200
OK
application/json
get
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

Delete a specific connector.

delete
Authorizations
Path parameters
workspaceIdstring · uuidRequired
connectorIdstring · uuidRequired
Responses
204
OK
delete
DELETE /workspaces/{workspaceId}/connectors/{connectorId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

No content

You can create a workspace subscription to listen to Channel Status changes and/or to be informed about new channel creations via webhooks

Create a webhook subscription

post

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.

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID for the workspace.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61
organizationIdstring · uuidRequired

The ID for the organization.

Example: cb28a94e-8557-4394-80ea-5bbd2170d434
Body
all ofOptional
Responses
201
The webhook subscription was created successfully.
application/json
post
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?