Skip to content

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:

  1. A Live Link 365 Account
  2. A cURL installation on your computer
  3. An app key and a secret associated to your Live Link 365 account
  4. 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:

  1. Open a new command prompt (or a terminal if you're using Mac).
  2. 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 prefixed

    The 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

  3. Press Enter. cURL will produce some output and will then display the endpoint's response.

  4. 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:

  1. A Live Link 365 account
  2. An app key and a secret associated to your Live Link 365 account
  3. 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:

  1. A Live Link 365 account
  2. An app key and a secret associated to your Live Link 365 account
  3. 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