In-App content API

In-app messages will be retrieved when you bring the app to the foreground. This means that in-app messages delivered as the result of a location- or beacon-triggered program will not be available until the user puts the app in the background and brings it to the foreground at least once, or triggers a location change, after the delay associated with phone home expires. (This delay may be up to 24 hours.)

📘

Note:

The way a user sends an in-app message using the UI will not change, and the in-app template will not change.

REST APIs for in-app messages

In-app messages are no longer associated with a push message. Therefore, changes need to be made to the payload of your in-app messages.
In-app mobile app messages now look more like inbox mobile app messages. What this means is that you'll have to publish the in-app message first, get an inAppContentId for that message, and then refer to the inAppContentId when you use the API to send a message.
If you create a custom in-app message with unique information for each of your users, contact support to go over what the best solution is for you.

InAppContentRequest

Attribute

Data Type

Description

personalizationDefaults [Optional]

Map

Map of key value pairs for personalization defaults.

personalizationFormulas [Optional]

Map

Map of key value pairs for personalization formulas

payload [Optional]

InappContentMap

n/a

InAppContentMap

Attribute

Data Type

Description

gcm [optional]

InAppTemplateContent

n/a

apns [optional]

InAppTemplateContent

n/a

InAppTemplateContent

Attribute

Data Type

Description

rules (optional)

Array[String]

List of inApp message rules to apply

template (optional)

String

Template name

maxViews (optional)

Integer

Maximum number of views on the InApp message

content (optional)

InAppContent

n/a

InAppContent

Attribute

Data Type

Description

mainImage (optional)

String

Main image url string

title (optional)

String

Title

text (optional)

String

Text

color (optional)

String

Color

icon (optional)

String

Icon

action (optional)

InAppAction

n/a

InAppAction

Attribute

Data Type

Description

type (optional)

String

InApp action type

value (optional)

String

InApp action value if any

Default In-App Payload

{
  "personalizationDefaults": "Map",
  "personalizationFormulas": "Map",
  "payload": {
    "gcm": {
      "rules": [
        "String"
      ],
      "template": "String",
      "maxViews": "Integer",
      "content": {
        "mainImage": "String",
        "title": "String",
        "text": "String",
        "color": "String",
        "icon": "String",
        "action": {
          "type": "String",
          "value": "String"
        }
      }
    },
    "apns": {
      "rules": [
        "String"
      ],
      "template": "String",
      "maxViews": "Integer",
      "content": {
        "mainImage": "String",
        "title": "String",
        "text": "String",
        "color": "String",
        "icon": "String",
        "action": {
          "type": "String",
          "value": "String"
        }
      }
    }
  }
}

Publishing the message

To publish your in-app message, send a POST to /channels/push/inappcontent with a payload that represents your in-app message. Here are four examples.

Example 1 – Bottom banner placement

{
  "payload": {
    "gcm": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "mainImage": "http://imgur.com/aoeu",
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "color": "#00ff00",
        "icon": "note",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    },
    "apns": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "mainImage": "http://imgur.com/aoeu",
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "color": "#00ff00",
        "icon": "note",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    }
  },
  "personalizationDefaults": {
    "First_Name": "Valued Customer",
    "expiration_date": "",
    "cust_timestamp": ""
  },
  "personalizationFormulas": {
    "cust_timestamp": "format(Dated, \"dd-MM-yyyy\")",
    "expiration_date": "format(Customer_Date, \"dd-MM-yyyy\")"
  }
}

Example 2 – Top banner placement

{
  "payload": {
    "gcm": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "orientation": "top",
        "mainImage": "http://imgur.com/aoeu",
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "color": "#00ff00",
        "icon": "note",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    },
    "apns": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "orientation": "top",
        "mainImage": "http://imgur.com/aoeu",
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "color": "#00ff00",
        "icon": "note",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    }
  },
  "personalizationDefaults": {
    "First_Name": "Valued Customer",
    "expiration_date": "",
    "cust_timestamp": ""
  },
  "personalizationFormulas": {
    "cust_timestamp": "format(Dated, \"dd-MM-yyyy\")",
    "expiration_date": "format(Customer_Date, \"dd-MM-yyyy\")"
  }
}

Example 3 – Image template

{
  "payload": {
    "gcm": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "image": "http://imgur.com/aoeu",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    },
    "apns": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "image": "http://imgur.com/aoeu",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    }
  },
  "personalizationDefaults": {
    "First_Name": "Valued Customer",
    "expiration_date": "",
    "cust_timestamp": ""
  },
  "personalizationFormulas": {
    "cust_timestamp": "format(Dated, \"dd-MM-yyyy\")",
    "expiration_date": "format(Customer_Date, \"dd-MM-yyyy\")"
  }
}

Example 4 – Video template

{
  "payload": {
    "gcm": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "video": "https://www.youtube.com/watch?v=sju3XOy-Jc8",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    },
    "apns": {
      "rules": [
        "all"
      ],
      "template": "default",
      "maxViews": 3,
      "content": {
        "title": "Hello %%First_Name%%",
        "text": "Hello %%First_Name%%, this offer expires at %%expiration_date%% starting now %%cust_timestamp%%",
        "video": "https://www.youtube.com/watch?v=sju3XOy-Jc8",
        "action": {
          "type": "url",
          "value": "http://store.apple.com"
        }
      }
    }
  },
  "personalizationDefaults": {
    "First_Name": "Valued Customer",
    "expiration_date": "",
    "cust_timestamp": ""
  },
  "personalizationFormulas": {
    "cust_timestamp": "format(Dated, \"dd-MM-yyyy\")",
    "expiration_date": "format(Customer_Date, \"dd-MM-yyyy\")"
  }
}

After doing the POST, you'll receive an ID back that will look something like this:

{
    "meta": {
        "attributes": {},
        "generalErrors": [],
        "fieldErrors": {},
        "links": [],
        "nextPageUrl": null
    },
    "data": {
        "location": "https://api0.silverpop.com/rest/channels/push/inappcontent/MqUONG7y",
        "id": "MqU8NG7y"
    }
}

Use the value from the id field when you send your in-app message.

📘

Note:

There is no place to see this ID in the user interface; if you misplace it, you will need to publish the message again to get a new ID.

Sending an in-app message to a user

After publishing the message, POST to /channels/push/sends or /channels/push/sends/usingAppFrequency to send it. The InAppContent ID can also be used in the push to segment with inline content API:POST /channels/push/sendjobs

📘

Note:

The value of inAppContentId in the inAppMessage section of the payload is the same value you received for id when you published the in-app message.

{
  "channelQualifiers": [
…
  ],
 "content": {
    "inAppMessage": {
      "expirationDate": "2018-08-25T22:34:51.123+00:00",
      "maxViews": 3,
      "inAppContentId": "MqU8NG7y"
    }
  },
  "personalizationDefaults": {
    "first_name": "Valued",
    "last_name": "Customer"
  },
  "contacts": [
    {
      "contactId": 13507,
      "personalization": {
        "first_name": "Michael",
        "last_name": "iOS iPhone"
      }
    }
  ]
}

Sending an in-app message to a contact source (segment)

You can send an in-app message to a contact source. For this you would POST to /channels/push/sendjobs, and would need both the contact source ID and the in-app message ID:

"contactSourceId": 10111,
  "campaignName": "In-app only",
  "messageName": "In-app only 2016-06-15",
  "appKeys": [
    …
  ],
  "content": {
    "inAppMessage": {
      "expirationDate": "2018-08-25T22:34:51.123+00:00",
      "maxViews": 3,
      "inAppContentId": "MqU8NG7y"
    }
  }
}

If you use /channels/push/sends/usingAppFrequency, in-app messages will count towards your total messages sent. Sending one in-app push will reduce by one, the total number of other messages you can send during a time period.
Don't confuse message frequency with maxViews: a single in-app message may permit multiple viewings (up to maxViews) after delivery.