Private SSP

Deliver highly personalized messages to encrypted phone numbers with great ease!

Many businesses are averse to sharing contact details of their users with third-party platforms like WebEngage.

We understand your concerns.

This is why, we've made it possible for you to leverage a user's PII (Personally Identifiable Information) for sending SMS campaigns without actually sharing their phone numbers! This can be achieved by setting up a Private SSP API endpoint at your end.

You can think of Private SSP as a proxy layer that decrypts phone numbers of an SMS campaign's target audience before sending it to your SSP for delivery to your users. All you need to do is:

Step 1: Pass hashed PII data to WebEngage from your servers.

Step 2: Set up a Private SSP API endpoint to decrypt hashed phone numbers.

Step 3: Configure Webhooks to ensure that the delivery status of each message is relayed back from your SSP < Decryption Layer < WebEngage dashboard.

Step 4: Select Private SSP as the preferred SSP while creating the SMS campaign. In doing so, we'll send all the messages to the specified endpoint (where you can decrypt the phone numbers and pass them to your preferred SSP).

How Private SSP Setup enables you to send SMS campaigns to encrypted phone numbers

PII Hashing

Let's get you acquainted with PII hashing or how you can encrypt a user's phone number and pass it to your WebEngage account.

Which Attributes Are PII?

WebEngage recognizes the user attributes, phone and email as PII (Personally Identifiable Information). Thus, if you opt for PII hashing, then instead of passing the actual data against these attributes, you will need to pass the corresponding hashes values against the attributes, hashed_phone and hashed_email.

Passing Hashed PII Values

All WebEngage platform integration SDKs enable you to pass hashed phone numbers and email addresses for each user. Here's an example to help you get started:

webengage.user.setAttribute({
  'we_hashed_phone': 'e0ec043b3f9e198ec09041687e4d4e8d',
  'we_hashed_email': '144e0424883546e07dcd727057fd3b62'
});
weUser.setHashedEmail(String hashedEmail)

weUser.setHashedPhoneNumber(String hashedPhoneNumber)
-(void) setHashedEmail:(NSString*)hasdhedemail;

-(void) setHashedPhone:(NSString*)hashedphone;

Please Note:

  • The values passed against hashed_phone must be encrypted in a format that you can decrypt later through the Private SSP.
  • The encrypted value can be a maximum of 512 characters. Additional characters will be truncated.
  • Please ensure that the actual phone number is never passed through this method.

🚧

Start Here

Private SMS Service Provider Basics

  • A private SSP is an API endpoint that you expose for WebEngage to call, which acts as a proxy between WebEngage and your actual SMS service provider.

  • WebEngage hits your Private SSP endpoint with a payload containing the hashed phone identifiers, the message body, and some other data.

  • WebEngage expects a JSON response at that instance denoting synchronous result (request success/failure).

  • WebEngage also subscribes to your Webhooks and expects later hits, passing the subsequent Delivery Status Notifications: delivery (sent, failed) and interaction (clicked).

Here's how this works:

  1. WebEngage makes a POST call to an API endpoint URL you provide us.

  2. You can choose to pass custom data (key-value pairs in headers) in this POST request by adding them to your WebEngage dashboard.
    a. Some headers cannot be overridden (e.g. “Content-Type”: “application/json”).
    b. Custom headers can be used for authentication.

  3. A unique ID will always be passed in custom data: UUID in case of SMS.

  4. The body of the POST request will be in JSON format.

  5. Response for the message request should be passed in the predefined format shown below.

  6. Webhook settings:
    a. URL to be set on your side for real-time delivery reports. This URL can be accessed on WebEngage dashboard under Integrations > Channels in your SSP list as shown below.

b. Delivery Status Notification request to be a POST (predefined JSON format).
c. Delivery Status Notification parameters must include the previously passed UUID.
d. errorCode and errorMessage parameters and values in case of failure should be passed in the predefined format shown below.

🚧

About Link Wrapping/Shortening

If your Private SSP is performing additional link wrapping on the links already wrapped by WebEngage (original URL) anywhere in the request payload, then the wrapped domain must ask the caller to follow the original URL-encoded location.

For example, ket's assume that the SMS has the following hyperlink:

<a href=“https://google.co.in/?param=%3D%3D%2B%20%20abcd”> Link </a>

We have a parameter named param with a value of ==+ abcd here.

Thus, if you are further wrapping this link, then the wrapped domain must ask the caller to follow the URL-encoded location (https://google.co.in/?param=%3D%3D%2B%20%20abcd), and not the decoded one (https://google.co.in/?param===+ abcd).

Request

{
  "version": "1.0",
    "smsData" :{
        "toNumber"  : "abc12345",
        "fromNumber": "PAXXXN",
        "body"      : "Text message"
    },
    "metadata": {
        "campaignType": "PROMOTIONAL",
        "custom": {
            "key1": "val1",
            "key2": "val2"
        },
        "timestamp": "2018-01-25T10:24:16+0000",
        "messageId": "webengage-message-id"
    }
}

Response

{
    "status" : "sms_accepted"
}
{
    "status" : "sms_rejected",
    "statusCode" : 2001, // null in case of SMS_SENT
    "message" : "YOUR IP IS NOT WHITELISTED" // null in case of SMS_SENT
}
{
    "status" : "sms_rejected",
    "statusCode" : 2010, // null in case of SMS_SENT
    "message" : "VERSION NOT SUPPORTED",
  "supportedVersion" : "2.0" // mandatory in case of statusCode 2010
}

Delivery Status Notification

{
  "version": "1.0",
    "messageId" : "webengage-message-id",
    "toNumber" : "abc12345",
    "status" : "sms_sent",
  "statusCode" : 0
}
{
  "version": "1.0",// Mandatory
    "messageId" : "XXXXXXXXXXXX",
    "toNumber" : "abc12345",
    "status" : "sms_failed",
  "statusCode" : 2007, // Mandatory
  "message" : "EXCEEDING MAX LENGTH"
}
KeyDescription
versionThis indicates the payload contract of the request. If there is any change in the payload structure in future, the version will be updated.
messageIdThe unique ID assigned to the message which is used to identify a message uniquely. This is received by the private SSP in the request body.
toNumberThe message recipient’s phone number along with country code as prefix.
statusThe message status being reported by this DSN. This can be either sms_sent or sms_failed.
statusCodeStatus code of this DSN. This must be one of the status codes described below.

Status codes

WebEngage will respond to the delivery status notification sent by the service provider with an HTTP 2XX response code and will enqueue the event to process it. Here's a list of all the response codes for your reference:

Status CodeDescriptionHTTP Status
0To be sent in case of success200
2000Insufficient credit balance200
2001The IP has not been whitelisted401
2002Empty message body400
2003Invalid mobile number400
2004Invalid Sender ID400
2005Authorization failure403
2006User under DND403
2007Maximum length of the message body has been exceeded413
2008The message has expired200
2009The message was not delivered by the operator200
2010Payload version unsupported.

In this case the supportedVersion is to be sent mandatorily, i.e., the version supported by the service provider. For example:
HTTP 400 BAD REQUEST { "status" : "sms_rejected", "statusCode" : 2010, "message" : "Version not supported", "supportedVersion" : "2.0" }
400
2011Authentication failure401
2015Throttling error.

To handle the loads with increasing customer base, WebEngage has introduced autoscaling which can occasionally result in higher call rates. WebEngage supports throttling from SSP end to handle such cases. Sending this status code will activate throttling for that request and WebEngage will send that request at later time.

Note:
1. WebEngage will retry sending the message 10 times if this status is received.
2. Time interval between retries follows binary exponential backoff: 0ms, 200ms, 400ms, 800ms...
429
3000Recipient Blacklisted403
9988Unknown reason200

We hope this has enabled you to set up a decryption layer for sending SMS campaigns to encrypted phone numbers. Please feel free to drop in a few lines at [email protected] in case you have further queries. We're always just an email away!

Updated 2 months ago


Private SSP


Deliver highly personalized messages to encrypted phone numbers with great ease!

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.