POST /smsSends SMS messages to one or more devices on your ThingSpace-enabled account.
See also:
Retrieve SMS Messages Sent by Devices
Start SMS Callback
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.
POST https://thingspace.verizon.com/api/m2m/v1/sms
None.
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. |
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.
|
| accountName required |
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 of customField objects | 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:
|
| 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. |
* You can either specify up to 10,000 individual devices with the devices parameter, or you can use any combination of groupName, servicePlan, and customFields to run the request on all devices that match all criteria.
Send an SMS Message to Single Device
{
"deviceIds": [
{
"id": "89148000000800139708",
"kind": "iccid"
}
],
"smsMessage": "Can you hear me now?"
}
Send an SMS Message to All Devices with a Specified Service Plan
{
"servicePlan": "T Plan 2",
"smsMessage": "The rain in Spain stays mainly in the plain."
}
Status 200
| Parameter Name | Data Type | Description |
|---|---|---|
| requestId | string | A unique string 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 of the callback messages have the same requestId. |
{
"requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}
Per-Device Message
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"deviceIds":[
{
"id":"89148000001134816189",
"kind":"Iccid"
},
{
"id":"5096307971",
"kind":"Mdn"
},
{
"id":"990000475989473",
"kind":"Imei"
},
{
"id":"15096307971",
"kind":"Msisdn"
}
],
"comment":"SendSmsMessage,Performed action on device.",
"status":"Success",
"callbackCount":1,
"maxCallbackThreshold":4
}
Request Complete Message
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"comment":"SendSmsMessage,Request Completed Processing."
"summary": {
"devicesRequested": 2
}
}
Success after device acknowledgement
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"deviceIds":[
{
"id":"5096307971",
"kind":"Mdn"
}
],
"deviceResponse":{
"smsDeliveryResponse":{
"confirmation":"Delivered"
}
}
}
Undelivered, such as for messages sent to suspended devices
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"deviceIds":[
{
"id":"5096307971",
"kind":"Mdn"
}
],
"deviceResponse":{
"smsDeliveryResponse":{
"confirmation":"Undelivered"
}
}
}
Expired, when a message could not be delivered within 5 days
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"deviceIds":[
{
"id":"5096307971",
"kind":"Mdn"
}
],
"deviceResponse":{
"smsDeliveryResponse":{
"confirmation":"Expired"
}
}
}
Rejected, when a device’s message queue is full (the device already has 100 pending messages in queue)
{
"username":"",
"password":"",
"requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
"deviceIds":[
{
"id":"5096307971",
"kind":"Mdn"
}
],
"deviceResponse":{
"smsDeliveryResponse":{
"confirmation":"Rejected"
}
}
}
Status 400
All error messages are returned in this format:
{
"errorCode": "error code string",
"errorMessage": "error message string"
}
Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.