Push to device

To send notifications to a specific subset of devices using the Push to Device API, you must 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 retrieve multiple consent records which are 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 Acoustic Campaign (using default or custom actions in Acoustic Campaign)
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 a Campaign
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
fcm(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
interruption-level	No	Value to determine the priority and timing of of when the user receives the notification. The following values are available: passive - does not interrupt the user. Available from the iOS 15 version. active (default) - wakes the phone and does not interrupt focus mode. time-sensitive - wakes the phone and interrupts the focus mode. Available from the iOS 15 version. critical - requires permission from Apple.
relevance-score	No	A number value between 0 and 1 to determine how the notification is featured when grouped.
content-available	No	If content-available, "1"	String
mutable-content	No	If mutable-content, "1"	String

Note :APNS APS level key: values can be added here and will be passed through to the device.

Action

Attribute	Required	Description	Data type
type	Yes	Type of action to perform	String
name	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

Note: Android alert level key:values can be added here and will be passed through to the device.

Attribute	Required	Description	Data type
highPriority	No	If true, the system attempts to wake the sleeping device and delivers immediately.	Boolean
icon	No	If the image URL is provided, the large icon will be rendered on the right side of the notification.	String
sensitive	No	If true, the notification text will not be displayed on the lock screen.	Boolean
expandable (ExpandableAndroidNode)	No	FCM supports text and image expandable content.	Model

ExpandableAndroidNode

Attribute	Required	Description	Data type
type	No	Either text or image	String
value	No	Additional text to display	String

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-campaign-[data center]-[pod#].goacoustic.com/restdoc/#!/channels/

Request Content Type

application/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.acoustic.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"
              }
            ]
          "icon": "https:some.icon.location.com/image.png"
          "highPriority": true
          },
          "notification-action": {
            "type": "sendEmail",
            "value": {
              "recipient": "[email protected]",
              "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 Acoustic site",
               "value":"http://www.acoustic.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 Acoustic site",
                  "value":"http://www.acoustic.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":"[email protected]",
                     "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

There are four approaches to target an API push:

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. Channel is only usable when you are targeting the lookup key used for the Mobile User ID, and more specifically, since it is already a lookup key, you can omit Channel and just use lookupKey instead (see the previous example).
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 five priorities:

Inline Personalization – When personalization is provided with every contact
Contact Lookup Personalization – First and last name is provided in Engage
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 the Google store online! Don’t forget to tell all your friends about this deal! (Note: Even though the 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 the 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)