# Installing an SMS channel It is possible to install an SMS 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 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](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 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//connectors' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --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" %}
PropertyTypeRequiredDescription
connectorTemplateRefstringYesSet as sms-messagebird:1
namestringYesThe name of your connector e.g. My SMS channel.
arguments.phoneNumberIdstringYesThe ID of the endpoint that will be installed.
arguments.useCaseIdstringConditionalThe ID of the use case.

Required for endpoint type longcode + local + US.
arguments.channelMessageTypestringYesThe message type for the channel to be created. Possible values: promotional, 2fa, conversational, transactional, emergency.

Required for all SMS channels.
channelConversationalStatusEnabledbooleanNoIf true, incoming messages will create new conversations in Inbox.
{% 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. ```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 SMS channel {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//connectors/' \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' ``` {% endcode %} {% endtab %} {% endtabs %} ## Installation scenarios Getting a valid phoneNumberId or useCaseId can have different prerequisites depending on the Endpoint type. See the quick starts for some common scenarios:
CountryEndpoint TypeNumber typeGuide
πŸ‡ΊπŸ‡Έ United States Long codeLocalus-10dlc-api-installation
🌐 GlobalLong code, Alphanumeric & Short code-See below
### Global installation scenario The generic method for installing an SMS is described below. More specific scenarios are listed in the table above. In principle, the following steps need to be followed to set up a channel programmatically: 1. Buy or request a **sender**: a phone number, alphanumeric sender, or short code (including the relevant KYC process, depending on the type of sender and country). 2. Set up a **use case**. 3. **Link the use case** to a sender. 4. **Install** the SMS channel. #### 1. Buy or Request a sender For more in-depth information about this step, see the[ Numbers API Specifications](https://docs.bird.com/api/numbers-api/api-reference). #### 2. Set up a use case This step is documented at the [SMS Use Cases documentation page](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/sms-use-cases#create-a-use-case). #### 3. Link the use case to a sender {% tabs %} {% tab title="Request" %} The following example will link the created use case to a sender. {% code overflow="wrap" %} ```bash curl --location 'https://api.bird.com/workspaces//endpoints//compliance-requirements/use-case-sms' \ -X PUT \ --header 'Accept: application/json' \ --header 'Authorization: AccessKey ' \ --data-raw '{ "type": "use-case", "useCaseId": "" }' ``` {% endcode %} {% endtab %} {% endtabs %} More information about this can be found in the [Update Workspace Compliance Requirements](https://docs.bird.com/api/numbers-api/api-reference/manage-endpoint-compliance-requirements/update-workspace-compliance-requirements) section. #### 4. Install the SMS channel This final step is explained in more detail [at the top of this page](#installing-an-sms-connector). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/installing-an-sms-channel.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.