Push to Contact API

Overview

Content can either be defined by the Marketer in Acoustic Campaign 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-campaign-us-[your pod number].goacoustic.com/restdoc/#!/channels/pushto_contactspost

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-campaign-us-[your pod number].goacoustic.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 Acoustic Campaign. Personalization is still supported when this feature flag is turned on.

Note: The non-optimized transactional feature is only needed if you are sending the same simple+inbox messages with personalization back-to-back within 2 seconds to the same user. In this case, only one of the messages may be processed. If this is your use-case and you cannot throttle the messages to be sent at a longer interval, then please contact support to discuss this further.

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

Acoustic Campaign 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 Acoustic Campaign
Send to all devices for a given contact

Path Parameters

Not applicable

Request Body

pushTo Contact

Attribute	Required	Description	Data type
channelQualifiers	Yes	channelQualifiers	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
inAppMessage	No	InApp 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}.

InApp Message

Attribute	Required	Description	Data type
expirationDate	Yes	InApp message expiration date represented in a String as per RFC 3339 (‘1970-01-01T00:00:00.000+00:00’)	Date
maxViews	Yes	Maximum number of views on the InApp message	Integer
inAppContentId***	Yes	InApp message content id	InApp message content id

***User must create a content ID using the In-App Content API, post/channels/push/inappcontent, prior to using this API call for a message that includes an inapp message. Using the In-App Content API will generate the In-App content ID needed here. User can also reuse a In-App content ID that was created earlier or by another user.

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
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
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.	String
relevance-score	No	A number value between 0 and 1 to determine how the notification is featured when grouped.	Number

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

AndroidPushPayload

Attribute	Required	Description	Data type
alert (AndroidAlertNode)	No	Android push contents	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
motification-action (Action)	No	Action to perform when notification is pressed	model

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.

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:

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.

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.acoustic.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": "[email protected]",
              "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 Acoustic site",
               "value":"http://www.acoustic.co",
               "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 Acoustic site",
                  "value":"http://www.acoustic.co",
                  "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":"[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"
}

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:

Inline Personalization – When personalization is provided with every contact in API payload.
Contact Lookup Personalization – Values come from contact record in Acoustic Campaign.
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 Acoustic Campaign

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 Acoustic Campaign 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/2020. (Note: Since there is no personalization map at the contact level, and there is no information in Acoustic Campaign, 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.