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

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

Body

application/json

namestringRequired

connectorTemplateRefstringOptional

channelConversationalStatusEnabledboolean · nullableOptional

invitationTokenstring · nullableOptional

Responses

201

OK

application/json

idstring · uuidRequired

The ID of this connector.

workspaceIdstring · uuidOptional

The ID of the workspace this connector belongs to.

routingKeystring · nullableOptional

namestringRequired

The Name of this connector.

regionstringOptional

The Region in which this connector was installed in.

descriptionstringOptional

The Description of this connector.

connectorTemplateSlugstringOptional

The slug for the template this connector is based on.

connectorTemplateRefstringOptional

The ref for the template this connector is based on.

createdAtstring · date-timeRequired

When the connector was created.

updatedAtstring · date-timeOptional

When the connector was last updated.

404

workspace not found

application/json

409

connector already exists

application/json

422

invalid data provided

application/json

post

/workspaces/{workspaceId}/connectors

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/connectors HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "name": "text",
  "connectorTemplateRef": "text",
  "arguments": {
    "someArgument": "someValue"
  },
  "securityArguments": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "channelConversationalStatusEnabled": true,
  "invitationToken": "text"
}

{
  "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": "2026-02-24T19:35:23.187Z",
  "updatedAt": "2026-02-24T19:35:23.187Z"
}

Example

Request

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

Parameters Description

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

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

connectorIdstring · uuidRequired

Responses

200

OK

application/json

404

connector not found

application/json

get

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

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/connectors/{connectorId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "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": "2026-02-24T19:35:23.187Z",
  "updatedAt": "2026-02-24T19:35:23.187Z"
}

Request

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