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

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

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

The requested resource was not found.

application/json

409

The request conflicts with the current state of the resource.

application/json

422

The request contains invalid parameters or body fields.

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-08-11T03:08:20.644Z",
  "updatedAt": "2026-08-11T03:08:20.644Z"
}

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

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

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

connectorIdstring · uuidRequired

Responses

200

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

The requested resource was 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-08-11T03:08:20.644Z",
  "updatedAt": "2026-08-11T03:08:20.644Z"
}

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