# Installing an SMS channel

It is possible to install an SMS channel via the [connectors API](../../api-reference/channel-connectors).&#x20;

Channels are created by first installing a new connector. Connectors are responsible for linking the MessageBird Engagements platform to third-party platforms.&#x20;

## Installing an SMS connector

In order to create an SMS connector, you must have a valid phoneNumberId and perform an HTTP request to the following endpoint with a [valid access key](../../../api-access/api-authorization).

## POST /workspaces/{workspaceId}/connectors

> Create a new connector from a template.

OpenAPI:

```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"}}},"paths":{"/workspaces/{workspaceId}/connectors":{"post":{"operationId":"createConnector","requestBody":{"content":{"application/json":{"schema":{"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","type":"object","additionalProperties":true,"nullable":true},"securityArguments":{"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},"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"]}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"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,"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"number":{"nullable":true,"type":"object","additionalProperties":false,"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"}}}}}}}},"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":{"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":{"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"}}}}}},"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"]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"description":"workspace not found"},"409":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"$ref":"#/paths/~1workspaces~1{workspaceId}~1connectors/post/responses/404/content/application~1json/schema/properties"}}}},"description":"connector already exists"},"422":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"$ref":"#/paths/~1workspaces~1{workspaceId}~1connectors/post/responses/404/content/application~1json/schema/properties"}}}},"description":"invalid data provided"}},"summary":"Create a new connector from a template.","tags":["Connectors"]}}}}
```

#### Example request

{% hint style="info" %}
To create an SMS channel, be aware that **`phoneNumberId`** and **`channelMessageType`** are required `arguments`.
{% endhint %}

{% tabs fullWidth="true" %}
{% tab title="Request" %}
{% code overflow="wrap" fullWidth="true" %}
```bash
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": "sms-messagebird:1",
    "name": "My SMS channel",
    "arguments": {
        "phoneNumberId": "2cffb55c-120e-91a8-8f10-ed9d1b412d29",
        "useCaseId": "be123b02-dacf-31f9-b3e5-50b18260bc23",
        "channelMessageType": "transactional"
    },
    "channelConversationalStatusEnabled": true
}'
```
{% endcode %}
{% endtab %}

{% tab title="Parameter description" %}
<table data-full-width="true"><thead><tr><th width="316.39322916666663">Property</th><th width="96.203125">Type</th><th width="128.4453125">Required</th><th>Description</th></tr></thead><tbody><tr><td>connectorTemplateRef</td><td>string</td><td>Yes</td><td>Set as <strong>sms-messagebird:1</strong></td></tr><tr><td>name</td><td>string</td><td>Yes</td><td>The name of your connector e.g. My SMS channel.</td></tr><tr><td>arguments.phoneNumberId</td><td>string</td><td>Yes</td><td>The ID of the endpoint that will be installed.</td></tr><tr><td>arguments.useCaseId</td><td>string</td><td>Conditional</td><td>The ID of the use case.<br><br><strong>Required</strong> for endpoint type longcode + local + US.</td></tr><tr><td>arguments.channelMessageType</td><td>string</td><td>Yes</td><td>The message type for the channel to be created. Possible values: promotional, 2fa, conversational, transactional, emergency.<br><br><strong>Required</strong> for <strong>all</strong> SMS channels.</td></tr><tr><td>channelConversationalStatusEnabled</td><td>boolean</td><td>No</td><td>If true, incoming messages will create new conversations in Inbox.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Get your channel ID

Once you have created your SMS connector, this will create an SMS channel. You can then get your channel ID as follows

## GET /workspaces/{workspaceId}/connectors/{connectorId}

> Show the details of a specific connector.

OpenAPI:

```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"}}},"paths":{"/workspaces/{workspaceId}/connectors/{connectorId}":{"get":{"operationId":"getConnector","responses":{"200":{"content":{"application/json":{"schema":{"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,"type":"object","additionalProperties":false,"required":["channelId","platform"],"properties":{"channelId":{"type":"string","format":"uuid"},"platform":{"type":"string"}}},"number":{"nullable":true,"type":"object","additionalProperties":false,"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"}}}}}}}},"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":{"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":{"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"}}}}}},"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"]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":5},"message":{"type":"string","minLength":5},"details":{"type":"object","additionalProperties":true}}}}},"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 SMS channel

{% code overflow="wrap" %}
```bash
curl --location 'https://api.bird.com/workspaces/<your-workspace-id>/connectors/<your-connector-id>' \
--header 'Accept: application/json' \
--header 'Authorization: AccessKey <your-access-key>'
```
{% endcode %}
{% endtab %}
{% endtabs %}

## Installation scenarios

Getting a valid phoneNumberId or useCaseId can have different pre-requisites depending on the Endpoint type. See the quick starts for some common scenarios:

<table><thead><tr><th width="199">Country</th><th width="145.66015625">Endpoint Type</th><th width="144.32421875">Number type</th><th>Guide</th></tr></thead><tbody><tr><td>🇺🇸 United States </td><td>Long code</td><td>Local</td><td><a data-mention href="installing-an-sms-channel/us-10dlc-api-installation">us-10dlc-api-installation</a></td></tr><tr><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td></td><td></td></tr></tbody></table>
