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 Watson Campaign Automation. 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:

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

  1. Inline Personalization – When personalization is provided with every contact in API payload.

  2. Contact Lookup Personalization – Values come from contact record in Acoustic Campaign.

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