Appendix A: Webhooks

The Lark Router supports advanced webhooks or APIs to expand functionality.  The third-party system will need to be configured to support those APIs. A description provided for each one.

Message Routing using Webhooks #

The routing Webhook is called with an HTTP POST body containing a JSON object. The fields are listed below

Fields

FieldDescriptionValuesRequired
phone-numberDestination NumberRequired
shortcodeDestination ShortcodeRequired
Message-subjectSubject of the messageRequired
bind_idID of the bind that message was received onRequired
directionMobile Originated or Mobile TerminatedMO/MTRequired
message-idUnique Message Identification numberNumericalRequired
message-typeType of messageMMS/SMS

The webhook must return the HTTP 200 code, and a single line of the form:

  • destination-bind: e.g. “Client-001” which is the bind through which the message should be sent. For MT this should be the supplier bind ID, for MO, it should be the client bind ID. Alternatively:
  • destination-bind-type,destination-bind: e.g. “supplier, Supplier-001” where the first string before the comma is the type of bind (must be set to supplier or carrier), and the string after the comma is the bind ID as above. This form of response makes it possible to, say, route a supplier-originated MO MMS back to a supplier as an MT MMS, by returning the bind-type as the supplier. 

No response or timeout will result in the message being rejected.

Example Request

{"phone-number": "165123456",
"message-type": "mms", "message-subject": "xyz123", "bind-id": "carrier1",
"direction": "MO", 
"message-id": "00001", }

Example Response

supplier,mm7-carrier-bind-1

CDR Webhook #

Overview

The Lark router supports a CDR Webhook to allow Providers to collect, maintain, report, and store events based on their corporate policies. An HTTP POST using JSON is available. This webhook is called when an MT message is delivered, expired or rejected. For MO it is called when the message is forwarded to the VASP.

To configure this, go to

Configuration ->Lark -> Queues, CDR & Caching

Set External CDR API URL to the URL that the Lark router will post the billing event to.

You may also change how long the Lark Router will store the CDRs in the server. The default is 365 days.

Once the message is received (The webhook receives and HTTP 200) the next event will be posted synchronously.

CDR Parameters

FieldDescriptionValuesNotes
message-dateDate/Time in UTC message is sent“YYYY-MM-DDTHH:MM:SSZ”Required
cdr-dateDate/Time in UTC CDR is sent“YYYY-MM-DDTHH:MM:SSZ”Required
source-bindIncoming message routeRequired
destination-bindOutgoing message routeRequired
fromOriginatorRequired
toDestinationRequired
sizeMessage sizeBytesRequired
message-typeSend/receive/ contentm-send-request; m-send-recvRequired
message-priorityMessage sent with High Priority or Low priorityHigh/Low Default =LowOptional
carrier-message-idProvided by the carrier on MM7 link, default value for MM1Optional
delivery statusDelivery Status (Carrier messages only)Retrieved/FailedOptional
dlr-statusDelivery Status (Carrier messages only)Expired, Failed, Unreachable, Retrieved, etc.Optional
Message Parameters
transaction idUnique identifierSequential numberRequired
mms-versionVersion of MMS encoding1.00 Default
content-typesText, pictures, audioList of content types in messageRequired
delivery-reportWas a delivery report providedYes/NoRequired
message-typeSend/receive/ contentm-send-request; m-send-recvRequired
Envelope Parameters
priorityPriority Indicator0 or 1Default 0
directionMobile Terminated or Mobile DeliveredMO or MTRequired
message-idID number given to the message by the carrierAvailable Only with DLROptional
attemptsAttempts made to deliver the messageAvailable only with DLROptional

Example

{
"cdr-params":{
"message-date":"2019-02-13T10:47:03Z",
"cdr-date":"2019-02-13T10:49:03Z",
"source-bind":"newscorp2",
"destination-bind":"local",
"from":"111",
"to":"222",
"size":4494,
"message-type":"MMS",
"message-priority":"low",
"carrier-message-id":"201902131046411550044001",
"transaction-id":"e55670WZNo",
"delivery-status":"Sent"
},
"message-params":{
"mms-version":"1.0",
"delivery-report":"Yes",
"content-types":[
"application/octet-stream"
]
},
"envelope-params":{
"direction":"MT",
"priority":"0",
"attempts":"2"
}
}

Billing Webhook #

Overview

The Lark router supports a Billing Webhook to assist Providers in billing their clients for message traffic. An HTTP POST using JSON is available.

To configure this, go to

Configuration→Lark → Queues, CDR & Caching

Set External Billing to the URL that the Lark router will post the billing event to.

and

Choose when the billing event should be posted.

  • On MMS Submission to the Gateway.

This is the default behavior as all messages counted in licensing totals and will be invoiced to the provider,

  • On MMS Submission to the Destination bind.

This would be used when only forwarded messages are to be billed to your customer.

  • On MMS Delivery to Destination Phone or VASP (DLR is received)
    Billed upon delivery (Success).

Once the event is received (HTTP 200) the next event will be posted this is a synchronous process.

Field Description

FieldDescriptionValuesNotes
message-dateDate/Time in (Zulu) UTC“YYYY-MM-DDTHH:MM:SSZ”Required
source-bindIncoming message routeRequired
destination-bindOutgoing message routeRequired
fromOriginatorRequired
toDestinationRequired
sizeMessage sizeBytesRequired
message-priorityMessage sent with High Priority or Low priorityHigh/Medium/LowOptional. Default is Low
dlr-statusDelivery Status (Carrier messages only)Available only when DLR is receivedOptional
Message Parameters
transaction-idUnique identifierOptional
MMS-versionThe version of MMS encoding1.0
content-typesText, pictures, audioList of content types in messageRequired
message-typeSend/receive/ contentm-send-req, etc.Required
Envelope Parameters
priorityPriority Indicator0 or 1Default 0
directionMobile Terminated or Mobile DeliveredMO or MTRequired
message-idID number that is given to the message by the carrierAvailable Only with DLROptional
attemptsAttempts made to deliver the messageAvailable only with DLROptional

Notes:

  • carrier-message-id: The message ID on the carrier side. This will only appear for messages to a carrier
  • dlr-status: The delivery status (for a DLR only)
  • delivery-status: For messages to a carrier, this will be indicated if the message was accepted for delivery or rejected.

Example:

{
   "cdr-params":{
      "message-date":"2018-10-19T13:59:25Z",
      "cdr-date":"2018-10-19T13:59:40Z",
      "source-bind":"testcorp",
      "destination-bind":"carrier1",
      "from":"222",
      "to":"111",
      "size":70,
      "message-type":"m-send-req",
      "message-priority":"low",
      "carrier-message-id":"dc35a3LtVu",
      "delivery-status":"Retrieved",
      "dlr-status":"Retrieved"
   },
   "message-params":{
      "transaction-Id":"112001",
      "mms-version":"1.0",
      "content-types":"text/plain",
      "delivery-report":"Yes",
      "message-type":"m-send-req"
   },
   "envelope-params":{
      "priority":"0",
      "direction":"MT",
      "message-id":"dc35a3LtVu",
      "attempts":"1"
}