Push to device

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 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 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

Atrribute

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

Atrribute

Required

Description

Data type

apns(IosPushPayload)

No

Push content for iOS devices

model

fcm(AndroidPushPayload)

No

Push content for Android devices

model

iOSPushPayload

Atrribute

Required

Description

Data type

aps (APS)

No

APS

model

notification-action (Action)

No

Action to perform when notification is pressed

model

APS

Atrribute

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 iOS 15 version.
  • active (default) - wakes the phone does not interrupt focus mode.
  • time-sensitive - wakes the phone and interrupts the focus mode. Available from 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.

Action

Atrribute

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

Atrribute

Required

Description

Data type

alert (AndroidAlertNode)

No

Android push contents

model

AndroidAlertNode

Atrribute

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

Atrribute

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

Atrribute

Required

Description

Data type

channel

Yes

Channel name

String

name

Yes

Column name

String

value

Yes

Column value

String

DeviceLookup

Atrribute

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

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.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"
              }
            ]
          },
          "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

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)