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.

Payload della richiesta

name

string

obbligatorio

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

Payload della risposta

string

obbligatorio

The ID of this connector.

workspaceId

string

The ID of the workspace this connector belongs to.

routingKey

string

name

string

obbligatorio

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

Mostra attributi secondari

channel.channelId

string

obbligatorio

channel.platform

string

obbligatorio

number

object

Mostra attributi secondari

number.profileId

string

obbligatorio

number.numberId

string

obbligatorio

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

Mostra attributi secondari

number.profileAttachments.capability

string

number.profileAttachments.profileId

string

number.profileAttachments.variables

object

Mostra attributi secondari

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

Mostra attributi secondari

dataFetching.schedule

string

dataFetching.streams

array of object

Mostra attributi secondari

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

Mostra attributi secondari

dataCapture.captureEndpoint

string

createdAt

string

obbligatorio

When the connector was created.

updatedAt

string

When the connector was last updated.

Esempio di codice

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

Esempio di codice

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

Parametri di query

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

Payload della risposta

results

array of object

obbligatorio

Mostra attributi secondari

results.id

string

obbligatorio

The ID of this connector.

results.workspaceId

string

The ID of the workspace this connector belongs to.

results.routingKey

string

results.name

string

obbligatorio

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

Mostra attributi secondari

results.channel.channelId

string

obbligatorio

results.channel.platform

string

obbligatorio

results.number

object

Mostra attributi secondari

results.number.profileId

string

obbligatorio

results.number.numberId

string

obbligatorio

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

Mostra attributi secondari

results.number.profileAttachments.capability

string

results.number.profileAttachments.profileId

string

results.number.profileAttachments.variables

object

Mostra attributi secondari

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

Mostra attributi secondari

results.dataFetching.schedule

string

results.dataFetching.streams

array of object

Mostra attributi secondari

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

Mostra attributi secondari

results.dataCapture.captureEndpoint

string

results.createdAt

string

obbligatorio

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.

Esempio di codice

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.

Payload della risposta

string

obbligatorio

The ID of this connector.

workspaceId

string

The ID of the workspace this connector belongs to.

routingKey

string

name

string

obbligatorio

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

Mostra attributi secondari

channel.channelId

string

obbligatorio

channel.platform

string

obbligatorio

number

object

Mostra attributi secondari

number.profileId

string

obbligatorio

number.numberId

string

obbligatorio

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

Mostra attributi secondari

number.profileAttachments.capability

string

number.profileAttachments.profileId

string

number.profileAttachments.variables

object

Mostra attributi secondari

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

Mostra attributi secondari

dataFetching.schedule

string

dataFetching.streams

array of object

Mostra attributi secondari

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

Mostra attributi secondari

dataCapture.captureEndpoint

string

createdAt

string

obbligatorio

When the connector was created.

updatedAt

string

When the connector was last updated.

Esempio di codice

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.

Payload della risposta

checks

object

Mostra attributi secondari

checks.runAt

string

checks.results

array of object

Mostra attributi secondari

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

Mostra attributi secondari

checks.results.assertions.name

string

checks.results.assertions.status

string

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

checks.results.assertions.message

string

channel

object

Mostra attributi secondari

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

Mostra attributi secondari

dataCapture.status

string

Possible values: ok, pending, error, unknown

dataCapture.stage

string

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

dataCapture.errorMessage

string

dataFetching

object

Mostra attributi secondari

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

Mostra attributi secondari

dataFetching.lastExecution.status

string

dataFetching.lastExecution.startedAt

string

dataFetching.lastExecution.endedAt

string

dataFetching.lastExecution.duration

number

dataFetching.lastExecution.errorMessage

string

engagements

object

Mostra attributi secondari

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

Mostra attributi secondari

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

Mostra attributi secondari

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

Mostra attributi secondari

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

Mostra attributi secondari

dataHubCatalog.catalogs.name

string

dataHubCatalog.catalogs.version

string

dataHubCatalog.catalogs.models

array of string

Esempio di codice

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.

Esempio di codice

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.

Payload della richiesta

service

string

obbligatorio

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

obbligatorio

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.

Mostra parametri secondari

eventFilters.key

string

obbligatorio

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

eventFilters.value

string

obbligatorio

template

string

url

string

obbligatorio

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.

Mostra parametri secondari

oauth2.tokenUrl

string

obbligatorio

The OAuth 2.0 token endpoint where access tokens are requested.

oauth2.clientId

string

obbligatorio

The OAuth 2.0 client identifier.

oauth2.clientSecret

string

obbligatorio

The OAuth 2.0 client secret.

oauth2.scopes

array of string

OAuth 2.0 scopes to request.

Payload della risposta

string

obbligatorio

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

organizationId

string

obbligatorio

workspaceId

string

obbligatorio

service

string

obbligatorio

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

obbligatorio

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

eventFilters

array of object

Mostra attributi secondari

eventFilters.key

string

obbligatorio

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

eventFilters.value

string

obbligatorio

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

obbligatorio

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.

Mostra attributi secondari

oauth2.tokenUrl

string

obbligatorio

The OAuth 2.0 token endpoint where access tokens are requested.

oauth2.clientId

string

obbligatorio

The OAuth 2.0 client identifier.

oauth2.scopes

array of string

OAuth 2.0 scopes to request.

status

string

obbligatorio

Possible values: active, inactive

statusReason

string

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

createdAt

string

updatedAt

string

Esempio di codice

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.

Esempio di codice

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

Esempio di codice

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