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

Authorization

Path parameters

workspaceId*string (uuid)

Body

name*connector name

connectorTemplateReftemplate to base this connector on by ref

argumentsarguments to provide to each action invocation on this connector

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.

Response

Body

id*string (uuid)

The ID of this connector.

workspaceIdstring (uuid)

The ID of the workspace this connector belongs to.

routingKeynullable string

name*string

The Name of this connector.

regionstring

The Region in which this connector was installed in.

descriptionstring

The Description of this connector.

argumentsnullable object

Pre-configured arguments for this connector.

channelChannelConfig (object)

numbernullable NumberConfig (object)

connectorTemplateSlugstring

The slug for the template this connector is based on.

connectorTemplateRefstring

The ref for the template this connector is based on.

dataFetchingThe connector's data fetching synchronisation configuration and state.

dataCapturenullable object

createdAt*string (date-time)

When the connector was created.

updatedAtstring (date-time)

When the connector was last updated.

Request

Response

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

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

Authorization

Path parameters

workspaceId*string (uuid)

Query parameters

Response

Body

results*array of Connector

nextPageTokenstring

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

Request

Response

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

Channel Connector

templateRef

SMS

sms-messagebird:1

whatsapp:1

Instagram

instagram:1

Facebook messenger

facebook:1

telegram:1

Line

line:1

email-messagebird:1

Get a connector

Show the details of a specific connector.

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

Authorization

Path parameters

workspaceId*string (uuid)

connectorId*string (uuid)

Response

Body

id*string (uuid)

The ID of this connector.

workspaceIdstring (uuid)

The ID of the workspace this connector belongs to.

routingKeynullable string

name*string

The Name of this connector.

regionstring

The Region in which this connector was installed in.

descriptionstring

The Description of this connector.

argumentsnullable object

Pre-configured arguments for this connector.

channelChannelConfig (object)

numbernullable NumberConfig (object)

connectorTemplateSlugstring

The slug for the template this connector is based on.

connectorTemplateRefstring

The ref for the template this connector is based on.

dataFetchingThe connector's data fetching synchronisation configuration and state.

dataCapturenullable object

createdAt*string (date-time)

When the connector was created.

updatedAtstring (date-time)

When the connector was last updated.

Request

Response

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

Authorization

Path parameters

workspaceId*string (uuid)

connectorId*string (uuid)

Response

Body

checksConnectorStatusConfigCheck (object)

channelnullable object

dataCapturenullable object

dataFetchingnullable object

engagementsnullable object

numbernullable object

dataFlowsnullable object

Request

Response

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}

Authorization

Path parameters

workspaceId*string (uuid)

connectorId*string (uuid)

Response

Request

Response

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

The first step to receiving notifications via webhooks is to create a subscription. A webhook subscription allows you to specify where events should be sent and how they should be filtered. When setting up a subscription, you can define which events should be directed to the chosen URL. Additionally, you can create multiple webhook subscriptions to route events to different URLs as needed.

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

Authorization

Path parameters

workspaceId*Workspace ID

The ID for the workspace.

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

organizationId*Organization ID

The ID for the organization.

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

Body

service*enum

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

Example: "channels"

channelsnumberspaymentsconversations

event*string

The name of the event is used to identify the event that is sent to the webhook. For example, to get events regarding SMS messages being sent (outbound), the name of the event would be sms.outbound.

Example: "sms.outbound"

eventFiltersnullable array of WebhookEventFilter (object)

templatestring

url*URL

The URL of the webhook is used to send events to the webhook. The URL must be a valid URL that is accessible from the internet. For example, if you want to send events to a webhook that is hosted at "https://example.com/webhook", the URL would be "https://example.com/webhook".

Example: "https://example-site.com/resource"

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

signingKeysigningKey

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

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

Response

The webhook subscription was created successfully.

Body

id*string (uuid)

The unique identifier for the webhook subscription. This identifier is used to reference the webhook subscription in other API calls.

organizationId*string (uuid)

workspaceId*string (uuid)

service*string

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

Example: "channels"

event*string

Example: "sms.outbound"

eventFiltersarray of WebhookEventFilter (object)

templatestring

url*URL

Example: "https://example-site.com/resource"

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

signingKeysigningKey

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

Example: "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk="

status*WebhookSubscriptionStatus (enum)

activeinactive

createdAtstring (date-time)

updatedAtstring (date-time)

Request

const response = await fetch('/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "service": "channels",
      "event": "sms.outbound",
      "url": "https://example-site.com/resource"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "service": "channels",
  "event": "sms.outbound",
  "eventFilters": [
    {
      "key": "channelId",
      "value": "58c44c1d-a6a0-4cb6-9f78-05308de87451"
    }
  ],
  "template": "text",
  "url": "https://example-site.com/resource",
  "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=",
  "status": "active",
  "createdAt": "2024-11-21T08:45:18.566Z",
  "updatedAt": "2024-11-21T08:45:18.566Z"
}

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 2 months ago

Create a webhook subscription

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

const response = await fetch('/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions', { method: 'POST', headers: { "Authorization": "Bearer jwt", "Content-Type": "application/json" }, body: JSON.stringify({ "service": "channels", "event": "sms.outbound", "url": "https://example-site.com/resource" }), }); const data = await response.json();

{ "id": "123e4567-e89b-12d3-a456-426614174000", "organizationId": "123e4567-e89b-12d3-a456-426614174000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "service": "channels", "event": "sms.outbound", "eventFilters": [ { "key": "channelId", "value": "58c44c1d-a6a0-4cb6-9f78-05308de87451" } ], "template": "text", "url": "https://example-site.com/resource", "signingKey": "KeV+/HGoIQrxuE5YPCRR6AuQOJveldYNNhbVi1i22qk=", "status": "active", "createdAt": "2024-11-21T08:45:18.566Z", "updatedAt": "2024-11-21T08:45:18.566Z" }

Create a connector

Create a new connector from a template.

Supported channel connectors

Properties

Example request

List connectors

Get list of available connectors for this workspace.

Filter by channel connector template

Get a connector

Show the details of a specific connector.

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

Show the status of a specific connector.

Delete a connector

Delete a specific connector.

(Optional) create a workspace subscription to list to channel related events

Create a webhook subscription

Channel creation Subscription

Channel Updates Subscription

Create a new connector from a template.

Get list of available connectors for this workspace.

Show the details of a specific connector.

Show the status of a specific connector.

Delete a specific connector.

Create a webhook subscription