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

Authorizations
Path parameters
workspaceIdstring uuidrequired
Body
nameconnector namerequired
connectorTemplateReftemplate to base this connector on by ref
argumentsarguments to provide to each action invocation on this connector
Example: {"someArgument":"someValue"}
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.
Responses
curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/connectors' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"name":"text","arguments":{"someArgument":"someValue"},"securityArguments":{"ANY_ADDITIONAL_PROPERTY":{}}}'
{
  "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",
    "variables": {},
    "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": true,
        "duplicatesFilterCapacity": 1,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2025-02-07T16:48:03.963Z",
  "updatedAt": "2025-02-07T16:48:03.963Z"
}

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"
    }
}'

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}

Authorizations
Path parameters
workspaceIdstring uuidrequired
connectorIdstring uuidrequired
Responses
curl -L \
  --url '/workspaces/{workspaceId}/connectors/{connectorId}' \
  --header 'Authorization: Bearer jwt'
{
  "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",
    "variables": {},
    "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": true,
        "duplicatesFilterCapacity": 1,
        "cursorField": "text"
      }
    ]
  },
  "dataCapture": {
    "captureEndpoint": "text"
  },
  "createdAt": "2025-02-07T16:48:03.963Z",
  "updatedAt": "2025-02-07T16:48:03.963Z"
}

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

Was this helpful?