External Logic Integration (ELI)

External Logic Integration (ELI) is a feature of SMPP Router that enables programmatic control over SMS message flow through real-time HTTP callbacks. When a message is submitted via SubmitSM, the router can invoke a customer-defined HTTP endpoint to make dynamic decisions about how the message should be handled.

This mechanism allows external systems to inspect message metadata—such as sender, recipient, content, IP address, and system ID—and respond with instructions that influence routing, rejection, delivery behaviour, and tagging.

Typical use cases:

• Enforcing custom routing policies

• Blocking messages based on source/destination patterns

• Integrating fraud detection or compliance logic

• Simulating delivery failures for testing or billing logic

By using ELI, businesses gain fine-grained control over message processing without modifying the SMPP Router’s internal logic.

ELI Requests

Request Types

Request Formats

Example ELI request type 0 (SubmitSM ESME-to-target)

{
  "ipaddr": "127.0.0.1",
  "submitsm": {
    "data_coding": 0,
    "dest_addr_npi": 1,
    "dest_addr_ton": 1,
    "destination_addr": "337700222333",
    "esm_class": 0,
    "priority_flag": 0,
    "protocol_id": 0,
    "registered_delivery": 1,
    "replace_if_present_flag": 0,
    "schedule_delivery_time": 0,
    "service_type": "",
    "short_message": [
      72,
      101,
      108,
      108,
      111,
      32,
      119,
      111,
      114,
      108,
      100,
      33
    ],
    "sm_default_msg_id": 0,
    "source_addr": "447700111222",
    "source_addr_npi": 0,
    "source_addr_ton": 0,
    "tlvs": [
      {
        "length": 1,
        "tag": 264,
        "value": "\u0003"
      }
    ],
    "validity_period": "2025-07-24T18:06:06.318Z"
  },
  "systemid": "esme001",
  "type": 0
}

The JSON of a “type 0” ELI request comprises the following fields:

• type : 0

• systemid : SMPP system ID of ESME

• ipaddr : IP addess of ESME

• submitsm : fields of the SubmitSM PDU

ELI Responses

When SMPP Router sends a request to an ELI webhook, the response can optionally be used to perform some operation in relation the the request. An empty response indications no action, resulting in SMPP Router processing the relevant SMPP PDU as if the ELI had not been called.

Where a response is provided by the ELI webhook, it will be one of the following actions:

Action: "action" in ELI JSON Response

The action field within the JSON response from an External Logic Integration (ELI) request dictates how the SMPP Router should handle a SubmitSM message. This field is evaluated following the invocation of the ELI HTTP endpoint, and supports conditional routing, rejection, or modification of messages.

"reject" action

Indicates that the message should be outright rejected. The SMPP Router will respond to the ESME with a SubmitSMResp indicating failure. By default, the response will carry ESME_RSUBMITFAIL, unless overridden by an optional cmdstatus field in the JSON.

Example:

{
  "action": "reject",
  "cmdstatus": 0x0000000B
}

In this case, the message is rejected and the response includes ESME_INVDSTADR (0x0000000B).

"reject_dlr" action

This instructs SMPP Router to accept the message from the ESME, but simulate rejection by generating a Delivery Receipt (DLR) with a status such as UNDELIV, EXPIRED, etc. This is typically used when the router needs to fabricate a delivery failure without rejecting the original submission.

Optional fields:

• status: DLR status code (e.g. 5 for UNDELIV)

• networkerror: Optional 8-bit error code to include in DLR

Example:

{
  "action": "reject_dlr",
  "status": 5,
  "networkerror": 1
}

“modify” action

This instructs SMPP Router to modify one or more message fields.

Example - Change source address, source TON and source NPI:

{
  "action": "modify",
  "parameters": [
    {
      "parameter": "sm.source_addr",
      "value": "441234567890"
    },
    {
      "parameter": "sm.source_addr_ton",
      "value": 1
    },
    {
      "parameter": "sm.source_addr_npi",
      "value": 1
    }
  ]
}

Example - Change source address and remove a specific TLV:

{
  "action": "modify",
  "parameters": [
    {
      "parameter": "sm.source_addr", 
      "value": "67890"
    },
    {
      "parameter": "tlv_",
      "op": "remove",
      "value": 1234
    }
  ]
}

Example - Change source address and add TLV with numeric value:

{
  "action": "modify", 
  "parameters": [
    {
      "parameter": "sm.source_addr",
      "value": "555123"
    },
    {
      "parameter": "tlv_",
      "op": "add",
      "value": {
        "tag": 5678,
        "value": 65535
      }
    }
  ]
}

Example - Change source address and add TLV with byte array:

{
  "action": "modify",
  "parameters": [
    {
      "parameter": "sm.source_addr",
      "value": "777888"
    },
    {
      "parameter": "tlv_",
      "op": "add", 
      "value": {
        "tag": 9012,
        "value": [0x48, 0x65, 0x6C, 0x6C, 0x6F]
      }
    }
  ]
}

Parameters that can be modified through the ELI "modify" action:

String Parameters (value type: string)

Numeric Parameters (value type: number)

TLV Parameters

TLV Add Object Structure:

{
  "tag": number,     // TLV tag (e.g., 1234)
  "value": string|number|array   // TLV value
}

TLV Value Types:

• String: "CustomValue" (converted to bytes)

• Number: 65535 (converted to big-endian bytes)

• Array: [72, 101, 108, 108, 111] (raw byte values)

Example Usage:

Modify String Parameters:

{
  "parameter": "sm.destination_addr",
  "value": "441234567890"
}

Modify Numeric Parameters:

{
  "parameter": "sm.data_coding", 
  "value": 8
}

Modify TLV:

{
  "parameter": "tlv_",
  "op": "add",
  "value": {
    "tag": 1234,
    "value": "Hello"
  }
}

Future and Custom Actions

The system can be extended to support additional actions such as:

• "route_override": Override target routing

• "annotate": Tag the message for logging/billing

• "delay": Introduce artificial delay before submission

These are not yet standardised, but may be supported in future releases or custom deployments.

Summary

All ELI responses must be valid JSON, and if an action is not specified or unrecognised, SMPP Router will proceed with normal processing.