Use this REST API to send simple, published push messages to contact lists.

How It Works

Note: Push to Contact Source/Segment APIs do honor mobile app frequency limits.

Prerequisites to API push send

  1. The Org must have push enabled by provisioning.
  2. A database in the org must have push enabled.
  3. An app needs to exist and be made available to mobile devices with specialized code included.
  4. Said app needs to be installed on a mobile device with push enabled, which triggers consent with Acoustic Campaign.
  5. An org admin user with push enabled and a token is the user that intends to make the API calls.
  6. A user created a simple push message that is published on this org.

Once this has been set up, the user can send a simple published push message to a contact source.

The API user builds an app to do the things that are needed, but if an app isn’t built or ready, one can always use a tool like Swagger to explore the capability of this API.

What must be provided to the API call

The API user must know and supply the following information in the call:

  • Published Message ID (parameter = publishedMessageId). The ID of the published message must be provided. All publishable push message types are supported with this API.
Mobile Messages and Templates
  • Message Name (parameter = messageName). The API requires a value for message name. It must be unique.

The API user can choose to include the following information in the call as well:

  • Contact Source ID (parameter = contactSourceId). The contact source’s ID must be provided. It can be a database, query, or contact list, and it must be enabled for push (or associated with a database that is enabled for push, if a query or contact list).

Campaign Name (parameter = campaignName). While the published push message requires a Campaign Name, the API accepts an optional value that overrides the value in the published push message.

  • If a campaign name element is not provided in the API call, the name element in the published push message is used. Whichever one is used ends up in the sent push message UB attribute for campaign name that is used downstream for tracking/reporting.

Recipient Time Zone (parameter = useRecipeintTimeZone). This optional parameter can be used when scheduling a message. Valid values are “true” or “false”.

  • True– The time specified in the scheduleDate parameter is converted to each recipient’s time zone.
    Note: If scheduled time has already passed for a recipient’s time zone, they will be sent the message immediately.
  • False – The time specified in the scheduleDate parameter reflects the time zone configured in the user profile.
    Note: The table is an example of the optional time zone parameter.
    useRecipientTimeZone True False (or blank)
    User (Marketer) Time Zone Pacific Pacific
    Recipient 1 Time Zone Pacific Pacific
    Recipient 2 Time Zone Eastern Eastern
    Schedule Time 9:00 am 4/25/2017 9:00 am 4/25/2017
    Recipient 1 Send Time 9:00 am Pacific 4/25/2017 9:00 am Pacific 4/25/2017
    Recipient 2 Send Time 9:00 am Eastern 4/25/2017 12:00 pm Eastern 4/25/2017
Note: API developers – Do not include leading/trailing spaces in the Campaign Name. Doing so might lead to inconsistent reporting on Campaign Name downstream. Different engine and analysis tools treat leading and trailing spaces differently and might return mixed results.


13 comments on"REST API to Send Push to Contact Source"

  1. Hi,

    I want to know about “Perform a push notification send to contacts” the Json schema explanation Given Is unclear in the Link please any one can provide adequate Doc for the above one.

    • When I send the Push I Am getting 202 as response , And i checked The sent folder and its not Sent , What Mistake May be I am Doing,?
      Please let me know.


      • Hello Naveen,
        I need to see your API call so that I can further investigate.

        Thank you

    • what is unclear about the Json schema?

  2. Steve_Miller April 05, 2018

    When using the swagger UI for testing what is the correct format for the sendJobSpecification ?

    I am getting a response code of 400 but not sure what the full message format should be.

    “meta”: {
    “attributes”: {},
    “generalErrors”: [
    “Bad Request”
    “fieldErrors”: {},
    “links”: [],
    “nextPageUrl”: null
    “data”: null

    • Hello Steve,
      Please let me know if the below is helpful.

      PushToContact {
      channelQualifiers (Array[String]): List of App keys,
      content (PushContent): Content for push notification,
      contacts (Array[PushContact]): List of contacts,
      personalizationDefaults (Map, optional): Map of key value pairs for personalization,
      campaignName (String): Campaign name
      PushContent {
      contentId (String, optional): publishedMessageId – representing the published message to load contents for push notification,
      inboxMessage (InboxMessage, optional): Inbox message content,
      simple (SimplePushContent, optional): Contents for push notification
      InboxMessage {
      expirationDate (Date): Inbox message expiration date represented in a String as per RFC 3339 (‘1970-01-01T00:00:00.000+00:00’),
      richContentId (RichContentId): Inbox message rich content id
      SimplePushContent {
      apns (IosPushPayload, optional): Push content for iOS devices,
      gcm (AndroidPushPayload, optional): Push content for Android devices,
      IosPushPayload {
      aps (APS, optional): ,
      notification-action (Action, optional): Action to perform when notification is pressed,
      inApp (InApp, optional): InApp message,
      data (Map, optional): Map of key value pairs as data content,
      media-attachment (String, optional): Media url sent with the notification
      APS {
      alert (IosAlertNode, optional): Message to show with title and subtitle,
      badge (Integer, optional): Number to show on App
      IosAlertNode {
      title (String, optional): Title of notification,
      subtitle (String, optional): SubTitle of notification,
      body (String, optional): Message of notification
      Action {
      type (String): Type of action to perform,
      name (String, optional): Name of action to display on notification,
      value (JSONnode): Parameters of action
      InApp {
      rules (Array[String]): List of InApp message rules,
      expirationDate (Date, optional): InApp expiration date represented in a String as per RFC 3339 (‘1970-01-01T00:00:00.000+00:00’),
      maxViews (int): Maximum number of views set for the InApp message,
      template (String, optional): InApp template name,
      content (Map): Map of key value pairs as InApp message content
      AndroidPushPayload {
      alert (AndroidAlertNode, optional): Android push contents,
      inApp (InApp, optional): InApp message,
      data (Map, optional): Map of key value pairs as data content
      AndroidAlertNode {
      subject (String, optional): Subject of notification,
      message (String, optional): Message of notification,
      notification-action (Action, optional): Action to perform when notification is pressed
      PushContact {
      contactId (Long): Engage recipientId takes precedence over lookupKeyFields,
      lookupKeyFields (Array[LookUpKeyField]): List of look up key fields to find contact,
      channel (DeviceLookup, optional): Look up key fields to find a specifc device,
      personalization (Map, optional): Map of key value pairs for personalization
      LookUpKeyField {
      channel (String): Channel name,
      name (String): Column name,
      value (String): Column value
      DeviceLookup {
      qualifier (String): Appkey,
      destination (String): xtifyUserId|xtifyChannelId,
      appKey (String, optional): AppKey, used in place of qualifier,
      userId (String, optional): Xtify User Id, used in place of destination along with channelId,
      channelId (String, optional): Xtify Channel Id, used in place of destination along with userId

      Thank you

      • Steve_Miller April 05, 2018

        Hi Jeri

        this is the similar information to is within the documentation within SwaggerUI!/

        I’m looking for the specific payload and send job specification that I would put into the UI for testing the PushToContact and Send Push to contact source APIs.

        I’ve tried a variety of different inputs but all fail so looking for exactly what to past in so I can then update with required IDs etc

        • Hi Steve,
          Can you send me an example of the info you are using that causes the 400 error code to generate?

          Thank you,

  3. Steve Miller April 20, 2018

    Hi JR

    I worked it out… you need to include quotes around the field name and field values for this to work.


  4. “Use this REST API to send simple, published push messages to contact lists.”

    LOL… which one?

  5. Hi Is there any slack community for watson campaign automation

    • Hello,
      To the best of my knowledge, there are currently no Watson Campaign Automation slack communities.

      Thank you

Join The Discussion

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