To send notifications to specific subset of devices using the Push to Device API, you will need to filter devices by Mobile User Id, Channel Id and App Key per contact. In Push to Device, sending is limited to a subset of devices.

The only difference between the Push to Device API and the Push to Contact API is how the recipient is looked up. In Push to Contact specifying one contact_Id may end up retrieving multiple consent records which are actually different devices.

Functionalities available

The Push to Device API call has POST functionality.

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

Scenarios that can be accomplished using this API

  • Send to one or more contact ids using existing content in Engage (using default or custom actions in Engage)
  • 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 Engage ​
  • Send to all devices for a given contact
  • Send to a specific device 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

PushContent

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

SimplePushContent

Attribute Required Description Data Type
apns(IosPushPayload) No Push content for iOS devices model
gcm(AndroidPushPayload) No Push content for Android 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

APS

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

Action

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

AndroidPushPayload

Attribute Required Description Data Type
alert (AndroidAlertNode) No Android push contents model

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

PushContact

Attribute Required Description Data Type
content (PushContent) No Optional content to override base push content. Note: ContentId is not allowed when overriding content for contact. model
contactId No Acoustic Campaign recipientId takes precedence over LookUpKeyFields Long
LookUpKeyFields No List of lookup key fields to find contact. For Push, the Mobile user Id can be specified without specifying the column name. Array [LookUpkeyField]
channel (DeviceLookup) No Lookup key fields to find a specific device. model
personalization No Map of key value pairs for personalization. Map

LookupKeyField

Attribute Required Description Data Type
channel Yes Channel name String
name Yes 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

Swagger URL

https://api[your pod number].silverpop.com/restdoc/#!/channels/

Request Content Type

appliction/json

Sample JSON Request Body

{
  "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": "my subject",
          "message": "Hello world!",
          "expandable": {
            "type": "text",
            "value": "This is a very long text that I used for demonstrating Android's BigText style.,
            "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": {
    "first_name": "John",
    "last_name": "Doe"
  },
  "campaignName": "push to contact campaign name"

Sample JSON Request Body (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.",
                     "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.",
                  "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.",
                     "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.",
                        "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.",
                  "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"
}

Contact lookup

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

  • 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.
  • 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.
  • Channel – The Channel first finds the lookupKeyFields for the channel and then uses the value to search the same lm_channel_lookup table.
  • 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.

Personalization

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

  1. Inline Personalization – When personalization is provided with every contact
  2. Contact Lookup Personalization – First and last name is provided in Engage
  3. Default Personalization – Greeting such as ‘Dear Valued Customer’ is used if Inline Personalization or Contact Lookup Personalization is not used

First we fetch the personalization provided for the contact. 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 and personalize using that. If that is not enough then the default personalization is used. In the code we merge the maps and apply personalization in one go.

Flexible payload is also supported

Example 1

{
   "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.",
                        "color" : "ffffff"},
        "background":"http://i.imgur.com/n0w2cH7.png",
        "header": "http://i.imgur.com/lKHAWtI.png"
    }
}

Example 2

{
"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!",
        "notification-action": {
          "name": "Open URL",
          "value": "https://store.google.com/category/phones",
          "type": "url"
        }
      }
    }
  }
},
"personalizationDefaults": {
  "first_name": "Valued",
  "last_name": "Customer",
  "event_description": "Some event"
},
"contacts": [
  {
    "contactId": 1,
    "personalization": {
      "first_name": "Mary",
      "last_name": "Jane",
      "event_description": "Google store online"
    }
  },
  {
    "contactId": 10,
    "personalization": {
      "event_description": "Amazon.com"
    }
  }
  {
    "contactId": 20
  },
],
"campaignName": "Notification with personalization"
}

Assuming contacts have the following information in the Acoustic Campaign:

  • ContactId = 1 – first_name: Evelyn, last_name: Jones
  • ContactId = 20 – first_name: Michael, last_name: Smith
  • ContactId = 30 – first_name: , last_name: – no first_name and last name recorded

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! (Note: Even though contact has last and first name, the information provided in the personalization map at the contact level would be used.)
  • ContactId = 10: Dear Michael Smith! Welcome to our annual sale at Amazon.com! Don’t forget to tell all your friends about this deal! (Note: First_name, last_name from the contact information in the Acoustic Campaign will be used, but event_description would come from personalization map at the contact level.)
  • ContactId = 20: Dear Valued Customer! Welcome to our annual sale at Some event! Don’t forget to tell all your friends about this deal! (Note: Since there is no personalization map at the contact level, and there is no information in the Acoustic Campaign, personalization defaults will be used)

Go Back to the Mobile App Messaging home page.

Join The Discussion

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