Callbacks

About Callbacks¶

Callbacks or webhooks are HTTP POST requests that a system sends when a specific event changes its state. Live Link 365 uses callbacks to notify web clients of two types of events, that is, whenever Live Link 365:

Receives replies to messages it previously sent
Detects a state change that is part of the regular SMS sending process

In event-notification systems, there are two roles that the interacting entities play:

Observers
Subjects or Observables

Observers¶

Observers are those who are interested in some event happening within a system that usually changes the system's state. They are constantly listening for callbacks that will notify them of a change of state they are interested in.

On Receiving Notifications

In order to receive notifications, observes must register with the subjects they wish to follow. In the case of callback event-notification systems, observers must provide subjects the URLs where they wish to receive POST requests

Subjects/Observables¶

Subjects, on the other hand, manage their own state. Whenever their state changes, subjects notify observers of these changes by sending them callback POST requests to the URLs they provided.

On Sending Notifications

Subjects will only send callbacks (POST requests) to their registered observers

Live Link 365 Callbacks¶

Live Link 365 features a callback system that notifies clients of:

Changes in the SMS message's status when it is sent from Live Link 365 to the operator and from the operator to the final handset
Changes in the form of replies from a mobile phone to a message sent by Live Link 365

In this event-notification system, Live Link 365 is the subject and any client app or service who has registered with it by providing callback URLs is an observer.

MO and ACK Callbacks

Please visit the Receiving MOs and the Receiving ACKs sections to learn more about Live Link 365's SMS callbacks

Within the Live Link 365 system, callbacks are implemented as HTTP POST requests that are sent in response to specific events happening within the system. It is used as a simple event-notification mechanism. Live Link 365 uses callbacks to notify web clients of two types of events, that is, whenever Live Link 365:

Receives replies to messages it previously sent (MOs)
Receives message delivery status reports (ACKs)

Configuring Callback Settings¶

To let Live Link 365 know where to send these callbacks and what authentication mechanisms to use, please visit your Live Link 365 account's Callback Configuration section:

Log in to the Live Link 365 Main Portal with your credentials.
Click on "Account" near the left side of the browser window. The following screen will appear:
Scroll all the way down until you see a section named "Callback Configuration".

Now that you have reached the Callback Configuration Section, follow the next two sections' steps to configure callback URLs and authentication mechanisms for your Live Link 365 account.

Callback URLs¶

You can set two URLs for receiving callbacks, one for each type of callback event. Follow these steps to set up the callback URLs from your Live Link 365 account's "Callback Configuration" settings:

Locate the Default incoming message callback URL field and enter the URL that will receive MO reply callbacks.
Locate the Default status callback URL field and enter the URL that will receive ACK status callbacks.

Note

These URLs serve as the defaults Live Link 365 will send callbacks to, in case you do not provide callback URLs within the payload when requesting to send a message using our API endpoints

When you send an SMS message request to our API, you can use the callback property in the request's JSON payload to specify a particular URL or multiple URLs to receive callbacks that will override the default URLs you specified in your account. These new URLs can each have a security scheme of their own. Below you can find examples of how to structure the callback property in different situations:

Open Authentication

String

{
  "message": "Hello World!",
  "destination": ["1122334455"],
  "acknowledgement": true,
  "ackDeliveredTime":true,
  "callback": "https://your.domain.com/your/endpoint"
}

Array

{
  "message": "Hello World!",
  "destination": ["1122334455"],
  "acknowledgement": true,
  "ackDeliveredTime":true,
  "callback": [{
      "url": "https://your.domain.com/your/endpoint"
  }]
}

Array with 'authType'

{
  "message": "Hello World!",
  "destination": ["1122334455"],
  "acknowledgement": true,
  "ackDeliveredTime":true,
  "callback": [{
      "authType": "OPEN",
      "url": "https://your.domain.com/your/endpoint"
  }]
}

Secure Authentication Types

OAuth 2.0

{
  "message": "Hello World!",
  "destination": [
    "1122334455"
  ],
  "acknowledgement": true,
  "ackDeliveredTime": true,
  "callback": [
    {
      "url": "https://your.domain.com/your/endpoint",
      "authType": "OAUTH2",
      "oAuth2": {
        "oAuthClient": "someHexKey",
        "oAuthSecret": "someHexLongSecret",
        "tokenUrl": "https://your.authserver.com/oauth/token"
      }
    }
  ]
}

Mixed

{
  "message": "Testing, Nakano  Test v2 {{$timestamp}}",
  "destination": [
    "1122334455"
  ],
  "acknowledgement": true,
  "ackDeliveredTime": true,
  "callback": [
    {
      "url": "https://your.domain.com/your/endpoint"
    },
    {
      "url": "https://your.domain.com/your/endpoint",
      "authType": "OAUTH2",
      "oAuth2": {
        "oAuthClient": "someHexKey",
        "oAuthSecret": "someHexLongSecret",
        "tokenUrl": "https://your.authserver.com/oauth/token"
      }
    }
  ]
}

Authentication Settings¶

Please choose the authentication type from the "Auth Type" dropdown.
If you select OAuth as the authentication type, you must check "Show OAuth Info" so that all the fields appear. If you select Open, no further action is needed.
Provide a key, a secret, and an OAuth URL so that Live Link 365 can request a token from your service. With a token from your service, the API will be able to successfully authenticate with your service and deliver the callbacks to the URLs you previously specified.
Click on Save Changes to save the configuration.

Callback Types¶

Incoming Reply¶

Live Link 365 will send an Incoming Reply callback to the preconfigured URL whenever it receives an MO (Mobile Originated) reply to a message it previously sent.

The callback's body will contain a JSON object like the following:

{
  "message": "Test Message",
  "messageId": "1.....7",
  "msisdn": "+1........8",
  "originatingAddress": "8........7",
  "parameters": {
    "accountId": "3...4",
    "dcs": "UTF8",
    "keyword": "SOME-KEYWORD",
    "messageClass": "1",
    "messageId": "9........0",
    "operator": {
      "code": {
        "mcc": "N/A",
        "mnc": "N/A"
      },
      "standard": "GSM"
    },
    "receivedServiceNumber": "1...1",
    "receivedTime": {
      "Date": "Sat, 22 Apr 2017",
      "Time": "01:52:28"
    },
    "udh": "050"
  }
}

Property	Value
message	The message body
messageId	Unique identifier for the send-message request (order ID)
msisdn	Phone number that sent the reply in E.164 format, i.e. it starts with a "+" sign which is followed by the country code and then by the number itself. Example US number: +11234567890
originatingAddress	Phone number that received the reply
parameters	Object holding properties from accountId to udh below
accountId	Unique identifier for the user account
dcs	SMS message encoding. Possible values include: 7b and UTF8. UTF8 encoded message bodies will come in hexadecimal format
keyword	The string that was used to parse the message's content. Not included if MO message was not parsed
messageClass	Received type of short message. There are four possible values: 0, 1, 2, and 3
messageId	Specifies the unique identifier for the MO message. Used to detect duplicates. Given in decimal format
operator	Object containing code and standard properties below
code	Object containing mcc and mnc properties below
mcc	Operator's mobile country code. N/A if none
mnc	Operator's mobile network code. N/A if none
standard	Mobile operator's standard. Possible values are: GSM, GSM_1900, GSM_1800, GSM_3G, FIXED_LINE, CDMA, TDMA, IDEN, PCS, UMTS, AMPS, UNKOWN, and N/A
receivedServiceNumber	Service number sent by mobile operator
receivedTime	Object containing Date and Time properties below
Date	Date MT was received. Format: Day, dd Mmm yyyy
Time	Time at which MT was received. Format: hh:mm:ss
udh	UDH sent by mobile subscriber in hexadecimal format. Property not included when none

Delivery Status¶

Live Link 365 will send this callback whenever it receives a receipt acknowledgement from either the SMS service, the cellular network operator, or the handset device.

You can decide what kinds of information about the delivery of SMS messages should come in the ACK POST requests you receive. For example, if you would like the ACK data to include the sending operator's ID, then you would add the "ackOperatorId": true key-value pair to the JSON body of the send SMS request. Likewise, if you would like the country code of the recipient to appear as well, you would need to add "ackCountryCode": true to the JSON body.

Below is an example of an ACK payload including the aforementioned information.

Selecting ACK info to Receive

Please refer to this site's Send SMS section for more information on the types of information you can request to come in the Acknowledgement payload

{
  "messageId": "1234567890",
  "recipient": "+1.........0",
  "operatorId": 433,
  "countryCode": "US",
  "message": "Message 1 of the order 1234567890 at destination of +1.........0 has been sent at 14:37:48 (GMT) on the 07-02-2020.",
  "status": "DELIVERED"
}

Property	Value
messageId	The message's order ID, i.e., a unique identifier for the message that was requested to be sent.
recipient	The destination number in E.164 format, i.e. it starts with a "+" sign which is followed by the country code and then followed by the number itself. Example US number: +11234567890
operatorId	Unique identifier for the operator network that sent the SMS message
countryCode	Code for the country associated to the phone number that received the SMS message
message	String that describes the message's delivery status. It varies depending on the specific status the message just went through. For example, for a SENT status the message would be: "Message 1 of the order #orderId at destination of #msisdn has been processed at #time"
status	The status of the message. Values can be: SENT: Messaging Gateway processed the message DELIVERED: Message sent to cellular network operator RECEIVED: Operator sent message to handset device ERROR: Message not delivered successfully

Sending an SMS message involves parties that communicate the message to each other and lastly to the destination. These parties are the SMS Service, the cellular network operator, and the destination device (the handset). Because the message is sent from one entity to another through the network, there is a need to know the state of the message's delivery as it jumps from one place to another. Delivery reports, also known as ACKs (Acknowledgements) and NACKs (Negative Acknowledgements), let clients and Live Link 365 know whether the delivery was successful or not.

There are three types of ACKs: System ACKs, SMS-C ACKs, and Handset ACKs. The table below outlines these ACKs and gives a brief description of what they mean:

ACK Type	Description
System ACK	The System Acceptance ACK is generated when an MT message request is processed by the Live Link 365 Messaging Gateway. Enterprises will always receive this acknowledgment, which includes the number of short messages created and their ORDERIDs. System ACKs are related to the SENT status contained in the callback body's message
SMS-C ACK	Generated when an MT message has been sent to the destination mobile operator SMS-C and is waiting to be delivered to the handset. The SMS-C ACK therefore represents a temporary status (awaiting Handset ACK); although in cases where the Handset ACK is not requested, or not supported by the destination operator, the SMS-C ACK constitutes the final notification. SMS-C ACKs are related to the DELIVERED status contained in the callback body's message
Handset ACK	Generated when an MT message has been delivered to the mobile phone. This is an operator-dependent feature. Handset ACKs are related to the RECEIVED status contained in the callback body's message

Contrary to ACK notifications, NACK (Negative Acknowledgement) notifications are delivered upon unsuccessful delivery attempts. NACKs are related to the ERROR status contained in the callback body's message.

Test Callbacks¶

endpoint v.2: /api/v2/sms

Once you have all the prerequisites:

An OAuth token
A working endpoint
Your endpoint's security configuration set up in your Live Link 365 account

follow these steps to send a message using cURL and to then receive a callback from the API when the message reaches the destination number:

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 body with the following properties (optional properties are between brackets):

Property	Value
message	The contents of the SMS message
destination	Array of recipient numbers. For testing purposes, use an array with your number as a member. If only one number, you can send it as a single element array or just the number string with no array at all
acknowledgement	Must set to true if you want to receive ACKs (status callbacks). Default value is false.
[callback]	URL of the endpoint that will receive the callback POST request

The command should look like this:

Mac/Linux

curl -X POST \
-H "Authorization: Bearer yourToken" \
-H "Content-Type: application/json" \
-d '{"message": "Some Message", "destination": ["YOUR-NUMBER"], "acknowledgement": "true"}' \
https://livelink.sapdigitalinterconnect.com/api/v2/sms

Windows

curl -X POST ^
-H "Authorization: Bearer yourToken" ^
-H "Content-Type: application/json" ^
-d "{\"message\": \"Some Message\", \"destination\": [\"YOUR-NUMBER\"], \"acknowledgement\": \"true\"}" ^
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:

{
    "livelinkOrderIds": [
        {
            "destination": [
                "123...789"
            ],
            "livelinkOrderId": [
                "123456789",
                "123456777"
            ]
        },
        {
            "destination": [
                "456...789"
            ],
            "livelinkOrderId": [
                "1453217689",
                "153256777"
            ]
        }
    ]
}

JSON Body Description

Property	Value
livelinkOrderIds	Object 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

HTTP Response vs. Callback

The aforementioned response is NOT the callback POST request. It corresponds to the request you just made. The API will send the callback POST request after the message goes through any of the three delivery process stages

Callback Retry Policy¶

If for an unexpected reason the endpoints you provided to receive callbacks are down, Live Link 365 will reattempt to send callbacks to them.

The Callback Retry Policy behaves in the following way:

The first time delivery fails, Live Link 365 will send three more callbacks, that is, it will send one POST request to your endpoints every five minutes for a max of three times.
If those three POST requests fail to reach your endpoints, it will wait for one hour and send another callback five minutes later.
If the fourth callback fails, two more callbacks will be sent after five minutes, each of them five minutes appart from the other.
If delivery still fails, Live Link 365 will wait another hour and send another callback five minutes after the hour.
If delivery fails, five minutes later, one last callback will be sent as a final attempt.

Number of Retries

The total number of retries adds upt to 8 POST requests

Attempts Chart