Templates and Property Substitution

Customers can configure endpoints on their servers to receive webhooks for various events supported by SMSPortal. SMSPortal substitutes data into webhook fully configurable webhook requests through a mechanism whereby a customer configures a template in our portal and when the webhook is ready to be dispatched from our system the applicable variables are injected into the customer's template.

NOTE 1: The term"property" or "variable" is used interchangeably.

Property Notation and Types

We use a similar @@ notation to our sending pages for adding properties in webhooks (eg. @@SentId@@).

Properties have a type (long, integer, string, json). This is provided so that customers understand how to parse these properties (eg. wrap string properties in quotation marks, etc.).

***NOTE 2 *: The json property refers to a nested object and is only applicable to HTTP POST requests.

As will become evident, some properties are only available to certain types of webhooks and further some properties are only available if the webhook is a HTTP POST request.

Customers are responsible for ensuring that valid query parameters are being built in HTTP GET webhooks and/or that valid JSON is being built in HTTP POST webhook requests (eg. not substituting a string without "", etc.). Our portal tooling does assist with this validation.

Example HTTP GET Substitution

URL Template:

https://www.your-example-domain.com?type=@@Type@@&customerRef=@@CustomerRef@@&msgNumTo=@@MsgNumTo@@&landingPageVersion=@@LandingPageVersion@@&landingPageName=@@LandingPageName@@

Resolved URL (after property substitution):

https://www.your-example-domain.com?type=REDIRECT&customerRef=your_optional_reference_id&msgNumTo=27000000001&landingPageVersion=Version1&landingPageName=ExampleLandingTemplate

Example HTTP POST Substitution

Request Body Template:

{
  "phoneNumber": "@@PhoneNumber@@",
  "customerId": "@@CustomerId@@",
  "type": "@@Type@@",
  "interactionUtc": @@InteractionUtc@@,
  "landingPageName": "@@LandingPageName@@",
  "landingPageVersion": "@@LandingPageVersion@@",
  "landingPageComponentId": "@@LandingPageComponentId@@"
}

Resolved Request Body (after property substitution)

{
  "phoneNumber": "27000000001",
  "customerId": "your_optional_reference_id",
  "type": "REDIRECT",
  "interactionUtc": 1735718400,
  "landingPageName": "ExampleLandingTemplate",
  "landingPageVersion": "Version1",
  "landingPageComponentId": "button_77"
}

Truncation

To align with the URL and JSON body length limitations (discussed later), we do apply truncation to the SentData, NumberValue1, and IncomingData properties applicable to the SMS Delivery Receipt and SMS Reply webhooks.

If a value is truncated, it will end with ...

Limitations are imposed as follows:

SentData is limited to 157 characters (160 incl. ...).
NumberValue1 is limited to 157 characters (160 incl. ...).
IncomingData is limited to 477 characters (480 incl. ...).

***NOTE 3 *: Should customers require the full data for these fields they can use the reporting functionality in the customer portal.

Default Templates

We make default templates available to our customers for each type of webhook.

The default template contains all the information that SMSPortal believe to be essential for that type of webhook.

This provides a good starting point for customers to configure their own webhook integrations from.

Backwards Compatibility

We maintain backwards compatibility through our legacy/deprecated properties. These should not be used in new webhooks but may still be used in existing webhooks. Existing webhooks won't be affected by the updated properties.