# Send SMS Messages To Devices SMS messages are queued on the ThingSpace Platform and sent as soon as possible, but they may be delayed due to traffic and routing considerations. You can register for the EnhancedConnectivityService callback service to be notified when the messages have actually been sent to the devices, and for the SMSDeliveryConfirmation callback service to verify that the devices receive the messages. The Verizon Wireless network attempts to deliver a message for five days (120 hours) from the date of receipt. Messages not delivered within five days are deleted, and an “expired” notification is sent via the SMSDeliveryConfirmation callback service. ## HTTP Request [POST https://thingspace.verizon.com/api/m2m/v1/sms](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/api-endpoints/sms/send-sms-to-device/send-sms-to-device) ## Header Parameters The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON. | Parameter Name | Data Type | Description | |:-----------------------:|:---------:|:------------------------------------------------------:| | Authorization *(required)* | string | HTTP Authorization bearer token. | | VZ-M2M-Token *(required)* | string | A valid session token returned by `POST /session/login`. | | Content-Type *(required)* | string | Must be `application/json`. | ## Request Body The request body identifies the devices that the message is sent to, and the message itself. | Parameter Name | Data Type | Description | |:-----------------------------------:|:----------------------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | **deviceIds** *optional* | array of device identifiers | The devices that you want to send the message to, specified by device identifier. You only need to provide one identifier per device. Do not use accountName, groupName, or customFields if you use this parameter. | | **kind, id** *required for deviceIds* | strings | The type and value of the device identifier. ESN - decimal, 11 digits ICCID - decimal, up to 20 digits IMEI - decimal, up to 15 digits MDN - decimal, 10 digits MSISDN - decimal, 11 digits | | **accountName** *optional* | string | The name of a billing account. This parameter is always required. An account name is usually numeric, and must include any leading zeros. | | **groupName** *optional* | string | The name of a device group, if you want to send the SMS message to all devices in the device group. | | **servicePlan** *optional* | string | The name of a service plan, if you want to only include devices that have that service plan. You can use GET /plans to get a list of all service plans in the account. | | **customFields** optional* | array | The names and values of custom fields, if you want to only include devices that have matching custom fields. | | **key** *required for customFields* | string | The name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5. | | **value** *required for customFields* | string | The value of the custom field. The value is not case-sensitive, but other than that it must match exactly with the value set for a device. Wildcards and partial matches are not supported. | | **dataEncoding** *optional* | string | The SMS message encoding, which can be: 7-bit (default) 8-bit-ASCII 8-bit-UTF-8 8-bit-DATA Note: All 8-bit SMS messages require the message contents to be base64 encoded. | | **smsMessage** *required* | string | The contents of the SMS message. The SMS message is limited to 160 characters in 7-bit format, or 140 characters in 8-bit format. | | **timeToLive** *(optional)* | string | A period of time the message remains valid or an end date for the message. For more information, please review section 5.2.16 (validity period) and 7.1 (time definitions) in the [SMPP Standards document](https://smpp.org/SMPP_v3_4_Issue1_2.pdf) | * Either specify up to 10,000 individual devices with the devices parameter, or use any combination of `groupName`, `servicePlan`, and `customFields` to run the request on all devices that match all criteria. ## Example Request Body Send an SMS Message to single or multiple Device ID(s): ```json { "accountName": "0000123456-00001", "customFields": [ { "key": "CustomField1", "value": "value of the field" } ], "dataEncoding": "optional 7 or 8-bit encoding", "deviceIds": [ { "id": "20-digit ICCID", "kind": "iccid" } ], "smsMessage": "the body or text of the message itself", "timeToLive": "000000010000000R" } ``` Send an SMS Message to All Devices with a specified service plan or group name: ```json { "accountName": "0000123456-00001", "customFields": [ { "key": "ANR5XG3Ud", "value": "r0QngIFUIQ1BatSsN" } ], "dataEncoding": "optional 7 or 8-bit encoding", "groupName": "the name of the group the device is in", "servicePlan": "the service plan the device is using", "smsMessage": "the body or text of the message itself", "timeToLive": "000000010000000R" } ``` ## Success Responses **Status 200** | Parameter Name | Data Type | Description | |:--------------:|:---------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| | requestId | string | A unique string (UUID) that associates the request with the results that are sent via a callback service. The ThingSpace Platform sends a separate callback message for each device that matched the request criteria, indicating whether the operation succeeded for that device and containing any requested information. All related callback messages have the same `requestId`. | ## Example Success Response ```json { "requestId": "595f5c44-eeee-ffff-gggg-020a1545a84d" } ``` ## Example Callback Response SendSmsMessage Callback Messages: Per-Device Message: ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceIds":[ { "id":"20-digit ICCID", "kind":"iccid" }, { "id":"3035551234", "kind":"mdn" }, { "id":"15-digit IMEI", "kind":"imei" }, { "id":"13035551234", "kind":"msisdn" } ], "comment":"SendSmsMessage,Performed action on device.", "status":"Success", "callbackCount":1, "maxCallbackThreshold":4 } ``` Request Complete Message: ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "comment":"SendSmsMessage,Request Completed Processing." "summary": { "devicesRequested": 2 } } ``` SmsDeliveryConfirmation Callback Messages: Success after device acknowledgement: ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceIds":[ { "id":"3035551234", "kind":"mdn" } ], "deviceResponse":{ "smsDeliveryResponse":{ "confirmation":"Delivered" } } } ``` Undelivered, such as for messages sent to suspended devices: ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceIds":[ { "id":"3035551234", "kind":"mdn" } ], "deviceResponse":{ "smsDeliveryResponse":{ "confirmation":"Undelivered" } } } ``` Expired, when a message could not be delivered within 5 days or exceeded `timeToLive` : ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceIds":[ { "id":"3035551234", "kind":"mdn" } ], "deviceResponse":{ "smsDeliveryResponse":{ "confirmation":"Expired" } } } ``` Rejected, when a device’s message queue is full (the device already has 100 pending messages in queue): ```json { "username":"", "password":"", "requestId":"595f5c44-eeee-ffff-gggg-020a1545a84d", "deviceIds":[ { "id":"3035551234", "kind":"mdn" } ], "deviceResponse":{ "smsDeliveryResponse":{ "confirmation":"Rejected" } } } ``` ## Callback Parameters | Parameter | Data Type | Description | | ---------- | --------- | ------------ | | **username** | string | The user name of the requestor. | | **password** | string | The password of the user making the request. | | **requestId** | string | The UUID of the request. A UUID is a 32 to 36-bit alphanumeric string. | | **deviceIds** | array | An array of device identifier objects, each object containing a `kind` and `id`. | | **id** | string | The value of the `kind` associated with the device. | | **kind** | string | A description of what the parameter is and what valid data for the parameter is. This is usually the <strong> MDN </strong> - Mobile Device Number, which is a 10-digit phone number, but could also be: <br> <strong> IMEI </strong> - International Mobile Equipment Identifier <br> <strong> ICCID </strong> - Integrated Circuit Card Identifier <br> <strong> MSISDN </strong> - Mobile Services International Subscriber Directory Number. In the United States, this is 1+ a 10-digit phone number. | | **deviceResponse** | object | The object containing the response from the device that was sent an SMS. | | **smsDeliveryResponse** | object | The object containing the confirmation message from the device. | | **confirmation** | string | Confirmation of message delivery. This can be one of the following: <br> <strong> DELIVERED: </strong> The message has successfully reached the recipient's device. <br> <strong> EXPIRED: </strong> The message validity period has passed, and the Short Message Service Controller (SMSC) cannot deliver it. <br> <strong> UNDELIVERABLE: </strong> The message could not be delivered for various reasons, such as an invalid number or a temporary mobile network outage. <br> <strong> DELETED: </strong> The message was deleted by the SMSC or the recipient. <br> <strong> REJECTED: </strong> The message was rejected by the SMSC. <br> <strong> UNKNOWN: </strong> The status of the message is unknown. | ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "error code string", "errorMessage": "error message string" } ``` Error response when the message sent is too long: ```json { "errorCode": "EnhancedConnectivityService.INPUT_INVALID.SmsMessage.TooLong", "errorMessage": "An 8-bit SMS message cannot be more than 188 characters long." } ``` Error codes and messages are listed on the [Error Messages](https://thingspace.verizon.com/documentation/api-documentation.html#/http/connectivity-management/guides/error-messages/overview) page, along with explanations and suggestions for corrective actions.