DocumentationEngagement Platform API
Sign inGet started
Guides
API

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
POST
/workspaces/{workspaceId}/connectors
Create a new connector from a template.
Corps de la requête
name
string
obligatoire
connectorTemplateRef
string
arguments
object
For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.
securityArguments
object
Provide the arguments required by the security scheme(s) on the connector template.
channelConversationalStatusEnabled
boolean
invitationToken
string
Corps de la réponse
id
string
obligatoire
The ID of this connector.
workspaceId
string
The ID of the workspace this connector belongs to.
routingKey
string
name
string
obligatoire
The Name of this connector.
region
string
The Region in which this connector was installed in.
description
string
The Description of this connector.
arguments
object
Pre-configured arguments for this connector.
channel
object
Afficher les attributs enfants
channel.channelId
string
obligatoire
channel.platform
string
obligatoire
number
object
Afficher les attributs enfants
number.profileId
string
obligatoire
number.numberId
string
obligatoire
number.phoneNumber
string
number.variables
object
number.capabilities
string
Capabilities of a number. That would be represented with joined string of capabilities with comma.
number.numberType
string
Type of the number; could be mobile, tollfree, local, etc.
number.endpointType
string
Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc.
number.country
string
Country code of the number.
number.profileAttachments
array of object
Afficher les attributs enfants
number.profileAttachments.capability
string
number.profileAttachments.profileId
string
number.profileAttachments.variables
object
Afficher les attributs enfants
number.profileAttachments.variables.connectorId
string
connectorTemplateSlug
string
The slug for the template this connector is based on.
connectorTemplateRef
string
The ref for the template this connector is based on.
dataFetching
object
Afficher les attributs enfants
dataFetching.schedule
string
dataFetching.streams
array of object
Afficher les attributs enfants
dataFetching.streams.eventName
string
dataFetching.streams.streamName
string
dataFetching.streams.eventStreamName
string
dataFetching.streams.filter
string
dataFetching.streams.initialState
string
dataFetching.streams.endCondition
string
dataFetching.streams.incremental
boolean
dataFetching.streams.duplicatesFilterCapacity
number
dataFetching.streams.cursorField
string
dataCapture
object
Afficher les attributs enfants
dataCapture.captureEndpoint
string
createdAt
string
obligatoire
When the connector was created.
updatedAt
string
When the connector was last updated.
Exemple de code
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/connectors' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
Example
Exemple de code

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:
GET
/workspaces/{workspaceId}/connectors/{connectorId}
Show the details of a specific connector.
Corps de la réponse
id
string
obligatoire
The ID of this connector.
workspaceId
string
The ID of the workspace this connector belongs to.
routingKey
string
name
string
obligatoire
The Name of this connector.
region
string
The Region in which this connector was installed in.
description
string
The Description of this connector.
arguments
object
Pre-configured arguments for this connector.
channel
object
Afficher les attributs enfants
channel.channelId
string
obligatoire
channel.platform
string
obligatoire
number
object
Afficher les attributs enfants
number.profileId
string
obligatoire
number.numberId
string
obligatoire
number.phoneNumber
string
number.variables
object
number.capabilities
string
Capabilities of a number. That would be represented with joined string of capabilities with comma.
number.numberType
string
Type of the number; could be mobile, tollfree, local, etc.
number.endpointType
string
Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc.
number.country
string
Country code of the number.
number.profileAttachments
array of object
Afficher les attributs enfants
number.profileAttachments.capability
string
number.profileAttachments.profileId
string
number.profileAttachments.variables
object
Afficher les attributs enfants
number.profileAttachments.variables.connectorId
string
connectorTemplateSlug
string
The slug for the template this connector is based on.
connectorTemplateRef
string
The ref for the template this connector is based on.
dataFetching
object
Afficher les attributs enfants
dataFetching.schedule
string
dataFetching.streams
array of object
Afficher les attributs enfants
dataFetching.streams.eventName
string
dataFetching.streams.streamName
string
dataFetching.streams.eventStreamName
string
dataFetching.streams.filter
string
dataFetching.streams.initialState
string
dataFetching.streams.endCondition
string
dataFetching.streams.incremental
boolean
dataFetching.streams.duplicatesFilterCapacity
number
dataFetching.streams.cursorField
string
dataCapture
object
Afficher les attributs enfants
dataCapture.captureEndpoint
string
createdAt
string
obligatoire
When the connector was created.
updatedAt
string
When the connector was last updated.
Exemple de code
curl -X GET 'https://api.bird.com/workspaces/{workspaceId}/connectors/{connectorId}' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
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
Exemple de code
curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors/<your-connector-id>' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'