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.

POST

/workspaces/{workspaceId}/connectors

Create a new connector from a template.

Anfrage-Payload

name

string

erforderlich

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

Antwort-Payload

string

erforderlich

The ID of this connector.

workspaceId

string

The ID of the workspace this connector belongs to.

routingKey

string

name

string

erforderlich

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

Untergeordnete Attribute anzeigen

channel.channelId

string

erforderlich

channel.platform

string

erforderlich

number

object

Untergeordnete Attribute anzeigen

number.profileId

string

erforderlich

number.numberId

string

erforderlich

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

Untergeordnete Attribute anzeigen

number.profileAttachments.capability

string

number.profileAttachments.profileId

string

number.profileAttachments.variables

object

Untergeordnete Attribute anzeigen

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

Untergeordnete Attribute anzeigen

dataFetching.schedule

string

dataFetching.streams

array of object

Untergeordnete Attribute anzeigen

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

Untergeordnete Attribute anzeigen

dataCapture.captureEndpoint

string

createdAt

string

erforderlich

When the connector was created.

updatedAt

string

When the connector was last updated.

Codebeispiel

curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/connectors' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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. For SMS connectors (sms-messagebird:1), it is a required field. channelMessageType is required and must be one of: promotional, transactional, conversational, emergency, 2fa.
channelConversationalStatusEnabled	boolean	If true incoming messages will create new conversations in Inbox

Example request

Codebeispiel

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

/workspaces/{workspaceId}/connectors

Get list of available connectors for this workspace.

Abfrageparameter

templateRef

string

Filter connectors by template ref

limit

integer

Limits the number of results to return.

pageToken

string

The cursor that keeps track of the current position in the results.

reverse

boolean

Reverses the order in which the results are returned.

includeInternal

boolean

Include internal ReleaseStatus in the result

Antwort-Payload

results

array of object

erforderlich

Untergeordnete Attribute anzeigen

results.id

string

erforderlich

The ID of this connector.

results.workspaceId

string

The ID of the workspace this connector belongs to.

results.routingKey

string

results.name

string

erforderlich

The Name of this connector.

results.region

string

The Region in which this connector was installed in.

results.description

string

The Description of this connector.

results.arguments

object

Pre-configured arguments for this connector.

results.channel

object

Untergeordnete Attribute anzeigen

results.channel.channelId

string

erforderlich

results.channel.platform

string

erforderlich

results.number

object

Untergeordnete Attribute anzeigen

results.number.profileId

string

erforderlich

results.number.numberId

string

erforderlich

results.number.phoneNumber

string

results.number.variables

object

results.number.capabilities

string

Capabilities of a number. That would be represented with joined string of capabilities with comma.

results.number.numberType

string

Type of the number; could be mobile, tollfree, local, etc.

results.number.endpointType

string

Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc.

results.number.country

string

Country code of the number.

results.number.profileAttachments

array of object

Untergeordnete Attribute anzeigen

results.number.profileAttachments.capability

string

results.number.profileAttachments.profileId

string

results.number.profileAttachments.variables

object

Untergeordnete Attribute anzeigen

results.number.profileAttachments.variables.connectorId

string

results.connectorTemplateSlug

string

The slug for the template this connector is based on.

results.connectorTemplateRef

string

The ref for the template this connector is based on.

results.dataFetching

object

Untergeordnete Attribute anzeigen

results.dataFetching.schedule

string

results.dataFetching.streams

array of object

Untergeordnete Attribute anzeigen

results.dataFetching.streams.eventName

string

results.dataFetching.streams.streamName

string

results.dataFetching.streams.eventStreamName

string

results.dataFetching.streams.filter

string

results.dataFetching.streams.initialState

string

results.dataFetching.streams.endCondition

string

results.dataFetching.streams.incremental

boolean

results.dataFetching.streams.duplicatesFilterCapacity

number

results.dataFetching.streams.cursorField

string

results.dataCapture

object

Untergeordnete Attribute anzeigen

results.dataCapture.captureEndpoint

string

results.createdAt

string

erforderlich

When the connector was created.

results.updatedAt

string

When the connector was last updated.

nextPageToken

string

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

Codebeispiel

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/connectors' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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

GET

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

Show the details of a specific connector.

Antwort-Payload

string

erforderlich

The ID of this connector.

workspaceId

string

The ID of the workspace this connector belongs to.

routingKey

string

name

string

erforderlich

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

Untergeordnete Attribute anzeigen

channel.channelId

string

erforderlich

channel.platform

string

erforderlich

number

object

Untergeordnete Attribute anzeigen

number.profileId

string

erforderlich

number.numberId

string

erforderlich

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

Untergeordnete Attribute anzeigen

number.profileAttachments.capability

string

number.profileAttachments.profileId

string

number.profileAttachments.variables

object

Untergeordnete Attribute anzeigen

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

Untergeordnete Attribute anzeigen

dataFetching.schedule

string

dataFetching.streams

array of object

Untergeordnete Attribute anzeigen

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

Untergeordnete Attribute anzeigen

dataCapture.captureEndpoint

string

createdAt

string

erforderlich

When the connector was created.

updatedAt

string

When the connector was last updated.

Codebeispiel

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/connectors/{connectorId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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

GET

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

Show the status of a specific connector.

Antwort-Payload

checks

object

Untergeordnete Attribute anzeigen

checks.runAt

string

checks.results

array of object

Untergeordnete Attribute anzeigen

checks.results.name

string

checks.results.displayName

string

checks.results.status

string

Possible values: invalid, ok, warning, error, indeterminate

checks.results.assertions

array of object

Untergeordnete Attribute anzeigen

checks.results.assertions.name

string

checks.results.assertions.status

string

Possible values: invalid, ok, warning, error, indeterminate

checks.results.assertions.message

string

channel

object

Untergeordnete Attribute anzeigen

channel.channelId

string

channel.platformName

string

channel.status

string

Possible values: ok, pending, error, unknown

channel.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

channel.errorMessage

string

dataCapture

object

Untergeordnete Attribute anzeigen

dataCapture.status

string

Possible values: ok, pending, error, unknown

dataCapture.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

dataCapture.errorMessage

string

dataFetching

object

Untergeordnete Attribute anzeigen

dataFetching.schedule

string

dataFetching.streams

string

dataFetching.status

string

Possible values: ok, pending, error, unknown

dataFetching.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

dataFetching.disabled

boolean

dataFetching.disabledAt

string

dataFetching.errorMessage

string

dataFetching.lastExecution

object

Untergeordnete Attribute anzeigen

dataFetching.lastExecution.status

string

dataFetching.lastExecution.startedAt

string

dataFetching.lastExecution.endedAt

string

dataFetching.lastExecution.duration

number

dataFetching.lastExecution.errorMessage

string

engagements

object

Untergeordnete Attribute anzeigen

engagements.lakeletId

string

engagements.status

string

Possible values: ok, pending, error, unknown

engagements.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

engagements.errorMessage

string

number

object

Untergeordnete Attribute anzeigen

number.numberId

string

number.profileId

string

number.phoneNumber

string

number.status

string

Possible values: ok, pending, error, unknown

number.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

number.errorMessage

string

dataFlows

object

Untergeordnete Attribute anzeigen

dataFlows.status

string

Possible values: ok, pending, error, unknown

dataFlows.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

dataFlows.errorMessage

string

dataFlows.dataFlows

object

dataHubCatalog

object

Untergeordnete Attribute anzeigen

dataHubCatalog.status

string

Possible values: ok, pending, error, unknown

dataHubCatalog.stage

string

Possible values: active, inactive, provisioning, deprovisioning, deprovisioned

dataHubCatalog.errorMessage

string

dataHubCatalog.catalogs

array of object

Untergeordnete Attribute anzeigen

dataHubCatalog.catalogs.name

string

dataHubCatalog.catalogs.version

string

dataHubCatalog.catalogs.models

array of string

Codebeispiel

curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/connectors/{connectorId}/status' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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}

Delete a specific connector.

Codebeispiel

curl -X DELETE 'https://api.bird.com/workspaces/{workspaceId}/connectors/{connectorId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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

POST

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

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.

Anfrage-Payload

service

string

erforderlich

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

Possible values: channels, numbers, payments, conversations, templates

event

string

erforderlich

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

eventFilters

array of object

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.

Untergeordnete Parameter anzeigen

eventFilters.key

string

erforderlich

Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId

eventFilters.value

string

erforderlich

template

string

url

string

erforderlich

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.

signingKey

string

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

oauth2

object

OAuth 2.0 client credentials configuration.

Untergeordnete Parameter anzeigen

oauth2.tokenUrl

string

erforderlich

The OAuth 2.0 token endpoint where access tokens are requested.

oauth2.clientId

string

erforderlich

The OAuth 2.0 client identifier.

oauth2.clientSecret

string

erforderlich

The OAuth 2.0 client secret.

oauth2.scopes

array of string

OAuth 2.0 scopes to request.

Antwort-Payload

string

erforderlich

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

organizationId

string

erforderlich

workspaceId

string

erforderlich

service

string

erforderlich

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

Possible values: channels, numbers, payments, conversations, templates

event

string

erforderlich

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

eventFilters

array of object

Untergeordnete Attribute anzeigen

eventFilters.key

string

erforderlich

Possible values: channelId, platformId, channelStatus, interactionType, messageStatus, status, eventDestination, navigatorId

eventFilters.value

string

erforderlich

template

string

Used for our Exit APIs for Twilio and Sinch. More information can be found here for Twilio and here for Sinch.

url

string

erforderlich

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.

signingKey

string

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

oauth2

object

OAuth 2.0 client credentials configuration.

Untergeordnete Attribute anzeigen

oauth2.tokenUrl

string

erforderlich

The OAuth 2.0 token endpoint where access tokens are requested.

oauth2.clientId

string

erforderlich

The OAuth 2.0 client identifier.

oauth2.scopes

array of string

OAuth 2.0 scopes to request.

status

string

erforderlich

Possible values: active, inactive

statusReason

string

A human-readable explanation for the current status of the webhook subscription.

createdAt

string

updatedAt

string

Codebeispiel

curl -X POST 'https://api.bird.com/organizations/{organizationId}/workspaces/{workspaceId}/webhook-subscriptions' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'

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.

Codebeispiel

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

Codebeispiel

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