SMS API
Send a Message¶
endpoint v.2: /api/v2/sms
endpoint v.1: /api/messages
Before you send an SMS message using the /api/v2/sms endpoint, make sure you have:
- A Live Link 365 Account
- A cURL installation on your computer
- An app key and a secret associated to your Live Link 365 account
- An OAuth token which will confirm your identity to the Live Link 365 endpoint
Once you have all the prerequisites (especially the OAuth token), follow these steps to send an SMS message using cURL:
- Open a new command prompt (or a terminal if you're using Mac).
-
Write a curl command. Make sure you add the following:
- A POST method
- An Authorization header with your bearer token
- A Content-Type header that specifies the data will be in application/json format
- A JSON body with the following properties (required properties followed by '*' in table):
{ "ackCountryCode": false, "ackDeliveredTime": false, "ackFinalOnly": false, "ackFinalStatus": false, "ackInternalStatus": false, "ackMTReceivedTime": false, "ackOperatorId": false, "ackTimeInGMT": true, "ackTpoa": false, "ackType": "ORDER", "acknowledgement": false, "callback": "https://server.to-receive-acks.com/endpoint-to-receive-them", "clientId": 12345, "contentTextEncoding": "UTF8", "destination": [ "1122334455", "1122334455" ], "message": "Hello World!!", "messageClass": "1", "mobileNotification": "YES", "operatorId": 61, "origin": "12345", "pId": "2A", "randomId": 0, "sessionId": "<facebook>test</facebook>", "subject": "ABC", "validityPeriod": "1w" }
Property Value ackCountryCode Set to true to receive Country Codes in ACKs ackDeliveredTime Set to true to receive ACK delivery times ackFinalOnly Set to true to receive only ACKs that have Final Status. Non-final ACKs will be ignored ackInternalStatus Set to true to receive Internal Status Codes in ACKs ackMTReceivedTime Set to true to receive MailSubmitTime in ACKs ackOperatorId Set to true to receive Operator IDs in ACKs ackTimeInGMT Set to true to receive GMT time in ACKs ackTpoa Set to true to receive TPOA in ACKs ackType Level of notification Live Link 365 will send back. These are the possible values: - NONE - No ACKs will be sent back
- ORDER - You will receive Live Link 365 ACKs
- MESSAGE - You will receive Live Link 365 and SMS-C/Handset ACKs
acknowledgement Set to true if you want to receive ACKs, false otherwise callback Callback URL which will receive ACKs. Please see our Callbacks section for more information clientId Unique identifier for the client sending the request contentTextEncoding Specifies the short message’s text encoding. Possible values are: - UTF8
- UCS2
destination* String array of recipient numbers. A single string can be sent when sending to a single destination number message* The SMS text message's content messageClass Specifies the message class. Message class is an operator dependent feature. Possible values are: - 0: immediate display (flash)
- 1: handset specific (Live Link default)
- 2: SIM specific
- 3: TE specific
mobileNotification Possible values: - YES
- NO
operatorId Used to specify the destination operator for the message origin Number that will be considered the message sender. It can be a short code, a long code, or an alphanumeric code as long as it belongs to your account's registered numbers. This number will be the one to receive MO replies once the message is sent pId Special string code in hexadecimal format that will tell the operator to process this message in a special manner. Not supported by all operators randomId Random integer that serves as an ID sessionId This is needed for session tracking, US campaign tracking, or other purposes. When supported by an operator, you may receive information in the SESSION_ID field of an incoming MO request. Upon receiving such information, you are expected to post it back into the SESSION_ID field of the MT reply subject This field can be useful to set your own unique ID which will be returned in notifications and will ease tracking of messages statuses validityPeriod Tells how long Live Link 365 tries to send the message.The time can be specified in weeks, days, hours or minutes Sending to Multiple Numbers
When you send the same message to multiple destinations at once, the message metadata's log entry will be slightly different. Please see the Getting Started's Analytics and Logs section for more information on logs for messages with multiple recipients
Code Formats
If you will use a long code as the origin, it must be prefixed with its respective country code.
Other code formats, on the other hand, must not be prefixedThe command should look like this:
curl -X POST \ -H "Authorization: Bearer yourToken" \ -H "Content-Type: application/json" \ -d '{"destination": ["YOUR-MOBILE-NUMBER"], "message": "My First Live Link 365 SMS"}' \ https://livelink.sapdigitalinterconnect.com/api/v2/sms
curl -X POST ^ -H "Authorization: Bearer yourToken" ^ -H "Content-Type: application/json" ^ -d "{\"destination\": [\"YOUR-MOBILE-NUMBER\"], \"message\": \"My First Live Link 365 SMS\"}" ^ https://livelink.sapdigitalinterconnect.com/api/v2/sms
Copying the Command
After you copy the command, make sure you replace all placeholders with appropriate values before pasting it into any command-line interface
-
Press Enter. cURL will produce some output and will then display the endpoint's response.
-
You should get a response like the following:
Property Value livelinkOrderIds Array of objects containing the destination and livelinkOrderId properties below destination Number to which the message was sent livelinkOrderId List of unique identifiers for the send-message request. If SMS message splitting occurs (usually when message is longer than 160 characters), there will be one order ID for each part sent The following JSON body shows the hierarchical structure of the payload's properties mentioned above:
{ "livelinkOrderIds": [ { "destination": [ "123...789" ], "livelinkOrderId": [ "123456789", "123456777" ] }, { "destination": [ "456...789" ], "livelinkOrderId": [ "1453217689", "153256777" ] } ] }
More on SMS 2 Endpoints
For more information on the SMS version 2 endpoint, please visit our API Reference section
Retrieve MOs¶
endpoint: /api/v2/sms/mo
You can also pull the MO records from the Live Link 365 platform by sending a GET request to the SMS MO endpoint.
MO Storage Policy
MOs will only be stored by Live Link 365 for 72 hours after they have been sent to your Incoming Reply Callback URL endpoint. After this time is over, MOs will no longer be available for pulling
Before you pull the MO records from the /api/v2/sms/mo endpoint, make sure you have:
- A Live Link 365 account
- An app key and a secret associated to your Live Link 365 account
- An OAuth token which will confirm your identity to the Live Link 365 endpoint
Please refer to this site's Authentication section for more information on getting app keys, secrets, and OAuth tokens
To pull the MO reply history data from the Live Link 365 platform, send a GET request to /api/v2/sms/mo. Make sure you provide the following:
Header | Description |
---|---|
Authorization | OAuth token used to authenticate with Live Link 365 API. Please provide the token like this: Bearer yourToken |
Key | Value |
---|---|
startUTCTime | Only MO data received after this time will be fetched. Provide in this format: yyyyMMddHHmm |
endUTCTime | Only MO data received before this time will be fetched. Provide in this format: yyyyMMddHHmm |
pageIndex | Number between 1 and n where n is the number of pages stored. Each page groups 10 MOs together |
keyword | Word to match in the MO body. Check is not case sensitive. Response will contain all MOs that contain this keyword |
The following cURL command serves as an example of the GET request you must send to retrieve MOs. In this case, the values of the startUTCTime and endUTCTime parameters will tell the endpoint to return MOs between April 1, 2018 and January 8, 2019.
curl 'https://livelink.sapdigitalinterconnect.com/api/v2/sms/mo?startUTCTime=201804011230&endUTCTime=201901080330&pageIndex=1' \
-H 'Authorization: Bearer yourAccessToken'
curl "https://livelink.sapdigitalinterconnect.com/api/v2/sms/mo?startUTCTime=201804011230&endUTCTime=201901080330&pageIndex=1" ^
-H "Authorization: Bearer yourAccessToken"
Live Link 365 will issue an HTTP response with the following body:
{
"pageCount": "2",
"pageIndex": "1",
"sapnotification": [
{
"contextText": "Some Message",
"orderId": "1234567",
"parameters": {
"clientId": "12345",
"keyword": "",
"receivedTime": "2018-08-16T16:15:03.277Z"
},
"recipient": "string",
"sender": "string"
}
]
}
Property | Value |
---|---|
pageCount | Total number of pages available |
pageIndex | The page number of the retrieved page |
sapNotification | Page's contents, i.e., a list of objects containing information on the received MOs. The following properties belong to the objects contained in this array |
contextText | The message that was received |
orderId | Unique identifier for the send-message request |
parameters | Object containing properties from clientId to receivedTime below |
clientId | Unique identifier of the Live Link 365 account that sent the first message |
keyword | Word that was used to find this MO |
receivedTime | Date and time when the message was received in yyyy-mm-ddThh-mm-ss format |
recipient | Phone number to which the MO was sent |
sender | Phone number that sent the MO |
Retrieve ACKs¶
endpoint: /api/v2/sms/status
You can manually pull the ACK records from the Live Link 365 platform by sending a GET request to the SMS ACK endpoint.
ACK Storage Policy
ACKs sent by Live Link 365 will only be stored for 72 hours after they are sent to your Status Callback URL. After that time they will no longer be available for pulling
To be able to request the ACKs from the /api/v2/sms/status endpoint, you must have:
- A Live Link 365 account
- An app key and a secret associated to your Live Link 365 account
- An OAuth token which will confirm your identity to the Live Link 365 endpoint
To pull the ACK delivery status data from Live Link 365, send a GET request to /api/v2/sms/status. Make sure you provide the following:
Header | Description |
---|---|
Authorization | OAuth token used to authenticate with Live Link 365 API. Please provide the token like this: Bearer yourToken |
Key | Value |
---|---|
startUTCTime | Only MO data received after this time will be fetched. Provide in this format: yyyyMMddHHmm |
endUTCTime | Only MO data received before this time will be fetched. Provide in this format: yyyyMMddHHmm |
pageIndex | Number between 1 and n where n is the number of pages stored. Each page groups 10 MOs together |
status | The message's delivery status. It can be one of four possible values: SENT, DELIVERED, RECEIVED, or ALL. ALL is not a delivery status but rather a value that will allow the retrieval of all ACKs, regardless of their status |
The following cURL command serves as an example of the GET request you must send to retrieve ACKs. In this case, the values of the startUTCTime and endUTCTime parameters will tell the endpoint to return ACKs between April 1, 2018 and January 8, 2019.
curl 'https://livelink.sapdigitalinterconnect.com/api/v2/sms/status?startUTCTime=201804011230&endUTCTime=201901080300&pageIndex=1' \
-H 'Authorization: Bearer yourAccessToken'
curl "https://livelink.sapdigitalinterconnect.com/api/v2/sms/status?startUTCTime=201804011230&endUTCTime=201901080300&pageIndex=1" ^
-H "Authorization: Bearer yourAccessToken"
Live Link 365 will issue an HTTP response with the following body:
{
"clientId": "string",
"pageCount": "integer",
"pageIndex": "integer",
"sapnotification": [
{
"finalStatusIndicator": "string",
"internalStatusId": "string",
"messageBody": "string",
"operatorId": "integer",
"orderId": "string",
"recipient": "string",
"status": "string",
"timestamp": "2018-08-16T21:15:02.015Z"
}
]
}
Property | Value |
---|---|
clientId | The client account's ID |
pageCount | The total number of ACK pages stored |
pageIndex | The retrieved page's number |
sapnotification | List of objects containing data on ACKs. The properties below belong to these objects |
finalStatusIndicator | The final status of the message |
internalStatusId | Unique identifier for the internal status |
messageBody | Contents of the sent message |
operatorId | Unique identifier for the operator that processed the message |
orderId | Unique identifier for the send-message request |
recipient | Phone number that received the message |
status | The delivery status that triggered this callback |
timestamp | Time when the status was reached. In yyyy-mm-ddThh-mm-ss format |