InApp message integration guide

Carma Inapp Messaging Overview

Revision pA1

 

Revision History

pA1                        First Draft.

pA2                        Payload modifications, and detailed info on content retrieval

pA3                        Note on server architecture, and example on TPS/App communication

 

Introduction

InApp Messaging (IAM) is a channel in Carma that complements the current Email, SMS, App Push channels. You can use IAM with all Carma Modules, e.g. Campaign, Transactional, and Autosend.

IAM is a method where messages generated in Carma are pushed to a 3rd party system (TPS). When a message is ready, it will be delivered immediately over HTTPS POST to the TPS. In addition, an “inbox” is available for each individual user. This inbox can be polled to retrieve messages that have not yet been displayed to the user, e.g. if the user was not online when the message was first delivered.

For instance, a betting company can have messages about new deals that a user will see when they logon to the site or displayed directly if the customer is online.

The actual delivery of InApp message delivery and inbox management is implemented using a serverless microservice architecture, ensuring maximum availability and performance.

Overview

IAM messages can be custom text or HTML. If HTML format is used, note that the messages will typically be viewed in a browser (computer or mobile), so you should make sure you use a template that allows for more functionality that an email template, such as video and javascript. You can also attach custom metadata to an IAM message.

When sending a message Carma will post a notification to the endpoint on your TPS to enable the message to be displayed directly if a user is online. In the case a user isn’t online you can fetch unexpired messages from an inbox.

The notification message contains general information regarding the message, i.e. recipient, subject, and custom metadata, along with URLs for retrieval of the actual message content. See below for detailed information on the notification payload format.

Basic flow: User is online

 

 

The actual message notification between the TPS and App will be highly implementation-specific. E.g. in the case when the App is a web application, a suitable solution would be to use e.g. Websockets or HTTP/2 Server Push.

Login flow: Retrieve pending messages from inbox

 

 

Customer Implementation

In order to use IAM, you should develop an URL resource that can receive the messages from carma. The resource should accept a HTTPS POST with application/json content type, containing the message payload described below.

The resource URL can have any format. It needs to be configured in Carma under Account Settings.

It is recommended that the TPS resource be protected with some authentication scheme. You may specify any custom header and value to be included in the HTTPS POST. The custom header may be e.g. be a Basic Auth Authorization header, or a custom authentication token validated by the TPS. The custom header is configured along with the resource URL under Account Settings.

API description

Notify recipient that is online

If you push a message from Carma this will send the request directly to the endpoint configured as described above. This will enable you to display this message immediately when you receive it if your customer is online.

Message notification

Carma will send the message notifications as POST requests with the following headers:

Content-Type:Application/json

Accept:application/json

X-Custom-Authentication-Header: secret

The X-Custom-Authentication-Header entry is the custom header specified under Account Settings as described above.

 

 

Message notification payload

The payload is formatted as JSON and looks as follows:

{

“originalId”: ABC123,

“contactId”: 12345,

“mailOpenedCallbackUrl”: “https://www.carmamail.com/mail/MOS… “,

“contentUrl”: “https://url.to.content/download”

“consumeContentUrl”: “https://url.to.content/consume”

“subject”: “This is a message to you”,

“expirationTime”: “2017-01-30T12:00:00+02”,

“metadata”: {

“someKey”: “someValue”,

“someOtherKey”: “someOtherValue”

}

}

  • orginalId: This is the primary key of the user in the TPS database
  • contatId: this is the primary key of the user in the Carma database
  • mailOpenedCallbackUrl: this link can be used to mark the IAM as read in Carma. Issue a HTTP GET to this URL to get opening statistics in Carma if you are not using HTML messages. If you are using HTML, the rendering of the message will call this URL automatically.
  • contentUrl: The location to use for downloading message content. This URL is valid for a maximum of one hour.
  • consumeContentUrl: The location to use for downloading message content, and mark the message as consumed. When this URL is called, the message will be considered by Carma to be consumed, and will not be returned by the inbox resource described above when checking for pending message.
  • subject: this is the subject as defined in the Carma user interface.
  • expirationTime: The message expiration time, in ISO8601 format.
  • metadata: this field contains additional information that the Carma rendering engine can add to the message.

Retrieve pending messages for user on login

All pending messages for a specific user can be retrieved with a HTTPS GET to the URL

<TBD>

For security reasons, this GET request needs to include a custom HTTP header containing an authentication token. This token can be retrieved in the Carma administration interface under Account Settings.

<Describe authentication token header here>

Only messages that are not expired (with respect to the expirationTime) will be returned. The response will be a JSON list with message payloads of all pending messages for the user (see message payload description below).

The GET request should be issued with the following headers

Content-Type:Application/json

Accept:application/json

Message inbox response payload

The message inbox response payload is a JSON list of message notification payloads, e.g.:

[

{

“originalId”: ABC123,

“contactId”: 12345,

“mailOpenedCallbackUrl”: “https://www.carmamail.com/mail/MOS…”,

“contentUrl”: “https://url.to.content/123456/download”,

“consumeContentUrl”: “https://url.to.content/123456/consume”,

“subject”: “This is a message to you”,

“expirytime”: “2017-01-30T12:00:00+02”,

“metadata”: {

“someKey”: “someValue”,

“someOtherKey”: “someOtherValue”

}

},

{

“originalId”: ABC123,

“contactId”: 12345,

“mailOpenedCallbackUrl”: “https://www.carmamail.com/mail/MOS…”,

“contentUrl”: “https://url.to.content/123457/download”,

“consumeContentUrl”: “https://url.to.content/123457/consume”,

“subject”: “This is a another message to you”,

“expirytime”: “2017-01-31T12:00:00+02”,

“metadata”: {

“someKey”: “someValue”,

“someOtherKey”: “someOtherValue”

}

}

]