Overview

Content can either be defined by the Marketer in the Watson Campaign Automation or passed in the payload of the Push Send API.

Notes:

Use this Swagger URL when sending messages via the Push to Contact API and when mobile app frequency limit(s) do NOT need to be honored or checked. These messages will NOT count towards mobile app frequency limits.
URL: https://api[your pod number].silverpop.com/restdoc/#!/channels/push_to_contacts_post_

Use this Swagger URL when sending messages via the Push to Contact API and when mobile app frequency limit(s) need to be honored and supported.
URL:https://api[your pod number].silverpop.com/restdoc/#!/channels/push/sends/useAppFrequency

Non-Optimized Transactional Push

Users can now send back to back mobile app messages within seconds using the Push to Contact API if they enable the Non-Optimized Transactional Push feature. Please contact Support to enable this for your organization.

When the Non-Optimized Transactional Push feature is turned on, it will not support the unified inbox use case.

For iOS messages, Apple automatically blocks mobile app messages that are sent back to back.

This feature does not impact mobile app messages sent from the Mobile Send Experience in Watson Campaign Automation. Personalization is still supported when this feature flag is turned on.

Functionality available

The Push to Contact API call has POST functionalities.

  • POST: This call creates a push notification.
  • POST /channels/push/sends

Scenarios that can be accomplished using this API Edit section

  • Watson Campaign Automation Send to one or more contact IDs by using content defined in the API payload (by using default or custom actions in the API payload)
  • Send to one or more contact ids using content defined in the API payload (using default or custom actions in the API payload)
  • Use personalization in the content from either an external system or the Watson Campaign Automation
  • Send to all devices for a given contact

Path Parameters

Not applicable

Request Body

pushTo Contact

Attribute Required Description Data Type
channelQualifiers Yes List of App keys Array[String]
content(PushContent) Yes Content for push notification model
contacts Yes List of contacts Array[PushContact]

Array[pushContact]

Attribute Required Description Data Type
personalizationDefaults No Map of key value pairs for personalization Map
campaignName*** No Campaign name model

***To ensure message is associated with a particular campaign, campaign name must be entered. If campaign name is not entered, then default ‘No Campaign Name Provided’ will be submitted.

PushContent

Attribute Required Description Data Type
contentID No UUID – representing delivery draft to load contents for push notification String
inboxMessage No Inbox message content model
simple(SimplePushContent) No Contents for push notification model

Inbox Message

Attribute Required Description Data Type
expirationDate Yes Inbox message expiration date String
richcontentID*** No Inbox message rich content id model

***User must create rich content using the Create Rich Content API, post/channels/push/richcontent , prior to using this API call for a message that includes an inbox message. Using the Create Rich Content API will generate the richcontentID needed here. User can also reuse a richcontentID that was created earlier or by another user. User can review the content of the rich message using the richcontentID in the Get Rich Content API, GET/channels/push/richcontent/{richContentId}.

SimplePushContent

Attribute Required Description Data Type
apns(IosPushPayload) No Push content for iOS devices model
gcm(AndroidPushPayload) No Push content for Android devices model
wns(WindowsPushPayload) No Push content for Window devices model

iOSPushPayload

Attribute Required Description Data Type
aps (APS) No APS model
notification-action (Action) No Action to perform when notification is pressed model
inApp No InApp message model
data No map of key value pairs as data content map
media-attachment No media url sent with the notification String

APS

Attribute Required Description Data Type
alert No Message to show on notification String
badge No Number to show on App Integer

IosAlertNote

Attribute Required Description Data Type
title No Title of notification String
subtitle No Subtitle of notification String
body No Message of notification String

Action

Attribute Required Description Data Type
alert Yes Type of action to perform String
name No Name of action to display on notification String
value Yes Parameters of action JSONnode

InApp

Attribute Required Description Data Type
rules Yes List of InApp message rules Array[String]
expirationDate No InApp expiration date String
maxViews Yes Maximum number of views set for the InApp message. Integer
template No InApp template name String
content Yes May of key value pairs as InApp message content Map

AndroidPushPayload

Attribute Required Description Data Type
alert (AndroidAlertNode) No Android push contents model
inApp No InApp message/td>

model
data No Map of key value pairs as data content Map

AndroidAlertNode

Attribute Required Description Data Type
subject No Subject of notification String
message No Message of notification String
notification-action (Action) No Action to perform when notification is pressed model

WindowsPushPayload

Attribute Required Description Data Type
contentType No Windows push payload content type String
xml No Windows push payload xml content String

PushContact

Attribute Required Description Data Type
contactId Yes if lookupkeyfields is not specified** WCA recipientId takes precedence over LookUpKeyFields Long
LookUpKeyFields Yes if contactid is not specified** List of lookup key fields to find contact. Array [LookUpkeyField]
channel (DeviceLookup) No Lookup key fields to find a specific device. model
personalization No Map of key value pairs for personalization. Map

**User must enter contactID or LookUpKeyFields. If multiple LookUpKeyFields are entered, only the first lookup key will be used to find the contact.

LookupKeyField

Attribute Required Description Data Type
channel Yes Channel name String
name Yes if channel is not push Column name String
value Yes Column value String

DeviceLookup

Attribute Required Description Data Type
qualifier Yes AppKey String
destination Yes Mobile UserId|Mobile Channel Id String
appKey No AppKey, used in place of qualifier String
userId No Mobile user id, used in place of destination along with channelId String
channelId No Mobile Channel Id, used in place of destination along with userId String

Contact lookup:

There are 4 different ways a contact can be identified:

  1. recipientId – RecipientId is the most basic where you can simply identify one contact and we fetch all the consent records for that contact and send messages to them.
  2. lookUpKey – lookupKeyFields takes the name of the column and finds it in lm_contact_lookup_key and then searches the lm_contact_lookup table for the value to get the recipientId.
  3. channel – The channel first finds the lookupKeyFields for the channel and then uses the value to search the same lm_channel_lookup table.
  4. device – Push to device is “basically” push to consent where we just look at the consent record for qualifier and destination to fetch the recipientId.

Example with inline content:

Body edit section{
  "channelQualifiers": [
    "appkey1",
    "appkey2"
  ],
  "content": {
    "contentId": null,
    "simple": {
      "apns": {
        "aps": {
          "content-available": 1
        },
        "dynamic-aps": {
          "alert": "Hello %first_name%, welcome to our holiday sale!",
          "badge": 1
        },
        "notification-action": {
          "name": "phone",
          "value": "1234567890",
          "type": "dial"
        },
        "category-actions": [
          {
            "name": "phone",
            "value": "1234567890",
            "type": "dial"
          },
          {
            "name": "Open URL",
            "value": "http://www.ibm.com",
            "type": "url"
          }
        ]
      },
      "gcm": {
        "alert": {
          "subject": "Holiday Sale",
          "message": "Here is your offer!",
          "expandable": {
            "type": "text",
            "value": "This is a very long text that is being used to demonstrate Android's BigText style. Because this is an expandable notification, all the text is displayed.",
            "expandable-actions": [
              {
                "type": "url",
                "name": "url",
                "value": "http://www.google.com"
              },
              {
                "type": "dial",
                "name": "phone",
                "value": "1234567890"
              }
            ]
          },
          "notification-action": {
            "type": "sendEmail",
            "value": {
              "recipient": "mytestemail@email.com",
              "subject": "Check out this deal!",
              "body": "Great Sale"
            }
          }
        }
      }
    }
  },
  "contacts": [
    {
      "contactId": "1234567890"
    },
    {
      "contactId": "2345678901"
    }
  ],
  "personalizationDefaults": {
    "name": "Dear Valued Customer"
  },
  "campaignName": "Holiday campaign name"
}

Example of using contentID (also known as publishedMessageID):

{
  "channelQualifiers": [
    "ap4N57J41k",
    "gc0Q96u1It"
  ],
  "content": {
    "contentId": "ac626bd2-2811-4034-b4ee-a5843326eb0c"
  },
  "contacts": [
    {
      "contactId": 2355736758,
      "personalization": {
        "first_name": "Mary",
        "last_name": "Jane",
        "product_message":"20%"
    }
    },
    {
      "contactId": 2352588805,
      "personalization": {
        "first_name": "Mary",
        "last_name": "Jane",
        "product_message":"20%"
    }
    }
  ],
  "personalizationDefaults": {
    "first_name": "John",
    "last_name": "Doe",
    "product_message":"10%"
  },
  "campaignName": "Data published test"
}

Example with extra parameters:

{  
   "channelQualifiers":[  
      "appkey1",
      "appkey2"
   ],
   "content":{  
      "contentId":null,
      "simple":{  
         "apns":{  
            "aps":{  
               "content-available":1,
               "watch-dynamic":{  
                  "title":{  
                     "text":"The M Hotel NYC",
                     "align":"center",
                     "color":"ffffff"
                  },
                  "body":{  
                     "text":"Luxurious pampering awaits you at Mspa, enjoy 20% off full body hot stone massage.",
                     "color":"ffffff"
                  },
                  "background":"http://i.imgur.com/n0w2cH7.png",
                  "header":"http://i.imgur.com/lKHAWtI.png"
               }
            },
            "watch-dynamic":{  
               "title":{  
                  "text":"The M Hotel NYC",
                  "align":"center",
                  "color":"ffffff"
               },
               "body":{  
                  "text":"Luxurious pampering awaits you at Mspa, enjoy 20% off full body hot stone massage.",
                  "color":"ffffff"
               },
               "background":"http://i.imgur.com/n0w2cH7.png",
               "header":"http://i.imgur.com/lKHAWtI.png"
            },
            "dynamic-aps":{  
               "alert":"Hello %%first_name%% %%last_name%%, welcome to Test iPad sale!",
               "badge":1,
               "watch-dynamic":{  
                  "title":{  
                     "text":"The M Hotel NYC",
                     "align":"center",
                     "color":"ffffff"
                  },
                  "body":{  
                     "text":"Luxurious pampering awaits you at Mspa, enjoy 20% off full body hot stone massage.",
                     "color":"ffffff"
                  },
                  "background":"http://i.imgur.com/n0w2cH7.png",
                  "header":"http://i.imgur.com/lKHAWtI.png"
               }
            },
            "notification-action":{  
               "name":"Visit IBM site",
               "value":"http://www.ibm.com",
               "type":"url",
               "extra":{  
                  "watch-dynamic":{  
                     "title":{  
                        "text":"The M Hotel NYC",
                        "align":"center",
                        "color":"ffffff"
                     },
                     "body":{  
                        "text":"Luxurious pampering awaits you at Mspa, enjoy 20% off full body hot stone massage.",
                        "color":"ffffff"
                     },
                     "background":"http://i.imgur.com/n0w2cH7.png",
                     "header":"http://i.imgur.com/lKHAWtI.png"
                  }
               }
            },
            "category-actions":[  
               {  
                  "name":"Visit Apple Store",
                  "value":"http://store.apple.com",
                  "type":"url"
               },
               {  
                  "name":"Visit IBM site",
                  "value":"http://www.ibm.com",
                  "type":"url"
               }
            ]
         },
         "gcm":{  
            "alert":{  
               "subject":"my subject",
               "message":"Hello %%first_name%% %%last_name%% welcome to Test iPad app!",
               "expandable":{  
                  "type":"text",
                  "value":"This is a very long text that I used for demonstrating Android's BigText style. Because this is an expandable notification, all the text is displayed.",
                  "expandable-actions":[  
                     {  
                        "type":"url",
                        "name":"url",
                        "value":"http://www.google.com"
                     },
                     {  
                        "type":"custom",
                        "name":"custom",
                        "value":"myintent"
                     },
                     {  
                        "type":"dial",
                        "name":"phone",
                        "value":"0509473828"
                     }
                  ]
               },
               "notification-action":{  
                  "type":"sendEmail",
                  "value":{  
                     "recipient":"testing@us.ibm.com",
                     "subject":"Check out this deal!",
                     "body":"Test iPad sale!"
                  }
               }
            }
         }
      }
   },
   "contacts":[  
      {  
         "lookupKeyFields":[  
            {  
               "name":"Mobile User Id",
               "value":"Mobile User Id1"
            }
         ],
         "personalization":{  
            "first_name":"Jason",
            "last_name":"Bourne"
         }
      }
   ],
   "campaignName":"campaign name here"
}

Flexible payload is also supported
Example

{
   "aps": {
       "alert": "Bob wants to play poker",
       "badge": 5,
       "flexible properties here": {}
   },
   "notification-action": {
       "type": "mytype",
       "value": "myvalue",
       "flexible properties here": {}
   },
   "flexible properties here": {}
}

Example (watch-dynamic could include more items like map and logo):

{
aps:{}
"watch-dynamic":{
        "title": {"text": "The M Hotel NYC" ,
                      "align":"center",
                       "color" : "ffffff"},
        "body": {"text": "Luxurious pampering awaits you at Mspa, enjoy 20% off full body hot stone massage.",
                        "color" : "ffffff"},
        "background":"http://i.imgur.com/n0w2cH7.png",
        "header": "http://i.imgur.com/lKHAWtI.png"
    }
}

Personalization

Personalization is very unique in Push to contact. We have three levels of personalization based on 3 priorities:

  1. Inline Personalization – When personalization is provided with every contact in API payload.
  2. Contact Lookup Personalization – Values come from contact record in Watson Campaign Automation.
  3. Default Personalization – Greeting such as ‘Dear Valued Customer’ is used if Inline Personalization is not provided or Contact Lookup Personalization is not found.

First we fetch the personalization provided for the contact in the API call. If the fields that were provided match all the personalization fields in the content then we do not have to look any further. If all fields are not provided, then we look at the actually contact and fetch the columns for the contact and personalize using those values that were fetched. If that is not enough then the default personalization is used. In the code we merge the maps and apply personalization in one go.

Personalization Example

{
"channelQualifiers": [
  "appkey1",
],
"content": {
  "simple": {
    "gcm": {
      "alert": {
        "subject": "Don't miss this sale!",
        "message": "Dear %%first_name%% %%last_name%%!  Welcome to our annual sale at %%event_description%%!  Don't forget to tell all your friends about this deal!  Hurry up, deal expires on %%expiration_date%%",
        "notification-action": {
          "name": "Open URL",
          "value": "https://store.google.com/category/phones",
          "type": "url"
        }
      }
    }
  }
},
"personalizationFormulas": {
    "expiration_date": "format(Customer_Date, \"dd-MM-yyyy\")"
},
"personalizationDefaults": {
  "first_name": "Valued",
  "last_name": "Customer",
  "event_description": "Holiday event",
  "expiration_date" : "12/31/2017"
},
"contacts": [
  {
    "contactId": 1,
    "personalization": {
      "first_name": "Mary",
      "last_name": "Jane",
      "event_description": "Google store online"
    }
  },
  {
    "contactId": 20,
    "personalization": {
      "event_description": "Amazon.com"
    }
  }
  {
    "contactId": 30
  },
],
"campaignName": "Notification with personalization"
}

Assuming contacts have the following information in the Watson Campaign Automation:

  • ContactId = 1 – first_name: Evelyn, last_name: Jones, Customer_Date: 12/31/2018
  • ContactId = 20 – first_name: Michael, last_name: Smith, Customer_Date: 12/25/2018
  • ContactId = 30 – first_name: , last_name: – no first_name and last name recorded, no Customer_Date specified

The following personalized messages display:

  • ContactId = 1: Dear Mary Jane! Welcome to our annual sale at Google store online! Don’t forget to tell all your friends about this deal! Hurry up the deal expires on 31-12-2018. (Note: Even though contact has last and first name, the information provided in the personalization map at the contact level would be used instead.)
  • ContactId = 20: Dear Michael Smith! Welcome to our annual sale at Amazon.com! Don’t forget to tell all your friends about this deal! Hurry up the deal expires on 25-12-2018 (Note: First_name, last_name from the contact information in the Watson Campaign Automation will be used, but event_description would come from personalization map at the contact level.)
  • ContactId = 30: Dear Valued Customer! Welcome to our annual sale at Holiday event! Don’t forget to tell all your friends about this deal! Hurry up the deal expires on 12/31/2017. (Note: Since there is no personalization map at the contact level, and there is no information in the Watson Campaign Automation, personalization defaults will be used)

Personalization Formulas can also be used as shown in the above example:

"personalizationFormulas": {
    "customerbirthday": "format(Birthday, \"dd-MM-yyyy\")",
    "expiration_date": Personalization Formulas can also be used as shown in the above example:"format(Customer_Date, \"dd-MM-yyyy\")"
  }

Note: In order for personalization to work in a rich message, a personalizationDefault map must be included in the payload when the rich message is created. This is different from the personalizationDefaults passed in via the API call. The rich personalizationDefaults map should contain values for all fields that could be replaced in the rich message via the API call.

Go Back to the Mobile App Messaging home page.

Join The Discussion

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