# Installing a Voice channel It is possible to install a Voice channel via the [connectors API](https://docs.bird.com/api/channels-api/api-reference/channel-connectors). 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](https://docs.bird.com/api/api-access/api-authorization) ## POST /workspaces/{workspaceId}/connectors > Create a new connector from a template. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateConnectorReq":{"type":"object","title":"A request to instantiate a new connector from a template","additionalProperties":false,"properties":{"name":{"type":"string","title":"connector name"},"connectorTemplateRef":{"type":"string","title":"template to base this connector on by ref"},"arguments":{"title":"arguments to provide to each action invocation on this connector","$ref":"#/components/schemas/ConnectorArguments"},"securityArguments":{"$ref":"#/components/schemas/SecurityArgumentsMap"},"channelConversationalStatusEnabled":{"title":"Controls the default value for channel's conversational flag.","type":"boolean","nullable":true},"invitationToken":{"title":"Invitation token to allow installation of connectors that are not GA.","type":"string","nullable":true}},"required":["name"]},"ConnectorArguments":{"type":"object","title":"ConnectorArguments","description":"For SMS connectors (sms-messagebird:1), channelMessageType is required and must be one of promotional, transactional, conversational, emergency, 2fa.","additionalProperties":true,"nullable":true},"SecurityArgumentsMap":{"type":"object","title":"SecurityArgumentsMap","description":"Provide the arguments required by the security scheme(s) on the connector template.","additionalProperties":{"type":"object","title":"SecurityArguments","additionalProperties":{"type":"string"}},"nullable":true},"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors":{"post":{"operationId":"createConnector","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectorReq"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"workspace not found"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector already exists"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"invalid data provided"}},"summary":"Create a new connector from a template.","tags":["Connectors"]}}}} ``` **Example** {% tabs %} {% tab title="Request" %} ```json curl --location 'https://api.bird.com/workspaces//connectors' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data '{ "connectorTemplateRef": "voice-messagebird:1", "name": "My Voice Channel", "arguments": { "phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29" } }' ``` {% endtab %} {% tab title="Parameters Description" %}
PropertyTypeDescription
connectorTemplateRefstringSet as voice-messagebird:1
namestringThe name of your connector e.g. My Voice channel
arguments.phoneNumberIdstringThe ID of endpoint that will be installed
{% endtab %} {% endtabs %} ## 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. ```json {"openapi":"3.0.3","info":{"title":"Connectors","version":"v1"},"tags":[{"description":"Manage connectors, invoke connector actions.","name":"Connectors"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"Connector":{"type":"object","title":"Connector","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The ID of this connector."},"workspaceId":{"type":"string","format":"uuid","description":"The ID of the workspace this connector belongs to."},"routingKey":{"type":"string","nullable":true},"name":{"type":"string","description":"The Name of this connector."},"region":{"type":"string","description":"The Region in which this connector was installed in."},"description":{"type":"string","description":"The Description of this connector."},"arguments":{"type":"object","additionalProperties":true,"description":"Pre-configured arguments for this connector.","nullable":true},"channel":{"nullable":true,"$ref":"#/components/schemas/ChannelConfig"},"number":{"nullable":true,"$ref":"#/components/schemas/NumberConfig"},"connectorTemplateSlug":{"type":"string","description":"The slug for the template this connector is based on."},"connectorTemplateRef":{"type":"string","description":"The ref for the template this connector is based on."},"dataFetching":{"$ref":"#/components/schemas/SyncConfig"},"dataCapture":{"type":"object","nullable":true,"properties":{"captureEndpoint":{"type":"string"}}},"createdAt":{"type":"string","format":"date-time","description":"When the connector was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the connector was last updated."}},"required":["id","name","createdAt"]},"ChannelConfig":{"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"NumberConfig":{"type":"object","additionalProperties":false,"nullable":true,"required":["numberId","profileId"],"properties":{"profileId":{"type":"string","format":"uuid"},"numberId":{"type":"string","format":"uuid"},"phoneNumber":{"type":"string"},"variables":{"type":"object"},"capabilities":{"type":"string","description":"Capabilities of a number. That would be represented with joined string of capabilities with comma."},"numberType":{"type":"string","description":"Type of the number; could be mobile, tollfree, local, etc."},"endpointType":{"type":"string","description":"Type of the endpoint; could be long-code-number, short-code-number, alpha-number, etc."},"country":{"type":"string","description":"Country code of the number."},"profileAttachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"capability":{"type":"string"},"profileId":{"type":"string"},"variables":{"type":"object","properties":{"connectorId":{"type":"string"}}}}}}}},"SyncConfig":{"type":"object","title":"The connector's data fetching synchronisation configuration and state.","additionalProperties":false,"properties":{"schedule":{"type":"string"},"streams":{"type":"array","nullable":true,"title":"streams that whould be fetched (names and incremental fetch config for each)","items":{"$ref":"#/components/schemas/StreamSyncConfig"}}}},"StreamSyncConfig":{"type":"object","title":"fetching configuration for a particular stream","additionalProperties":false,"properties":{"eventName":{"type":"string","title":"name of the event to push when records are fetched from that stream"},"streamName":{"type":"string","title":"name of the stream, as it appears in the catalog (see WorkflowStateForSync)"},"eventStreamName":{"type":"string","nullable":true,"title":"event that the stream will be mapped to"},"filter":{"type":"string","nullable":true,"title":"filter to apply to the records stream, record is included if the filter evaluates to true"},"initialState":{"type":"string","nullable":true,"title":"initial state to apply to the records stream"},"endCondition":{"type":"string","nullable":true,"title":"end condition to apply to the records stream, stops fetching when the condition evaluates to true"},"incremental":{"type":"boolean","title":"whether to fetch the contents of this stream incrementally"},"duplicatesFilterCapacity":{"type":"number","title":"size of the filter used to de-duplicate records"},"cursorField":{"type":"string","nullable":true,"title":"when fetching incrementally, and the source doesn't specify the cursor field, (JSON-)path of the field to use as a cursor field"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}":{"get":{"operationId":"getConnector","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"connector not found"}},"summary":"Show the details of a specific connector.","tags":["Connectors"]}}}} ``` {% tabs %} {% tab title="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 {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//connectors/' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' ``` {% endcode %} {% endtab %} {% endtabs %}