Introduction

© 2006 - 2024 Lekab Communication Systems AB. Version 5.1.161, 2024-06-10.

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

  • statusmessage - Status details e.g. DELIVRD

  • timestamp - Formatted timestamp YYYY-MM-ddTHH:mm:ss e.g. 2009-02-14T00:31:30

Example:

https://www.example.com/sms/dr/callback?id=1363257&from=70303&to=12345678901&status=Delivered&statusmessage=DELIVRD&timestamp=2009-02-14T00%3A31%3A30

1.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 timestamp YYYY-MM-ddTHH:mm:ss e.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&timestamp=2009-02-14T00%3A31%3A30

Note 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

  • statusmessage - Status details e.g. DELIVRD

  • conversation - Conversation ID

  • time - Formatted timestamp YYYY-MM-ddTHH:mm:ss e.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 timestamp YYYY-MM-ddTHH:mm:ss e.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. 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.3.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 timestamp YYYY-MM-ddTHH:mm:ss e.g. 2009-02-14T00:31:30

Example:

id=19334&from=12345678900&to=70303&message=I+am+a+little+teapot&timestamp=2009-02-14T00%3A31%3A30

1.4. 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.4.1. Delivery receipt - DR

Example from sender:

no-reply@sms.lekab.com

Subject line:

VSO delivery notification

Message 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.4.2. Mobile originated - MO

Example from sender:

46701234567@sms.lekab.com

Subject line:

SMS from 46701234567 to 46737494333000

Message text:

Yes

Message received 2021-11-17 10:12:35

1.5. 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.5.1. Delivery receipt - DR

Example callback email from sender:

no-reply@sms.lekab.com

Callback email subject line:

VSO delivery notification

Message 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.5.2. Mobile originated - MO

Example callback email from sender:

46701234567@sms.lekab.com

Callback email subject line:

SMS from 46701234567 to 46737494333000

Message text:

Yes

Message received 2021-11-17 10:12:35