1. Webhook and Callback functionality
The SMS platform includes functionality for callback (pushing, event-driven reporting) of inbound messages (MO) and delivery receipts (DR) to customer environments.
This is in addition to, and complementing the existing polling functionality available through the web services (and through logging in to the web interfaces and looking). The customer will supply a URL where their service will be listening for callback from the service.
The following callbacks are available:
-
DR - Delivery receipt
-
MO - Mobile originated SMS
All the timestamps are from the CET timezone. The customer can specify their preferred timezone in their account settings.
1.1. GET
HTTP GET as UTF-8 URL-encoded URL parameters. Note that space %20 is replaced with +.
See https://tools.ietf.org/html/rfc3986#section-2.1 and https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1
A callback has succeeded when the customer’s server responds with 200 OK.
1.1.1. Delivery receipt - DR
Parameters:
-
id- Unique message ID generated by the service -
from- Sender ID e.g. 46737494333000 or BIGCO or 70303 -
to- Recipient e.g. 46701234567 -
status- Status e.g. Delivered (see Statuses section below) -
statusmessage- Status details e.g. DELIVRD (see Statuses section below) -
timestamp- Formatted timestampYYYY-MM-ddTHH:mm:sse.g.2009-02-14T00:31:30
Example:
https://www.example.com/sms/dr/callback?id=1363257&from=70303&to=12345678901&status=Delivered&statusmessage=DELIVRD×tamp=2009-02-14T00%3A31%3A301.1.2. Mobile originated - MO
Parameters:
-
id- Unique message ID generated by the service -
from- Sender ID e.g. 46701234567 -
to- Recipient e.g. 46737494333000 or a short code like 70303 -
message- The message -
timestamp- Formatted timestampYYYY-MM-ddTHH:mm:sse.g.2009-02-14T00:31:30
Example:
https://www.example.com/sms/mo/callback?id=19334&from=12345678900&to=70303&message=I+am+a+little+teapot×tamp=2009-02-14T00%3A31%3A30Note that this can also be used for customers that poll the inbox after we send a GET polling-trigger, if they ignore the query parameters.
1.2. POST
HTTP POST as a JSON document in the message body.
A callback has succeeded when the customer’s server responds with 200 OK.
1.2.1. Delivery receipt - DR
Parameters in the JSON document:
-
id- Unique message ID generated by the service -
sender- Sender ID e.g. 46737494333000 or BIGCO or 70303 -
recipient- Recipient e.g. 46701234567 -
status- Status e.g. Delivered (see Statuses section below) -
statusmessage- Status details e.g. DELIVRD (see Statuses section below) -
conversation- Conversation ID -
time- Formatted timestampYYYY-MM-ddTHH:mm:sse.g.2009-02-14T00:31:30
Example:
{
"id":"1363257",
"status":"Delivered",
"statusmessage":"DELIVRD",
"sender":"70303",
"recipient":"12345678901",
"conversation":"ABC123",
"time":"2009-02-14T00:31:30"
}1.2.2. Mobile originated - MO
Parameters:
-
id- Unique message ID generated by the service -
sender- Sender ID e.g. 46701234567 -
recipient- Recipient e.g. 46737494333000 or a short code like 70303 -
message- The message -
conversation- Conversation ID -
time- Formatted timestampYYYY-MM-ddTHH:mm:sse.g.2009-02-14T00:31:30
Example:
{
"id":"19334",
"sender":"12345678900",
"recipient":"70303",
"message":"I am a little teapot",
"conversation":"",
"time":"2009-02-14T00:31:30"
}1.3. POST_2
HTTP POST as a JSON document in the message body.
A callback has succeeded when the customer’s server responds with 200 OK.
This is a much extended version of the POST (JSON) callback described above.
The old POST callback is retained unchanged for legacy integrations. With the POST_2 callback,
we hereby warn that new fields may be added later, and that fields where no content is available will
not be present in the JSON. Therefore, deserialization code needs to not stop on new fields or on missing fields.
So far, the incoming/MO callback is identical to the POST callback type, so only the receipt/DR callback format
is described here.
1.3.1. Delivery receipt - DR
Parameters in the JSON document:
-
id- Unique message ID generated by the service -
status- Status (summary) e.g. Delivered (see Statuses section below) -
statuscode- Code for the summary status (2-14, see Statuses section below) -
statusmessage- Status details e.g. DELIVRD (see Statuses section below) -
sender- Sender ID e.g. 46737494333000 or BIGCO or 70303 -
recipient- Recipient e.g. 46701234567 -
conversation- Conversation ID given by the sender echoed here -
time- Timestamp in UTC time zoneYYYY-MM-ddTHH:mm:ssZe.g.2009-02-14T00:31:30Z -
messagetext- Text of the message sent (if still available) -
countrycallingcode- Calling code of the destination number (billing info) -
numberofparts- Number of SMS parts in the message (billing info) -
costcenter- Cost center given by the user for splitting bill (billing info) -
billingid- Billing id assigned to user or otherwise set by system (billing info) -
senttime- Time of sending in UTC time zone e.g.2009-02-14T00:31:30Z -
submittime- Time of submit to operator in UTC time zone e.g.2009-02-14T00:31:30Z -
updatetime- Time of last update before done in UTC time zone e.g.2009-02-14T00:31:30Z -
donetime- Time sending finished in UTC time zone e.g.2009-02-14T00:31:30Z
Example:
{
"id": "17793542",
"status": "Delivered",
"statuscode": 2,
"statusmessage": "DELIVRD",
"sender": "BIGCO",
"recipient": "46706352602",
"conversation": "",
"time": "2026-04-08T09:00:43Z",
"messagetext": "This text comes in the DR callback json",
"countrycallingcode": "46",
"numberofparts": "1",
"costcenter": "DEPT01",
"billingid": "STOCKHOLM",
"senttime": "2026-04-08T09:00:33Z",
"submittime": "2026-04-08T09:00:33Z",
"updatetime": "2026-04-08T09:00:33Z",
"donetime": "2026-04-08T09:00:43Z"
}Some of these fields are not usually present simultanously (e.g. costcenter and billingid) and null fields will not be included in the JSON. Therefore, the deserializing code should not stop on missing fields or on new fields added in later versions.
1.4. POSTFORM
HTTP POST UTF-8 URL-encoded in the message body. Note that space %20 is replaced with +.
See https://tools.ietf.org/html/rfc3986#section-2.1 and https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1
A callback has succeeded when the customer’s server responds with 200 OK.
1.4.1. Mobile originated - MO
Parameters:
-
id- Unique message ID generated by the service -
from- Sender ID e.g. 46701234567 -
to- Recipient e.g. 46737494333000 or a short code like 70303 -
message- The message -
timestamp- Formatted timestampYYYY-MM-ddTHH:mm:sse.g.2009-02-14T00:31:30
Example:
id=19334&from=12345678900&to=70303&message=I+am+a+little+teapot×tamp=2009-02-14T00%3A31%3A301.5. SMTP
The callback will be sent as a plain text message to an email address of the customer’s choice, which is given in the URL field of the settings.
There is no check whether the callback email was successfully delivered.
Note that the callback will be sent as an email in all cases, independent on whether the original SMS was generated from an email, by using an API (REST or SOAP) or from the web portal Send SMS page.
1.5.1. Delivery receipt - DR
Example from sender:
no-reply@sms.lekab.comSubject line:
VSO delivery notificationMessage text:
VSO delivery notification
-----------------------------------------------------------
Message 1041045547 sent to 46701234567
Time: 2021-11-17T10:12:07.911
Subject:
Status : Delivered
-----------------------------------------------------------If the message was not generated by email-to-SMS, the Subject field will be empty, while if it was, the Subject line of the original email-to-SMS email will be shown as the Subject.
1.6. SMTPSPLIT
The callback will be sent as a plain text message to an email address which is supposed to have been stored when the user sent an SMS by using the email-to-SMS functionality. This is in contrast to the SMTP setting (above) which callbacks only to the given email address in the URL field.
To this end, the email-to-SMS functionality administrator must set the email-to-SMS account to "shared user, split callback" so that the sender email will be stored for the purpose of callback.
If the email-to-SMS functionality was not used to send the original SMS, the email address in the URL will be used for callback of receipt and incoming reply. For "cold" incoming messages to a reserved incoming number (short code or long number) the email address in the URL will likewise be used. Note that the callback will be sent as an email in all cases, independent on whether the original SMS was generated from an email, by using an API (REST or SOAP) or from the web portal Send SMS page.
If a blank URL is given, there will be no callback at all, for any messages. Use any dummy URL like "DUMMY" or "X" or "IGNORE" if cold incoming messages and non-email originated SMS receipts and responses are to be ignored, but email originated receipts and two-way responses are to be callbacked to the sender email address.
There is no check whether the callback email was successfully delivered.
1.6.1. Delivery receipt - DR
Example callback email from sender:
no-reply@sms.lekab.comCallback email subject line:
VSO delivery notificationMessage text:
VSO delivery notification
-----------------------------------------------------------
Message 1041295921 sent to 46701234567
Time: 2021-11-17T14:41:54.795
Subject: Important message
Status : Delivered
-----------------------------------------------------------If the message was not generated by email-to-SMS, the Subject field will be empty, while if it was, the Subject line of the original email-to-SMS email will be shown as the Subject.
1.7. Statuses
Delivery Receipt (DR) callback messages indicate success or failure
of sending an SMS message. Usually, either the message got through to the (turned-on)
mobile handset of the recipient: Delivered, or there is an error status.
We send DR callback messages when triggered by getting a delivery receipt from an SMSC further on in the distribution chain, with a status message in it. Thus, we do not send DR callbacks when a message moves from one internal queue to another, nor do we send DR callbacks when a message leaves the last internal queue and is sent to the first in the chain of SMSCs delivering the message to the customer’s home SMSC. However, as soon as we get a notification of success or failure of the sending, we send a DR callback.
If we do not get notification of either success or failure, we do not know whether the message will eventually reach the recipients, but if takes too long, the message will expire and we (from most operators in most countries) get a message telling us that. If no such message arrives, we will not send any callback, but this is a very rare occurrence.
Most messages are delivered, and most operators then send only "DELIVRD", with no extra comments. Otherwise, the status messages we receive when sending fails differ greatly between operators and countries, and we keep a translation table to map known status messages to one of a small number of statuses. In the DR callback, we show this summary status (e.g. Delivered) and also the status message we got from the distributor chain (e.g. DELIVRD or something longer).
The following list gives the statuses that can occur in a DR callback:
| statuscode | status | Description |
|---|---|---|
|
|
Delivered to the mobile station |
|
|
The message was deleted |
|
|
The message has expired |
|
|
The message was rejected by the operator |
|
|
The message could not be delivered |
|
|
The subscribers mobile station is switched off |
|
|
The subscriber is not known |
|
|
The destination address is invalid |
|
|
The mobile station can not receive the message |
|
|
The status of the message is unknown |
|
|
Internal error when sending the message |
|
|
Recipient read message (only for non-SMS channel uplift) |