--- name: cumulocity-send-and-receive-sms description: "Configure the SMS provider of the tenant, send an SMS through the SMS gateway microservice, and read the messages received for an address. Use when the user wants to send an SMS to a phone or device, read the SMS received for an address, or set up the SMS provider of a tenant." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Send and receive SMS Source: https://cumulocity.com/docs/skills/application-enablement/send-and-receive-sms/ Sector: Skills, Application enablement & solutions Release: Latest Description: Configure the SMS provider of the tenant, send an SMS through the SMS gateway microservice, and read the messages received for an address. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) The SMS gateway microservice `sms-gateway` sends and receives SMS through the SMS provider that is configured for the tenant. The platform also uses this provider for other features, for example for two-factor authentication. You use the REST endpoints of the microservice at `/service/messaging`, see [SMS management endpoints](https://cumulocity.com/docs/microservice-sdk/java/#sms-management-endpoints). Addresses have the form `:`, for example `tel:+491701234567`. The protocol is `tel` for a phone number, or `iccid`, `acr`, or `short`. To send an SMS through the SIM provider of a device instead, see [Manage the SIM card of a device](https://cumulocity.com/docs/skills/device-management/manage-sim-connectivity/#to-send-an-sms-to-the-device). > **Requirements:** > ROLES & PERMISSIONS: > > * To read the provider configuration and received messages: ROLE_SMS_READ > * To configure the provider and send SMS: ROLE_SMS_ADMIN > > Your tenant is subscribed to the SMS gateway microservice `sms-gateway`. If a request returns HTTP 403 with the error "Microservice/Access Denied", your tenant is not subscribed to the microservice. Any other HTTP 403 means that your user lacks the role for the request. ### To check the SMS provider of the tenant {#to-check-the-sms-provider-of-the-tenant} Send the following request to the microservice: ```http GET /service/messaging/providers/configuration ``` The microservice returns HTTP 200 and the configuration. The `provider` property contains the ID of the provider. If the microservice returns HTTP 404 with the message "No provider configuration could be found", no SMS provider is configured. You cannot send or receive SMS until you configure one. ### To configure the SMS provider {#to-configure-the-sms-provider} 1. Send the following request to the microservice to read the properties that each provider needs: ```http GET /service/messaging/providers/definitions ``` The microservice returns HTTP 200 and a JSON array of providers. Each provider has an `id`, a `displayName`, and a `schema`. The `schema` is the JSON schema of the properties that the provider needs, such as URLs and credentials. 2. Send a PUT request. Set `provider` to the `id` of the provider, ``, and add each property that its `schema` requires as `` and ``: ```http PUT /service/messaging/providers/configuration Content-Type: application/json Accept: application/json { "provider": "", "": "" } ``` The microservice deletes the current configuration before it saves the new one. Always send the complete configuration, not only the changed properties. The microservice returns HTTP 200 and the saved configuration. If it returns HTTP 400, the body does not match the schema of the provider. You can also configure the provider in the Administration application, see [SMS provider](https://cumulocity.com/docs/standard-tenant/changing-settings/#sms-provider). > **Caution:** > `DELETE /service/messaging/providers/configuration` removes the provider configuration and disables SMS for the whole tenant. Do not delete a configuration that you did not create. ### To send an SMS {#to-send-an-sms} The example uses `` for the address of the sender and `` for the address of the recipient, both in the form `:`. Send a request to send a message, as described in [SMS management endpoints](https://cumulocity.com/docs/microservice-sdk/java/#sms-management-endpoints), with the sender address in the path: ```http POST /service/messaging/smsmessaging/outbound//requests Content-Type: application/json Accept: application/json { "outboundSMSMessageRequest": { "senderAddress": "", "address": [""], "outboundSMSTextMessage": { "message": "Hello device" } } } ``` The `address` array can contain several recipients. Optional properties of `outboundSMSMessageRequest` are `senderName`, `clientCorrelator`, and `receiptRequest`. The microservice returns HTTP 200 and the `outboundSMSMessageRequest` with the `senderAddress`, the `address`, and the message. If the microservice returns an error, check the status: * **HTTP 409** with the message "Missing provider in tenant option, category: messaging": No SMS provider is configured. See [To configure the SMS provider](https://cumulocity.com/docs/skills/application-enablement/send-and-receive-sms/#to-configure-the-sms-provider). * **HTTP 400**: The provider rejected the request, or an address is not in the form `:`. The error body contains the details. You cannot undo a sent SMS. The REST API does not report the delivery status of a sent SMS. ### To read received messages {#to-read-received-messages} The example uses `` for the address that received the messages, in the form `:`. Not every SMS provider supports receiving messages. Send a request to receive all messages, as described in [SMS management endpoints](https://cumulocity.com/docs/microservice-sdk/java/#sms-management-endpoints): ```http GET /service/messaging/smsmessaging/inbound/registrations//messages ``` The microservice returns HTTP 200 and the received messages in the `inboundSMSMessageList` array. Each `inboundSMSMessage` contains its `messageId`, `message`, `senderAddress`, `destinationAddress`, and `dateTime`. To read one message, add its ID, ``, to the path: ```http GET /service/messaging/smsmessaging/inbound/registrations//messages/ ``` If the microservice returns HTTP 409, no SMS provider is configured. If it returns HTTP 400, the address is not in the form `:`. ## Linked from the documentation - [Microservice SDK for Java > Services platform and SMS API](https://cumulocity.com/docs/microservice-sdk/java/#services-platform-sms-api)