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 message 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 Required Description Data Type
personalizationDefaults No Map of key value pairs for personalization defaults Map (optional)
personalizationFormulas No Map of key value pairs for personalization formulas Map (optional)
payload No   InappContentMap (optional)

InAppContentMap

Attribute Required Description Data Type
gcm No   InAppTemplateContent (optional)
apns No   InAppTemplateContent (optional)

InAppTemplateContent

Attribute Required Description Data Type
rules No List of inApp message rules to apply Array[String] (optional)
template No  Template name String (optional)
maxViews No Maximum number of views on the InApp message Integer (optional)
content No   InAppContent (optional)

InAppContent

Attribute Required Description Data Type
mainImage No Main image url string String (optional)
title No Title String (optional)
text No Text String (optional)
color No Color String (optional)
icon No Icon String (optional)
action No   InAppAction (optional)

InAppAction

Attribute Required Description Data Type
type No InApp action type  String (optional)
value No InApp action value if any String (optional)

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.

Join The Discussion

Your email address will not be published. Required fields are marked *