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 to retrieve the final result .

Create a new connector from a template.

post

/workspaces/{workspaceId}/connectors

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

Body

nameconnector namerequired

connectorTemplateReftemplate to base this connector on by ref

securityArgumentsSecurityArgumentsMap

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

channelConversationalStatusEnabledControls the default value for channel's conversational flag.

invitationTokenInvitation token to allow installation of connectors that are not GA.

argumentsarguments to provide to each action invocation on this connector

Example: {"someArgument":"someValue"}

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

201

404

409

422

201

{
  "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-21T18:08:52.189Z",
  "updatedAt": "2025-02-21T18:08:52.189Z",
  "arguments": {
    "someArgument": "someValue"
  },
  "dataCapture": {
    "captureEndpoint": "text"
  }
}

OK

Supported channel connectors

Currently we support creating the following channel connectors

SMS

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

/workspaces/{workspaceId}/connectors

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

Query parameters

templateRefstring

Filter connectors by template ref

limitinteger · max: 100 · default: 10

Limits the number of results to return

pageTokenstring · max: 8000

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

reverseboolean

Order in which to retrieve the results

includeInternalboolean

Include internal ReleaseStatus in the result

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

200

{
  "results": [
    {
      "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-21T18:08:52.189Z",
      "updatedAt": "2025-02-21T18:08:52.189Z",
      "arguments": {
        "someArgument": "someValue"
      },
      "dataCapture": {
        "captureEndpoint": "text"
      }
    }
  ],
  "nextPageToken": "text"
}

OK

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

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

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

connectorIdstring · uuidrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

200

{
  "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-21T18:08:52.189Z",
  "updatedAt": "2025-02-21T18:08:52.189Z",
  "arguments": {
    "someArgument": "someValue"
  },
  "dataCapture": {
    "captureEndpoint": "text"
  }
}

OK

Check the readiness of a connector and its channel to send SMS

Show the status of a specific connector.

get

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

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

connectorIdstring · uuidrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

200

{
  "checks": {
    "runAt": "2025-02-21T18:08:52.189Z",
    "results": [
      {
        "name": "text",
        "displayName": "text",
        "status": "invalid",
        "assertions": [
          {
            "name": "text",
            "message": "text",
            "status": "invalid"
          }
        ]
      }
    ]
  },
  "channel": {
    "channelId": "123e4567-e89b-12d3-a456-426614174000",
    "platformName": "text",
    "errorMessage": "text",
    "status": "ok",
    "stage": "active"
  },
  "dataCapture": {
    "errorMessage": "text",
    "status": "ok",
    "stage": "active"
  },
  "engagements": {
    "lakeletId": "123e4567-e89b-12d3-a456-426614174000",
    "errorMessage": "text",
    "status": "ok",
    "stage": "active"
  },
  "number": {
    "numberId": "123e4567-e89b-12d3-a456-426614174000",
    "profileId": "123e4567-e89b-12d3-a456-426614174000",
    "phoneNumber": "text",
    "errorMessage": "text",
    "status": "ok",
    "stage": "active"
  },
  "dataFetching": {
    "schedule": "text",
    "streams": "text",
    "disabled": true,
    "disabledAt": "text",
    "errorMessage": "text",
    "status": "ok",
    "stage": "active",
    "lastExecution": {
      "status": "text",
      "startedAt": "2025-02-21T18:08:52.189Z",
      "endedAt": "2025-02-21T18:08:52.189Z",
      "duration": 1,
      "errorMessage": "text"
    }
  },
  "dataFlows": {
    "errorMessage": "text",
    "status": "ok",
    "stage": "active",
    "dataFlows": {
      "ANY_ADDITIONAL_PROPERTY": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "disabled": true,
        "disabledAt": "2025-02-21T18:08:52.189Z",
        "schedule": "text",
        "lastRun": {
          "id": "text",
          "dataFlowId": "text",
          "workspaceId": "text",
          "organizationId": "text",
          "status": "text",
          "startedAt": "2025-02-21T18:08:52.189Z",
          "endedAt": "2025-02-21T18:08:52.189Z",
          "duration": 1,
          "message": "text"
        }
      }
    }
  }
}

OK

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 a specific connector.

delete

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

Authorizations

useraccessKey

Path parameters

workspaceIdstring · uuidrequired

connectorIdstring · uuidrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

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

204

422

204

No body

OK

(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

Create a webhook subscription

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.

post

/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions

Authorizations

useraccessKey

Path parameters

workspaceIdWorkspace IDrequired

The ID for the workspace.

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

organizationIdOrganization IDrequired

The ID for the organization.

Example: cb28a94e-8557-4394-80ea-5bbd2170d434

Body

servicestring · enumrequired

The service that the webhook is subscribed to. For example, to get events regarding channels, the service would be channels.

Options: channels, numbers, payments, conversations

eventstringrequired

The event name identifies the webhook event, such as sms.outbound for notifications about SMS messages being sent.

Example: sms.outbound

templatestring

urlstringrequired

The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that respects the established pattern and is accessible from the internet.

Example: https://example.com/webhook

Pattern: ^https://([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(/[^\s]*)?$

signingKeystring

The signing key for the webhook and can be used to verify the authenticity of the webhook.

Example: KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=

eventFiltersobject[] | nullable

Filters to apply to the events that are sent to the webhook. This is a key-value list of filters that are specific to the service that the webhook is subscribed to. One example would be a key of channelId and a value of a UUID (in string format) that represents a channel.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"service":"channels","event":"sms.outbound","url":"https://example.com/webhook","signingKey":"KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=","eventFilters":[]}'

201

400

422

201

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "cb28a94e-8557-4394-80ea-5bbd2170d434",
  "workspaceId": "b4e02c85-c6d2-4b15-8885-e09671799c61",
  "service": "channels",
  "event": "sms.outbound",
  "template": "twilio",
  "url": "https://example.com/webhook",
  "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=",
  "status": "active",
  "createdAt": "2025-02-21T18:08:52.189Z",
  "updatedAt": "2025-02-21T18:08:52.189Z",
  "eventFilters": [
    {
      "value": "clicked",
      "key": "channelId"
    }
  ]
}

The webhook subscription was created successfully.

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": [
  ]
}'