Medallia Adapter

Every request to the sending service must include authentication, i.e. the equivalent of username and password. To conform to the standard of the Medallia software, the only allowed authentication method for the Medallia adapter sending endpoint is the following:

Callback to Medallia is authenticated, and content integrity verified, by adding a header containing the HMAC SHA-1 signature of the HTTP POST body using a secret supplied by Medallia, as described below.

Probably from the Medallia application. The ordinary application is two-way SMS, i.e. a number from the customer’s number pool will be the sender id shown on the recipient phone, and replies will be to that number.

With the contents of the HTTP body following the conventions of the Medallia software:

Probably from the Medallia application. The ordinary application is two-way SMS, i.e. a number from the customer’s number pool will be the sender id shown on the recipient phone, and replies will be to that number.

If one-way SMS is required, the Medallia system must supply a sender id to be used. In many countries, that id can be alphanumeric, but in some jurisdictions, that alphanumeric sender id must be registered, while other demand a (usually pre-registered) phone number as the sender id. Different countries have different rules about what is a campaign (which must be pre-approved) and what is one-to-one communication (which is often less restricted).

In the following example, the sender id "Shop Ltd" is requested. The SMS standard allows a maximum of 11 characters (spaces included) in a sender id, and results vary when characters outside western European alphabets are used. Note url encoding of the space character ("%20").

With the contents of the HTTP body following the conventions of the Medallia software:

probably from the Medallia application

With the contents of the HTTP body following the conventions of the Medallia software:

In the "channel definition", the parameter Customer send message URL should be set to the adapter url, e.g.

Likewise, in the "channel definition", the parameter Token should be set to the api key of the sending user account in the message gateway e.g.

For the callback functionality (see below), three strings must delivered (once, when setting up the channel) from the Medallia system administrator to our customer service, for inclusion in the database table as described in the following paragraphs.

The three necessary strings are the Instance URL of the Medallia system of the customer, e.g.

and the Page Id inside Medallia of the customer application using Medallia, e.g.

and, finally, the Signing secret used for SHA-1 HMAC signature of the callback HTTP body, for authentication of callback messages to be accepted at this Instance URL, e.g.

Setup for SMS sending inside our system begins with standard two-way API user setup with receipt and incoming callback set to MEDALLIA with the user id as "callback url". The sending user account must have the roles Api and Two-way and the user’s default number pool should contain a single dedicated number, so that conversations are kept together in the recipient phone. Number pool switching, e.g. for different country prefixes, is recommended when the customer needs different senders for different countries, and this is set up in the database table t_number_pool with each of the alternate number pools also containing a single number.

Further send channel parameters and setup of Medallia callback (see below) is done in the database table t_medallia_settings (see next paragraph) where a database row, with the composite key consisting of the (integer) user id and the (string) channel "SMS", contains all further settings of the Medallia adapter for the customer. The three strings needed from Medallia for each customer channel (above) go in this database row.

Note that the SMS sending (as opposed to the callback) functionality of the adapter will work also when no row with the proper user id and "SMS" channel is present. Not so for the future extension to Rich channels, which will have to be defined each in a row in this table, and also in the Rich authorization tables. Such setup will also need further contractual agreements with us and with the respective channel administrative bodies.

This is a callback message informing of an incoming answer to a previously sent message:

The message will have HTTP headers which include

and the HMAC SHA-1 signature of the entire UTF-8 encoded HTTP body using the supplied secret (example is not accurate)

To validate the author and integrity of the callback information, every callback HTTP POST request has a signature in a HTTP header X-Hub-Signature containing the HMAC SHA-1 signature of the entire UTF-8 encoded message HTTP POST body, using the secret received from Medallia for the instance url, as entered into the t_medallia_settings database table.

The following Java code is used to generate the signature.

The Adapter was implemented according to specifications in the document

The fields notification_type and sender_action in the /send/{channel} json request body, as well as any other fields not listed above, are allowed but completely ignored. All json keys must have the capitalization described, i.e., "Recipient" is not a valid alternative to "recipient".

Medallia requests for profileData are not supported by the adapter implementation, and the corresponding HTTP GET endpoint will not be found, so layers outside the adapter implementation are likely to respond with a 404 Not found.

Medallia End-of-conversation signal and Typing signal requests are recognized but not supported by the implementation, and will result in a 400 "Message empty or null" error message, because such requests have a structure similar to a send request missing a message text. To avoid these errors, set "disableEndSignal" in the Medallia account settings, and "Typing off" in the Medallia Custom channel properties.

UTF-8 encoding is assumed everywhere (the standard for json), and where URL-encoding of input data is necessary (e.g. for URL query parameters), the underlying encoding is UTF-8 (the standard for url encoding).

As mentioned above, Rich messaging channels RCS, KakaoTalk and Line are not yet available, but in an advanced stage of preparation.

Note that the Line channel uses a special Line app id instead of a phone number, and the id should not generally be preceded by a + sign or country code. Also, the Line channel does not send successful delivery receipts, but only unsuccessful in such cases.

The character set used in the input to the API does not affect the resulting SMS. Instead, the characters that are requested to be sent will determine the size and pricing of the message.

Most network operators globally support all printable characters in SMS messages. They also support the sending of longer SMS messages by dividing the content into several SMS message parts (with some exceptions, like South Korea). An SMS message part is limited in size to 140 bytes; longer messages will require more parts. The character set used, not the language, will determine how many parts are needed. The pricing is based on the number of SMS message parts sent. Normally, the recipient’s mobile handset will automatically reassemble the parts of a divided message in the correct order, without any action needed by the recipient.

The GSM standard regulates SMS communication globally. While all characters are supported, some characters used in Western European languages are given special treatment. Two character encodings (character sets) are supported by almost all network operators in the world, and therefore by us: GSM-7 and UCS-2.

By GSM-7 we mean the internationally common GSM-7 alphabet according to GSM 03.38 / 3GPP 23.038 without any national language shift table (only the basic character extension). See for example https://en.wikipedia.org/wiki/GSM_03.38 for details.

The GSM-7 encoding uses 7 bits per character to encode only characters from these Western European languages (including numbers and some punctuation), while the UCS-2 encoding can encode characters from any Unicode alphabet and uses 16 bits per character. If every character in a message can be encoded with GSM-7, the message will employ the more compact GSM-7 encoding. If any character in a message cannot be encoded with GSM-7, UCS-2 will be used for the entire message.

Since the GSM-7 is a 7-bit character set, 160 characters will fit into one 140 bytes SMS part. The UCS-2 is a 16-bit character set and can accommodate only 70 characters in a 140 bytes SMS part. If a GSM-7 encoded message is longer than 160 characters, or a non-GSM-7 encoded message is longer than 70 characters, it will be divided into more than one part. Due to how such parts are constructed, multi-part SMS messages can only fit 153 GSM-7 characters or 67 UCS-2 characters per part. All parts of a message will use the same encoding, so they will all be GSM-7 or all UCS-2.

The inclusion, even accidentally, of a non-GSM-7 encodable character in a message will therefore transform it into a UCS-2 encoded message. This message will have a larger number of shorter parts, and the send-out will be more costly. Therefore, when sending SMS messages in Western European languages, it is often advisable to be on the lookout for any such characters that may be included in the message. For instance, some characters automatically generated in some circumstances by Microsoft Word, like curved citation marks (curved quotes) and unbreakable spaces, are not included in the GSM-7 character set. French vowels with the accent circonflexe also do not fit into GSM-7. Unsurprisingly, Cyrillic, Arabic, Chinese, Thai, Japanese and many other alphabets are not included, and neither are emojis, while ordinary text in English, Swedish, Finnish, German and similar languages will fit into the GSM-7 encoding. The Euro-sign (European Union currency symbol) is included in the GSM-7 basic character extension, which we support.

In contrast to SMS, where it is unknown whether the recipient has opened and read the message, many Rich communication channels send one receipt upon message delivery, and a second receipt when the message has been read by the user. The specification for Medallia receipts says that a successful delivery has only one kind of format, without any way of marking whether it pertains to READ or DELIVERED.

Therefore, we offer two options via the flag c_readnotif in the database table t_medallia_settings, each with their own disadvantages.

The first, and default, with flag value N, is to not confuse Medallia with two delivered receipts for the same message. The disadvantage of this is that our system will only deliver callbacks of messages statuses that are of a higher level of finality than earlier callbacked statuses. A READ callback has higher finality than a DELIVERED callback. That means that if, for some reason, the operator sends the READ receipt before the DELIVERED receipt (which can indeed happen), we mark the message as READ, but do not send any callback due to the flag being set to N, and when we get the DELIVERED receipt we do not send any callback, because of the status already being the more final READ. So in those instances, no receipt callback arrives.

The second, with flag value Y, gives at least one, but most of the time two delivered receipts for the same message. The Medallia service provider will have to ensure that this does not cause confusion in the Medallia system.