Installing a Voice channel

It is possible to install a Voice channel via 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.

Installing a Voice connector

In order to create a Voice connector, you must have a valid phoneNumberId and perform a HTTP request to the following endpoint with a valid access key

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

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",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "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",
    "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": false,
        "duplicatesFilterCapacity": 0,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2025-01-21T01:37:18.811Z",
  "updatedAt": "2025-01-21T01:37:18.811Z"
}

Example



curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>' \
--data '{
    "connectorTemplateRef": "voice-messagebird:1",
    "name": "My Voice Channel",
    "arguments": {
        "phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29"
    }
}'

Property

Type

Description

connectorTemplateRef

string

Set as voice-messagebird:1

name

string

The name of your connector e.g. My Voice channel

arguments.phoneNumberId

string

The ID of endpoint that will be installed

Get your channel id

Once you have created your Voice connector, this will create a Voice channel each Voice channel have a unique channel ID that you need to use when calling Voice Calls API to use this specific channel. You can then get your channel ID as follows:

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

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

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
  "routingKey": "text",
  "name": "text",
  "region": "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",
    "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": false,
        "duplicatesFilterCapacity": 0,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2025-01-21T01:37:18.811Z",
  "updatedAt": "2025-01-21T01:37:18.811Z"
}

The following example will get the connector you have created in the previous step. Parse the channel.channelId to get the id of your new Voice channel

curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors/<your-connector-id>' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'

Last updated 3 months ago

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();

{ "id": "123e4567-e89b-12d3-a456-426614174000", "workspaceId": "123e4567-e89b-12d3-a456-426614174000", "routingKey": "text", "name": "text", "region": "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", "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": false, "duplicatesFilterCapacity": 0, "cursorField": "text" } ] }, "dataCapture": { "captureEndpoint": "text" }, "createdAt": "2025-01-21T01:37:18.811Z", "updatedAt": "2025-01-21T01:37:18.811Z" }

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