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

Create a new connector from a template.

POST/workspaces/{workspaceId}/connectors

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

Body

application/json

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

201404409422

OK

Body

application/json

id*string (uuid)

The ID of this connector.

routingKeynullable string

name*string

The Name of this connector.

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.

createdAt*string (date-time)

When the connector was created.

updatedAtstring (date-time)

When the connector was last updated.

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/connectors', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text"
    }),
});
const data = await response.json();

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "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",
    "capabilities": "mms-inbound,mms-outbound,sms-inbound,sms-outbound",
    "numberType": "mobile",
    "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",
        "incremental": false,
        "duplicatesFilterCapacity": 0,
        "cursorField": [
          "text"
        ]
      }
    ]
  },
  "createdAt": "2024-04-29T12:09:16.665Z",
  "updatedAt": "2024-04-29T12:09:16.665Z"
}

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
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"
    },
    "channelConversationalStatusEnabled": true
}

Second Tab

List connectors

Get list of available connectors for this workspace.

GET/workspaces/{workspaceId}/connectors

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

Query parameters

Response

200404

OK

Body

application/json

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

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/connectors', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "routingKey": "text",
      "name": "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",
        "capabilities": "mms-inbound,mms-outbound,sms-inbound,sms-outbound",
        "numberType": "mobile",
        "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",
            "incremental": false,
            "duplicatesFilterCapacity": 0,
            "cursorField": [
              "text"
            ]
          }
        ]
      },
      "createdAt": "2024-04-29T12:09:16.665Z",
      "updatedAt": "2024-04-29T12:09:16.665Z"
    }
  ],
  "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 status of a specific connector.

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

Authorization

useraccessKey

Path parameters

workspaceId*string (uuid)

connectorId*string (uuid)

Response

200404

OK

Body

application/json

checksConnectorStatusConfigCheck (object)

channelnullable object

dataCapturenullable object

dataFetchingnullable object

engagementsnullable object

numbernullable object

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/connectors/{connectorId}/status', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

{
  "checks": {
    "runAt": "2024-04-29T12:09:16.665Z",
    "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": false,
    "disabledAt": "text",
    "errorMessage": "text",
    "lastExecution": {
      "status": "text",
      "startedAt": "2024-04-29T12:09:16.665Z",
      "endedAt": "2024-04-29T12:09:16.665Z",
      "duration": 0,
      "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"
  }
}

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

useraccessKey

Path parameters

workspaceId*string (uuid)

connectorId*string (uuid)

Response

204422

OK

Request

JavaScriptCurl

const response = await fetch('/workspaces/{workspaceId}/connectors/{connectorId}', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();