Send SMS Messages To Devices:

POST /sms

Sends SMS messages to one or more devices on your ThingSpace-enabled account.

Contents

See also:
Retrieve SMS Messages Sent by Devices
Start SMS Callback

Uses and Requirements

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.

Request

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/sms

Resource Path and Query Parameters

None.

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
Parameter NameAuthorization
required		 Data Typestring DescriptionHTTP Authorization bearer token.
Parameter NameVZ-M2M-Token
required		 Data Typestring DescriptionA valid session token returned by POST /session/login.
Parameter NameContent-Type
required		 Data Typestring DescriptionMust 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
Parameter NamedeviceIds
optional*		 Data Typearray of device identifiers DescriptionThe 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.
Parameter Name
kind,
id
required for deviceIds
 Data Typestrings DescriptionThe 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
  • MEID - hexadecimal, 14 characters
  • MSISDN - decimal, 11 digits
Parameter NameaccountName
required
 Data Typestring DescriptionThe name of a billing account. This parameter is always required.
An account name is usually numeric, and must include any leading zeros.
Parameter NamegroupName
optional*		 Data Typestring DescriptionThe name of a device group, if you want to send the SMS message to all devices in the device group.
Parameter NameservicePlan
optional*		 Data Typestring DescriptionThe 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.
Parameter NamecustomFields
optional*		 Data Typearray of customField objects DescriptionThe names and values of custom fields, if you want to only include devices that have matching custom fields.
Parameter Name
key
required for customFields
 Data Typestring DescriptionThe name of the custom field. Valid names are CustomField1, CustomField2, CustomField3, CustomField4, and CustomField5.
Parameter Name
value
required for customFields
 Data Typestring DescriptionThe 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.
Parameter NamedataEncoding
optional		 Data Typestring DescriptionThe 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.
Parameter NamesmsMessage
required		 Data Typestring DescriptionThe 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.

Example Request Body

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."
}

Success Responses

Status 200

Parameter Name Data Type Description
Parameter NamerequestId Data Typestring DescriptionA 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.

Example Success Response

{
  "requestId": "595f5c44-c31c-4552-8670-020a1545a84d"
}

Example Success Callback Response

SendSmsMessage Callback Messages

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
  }
}

SmsDeliveryConfirmation Callback Messages

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"
    }
  }
}

Failure Responses

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.

Try It Out!