Push to segment

Push to Segment API can be used from an external system, but not from the Watson Campaign Automation UI. Content must be defined by the user in Watson Campaign Automation and published. The published message ID will be used as the path parameter for this Push to Segment API.

📘

Note:

This API is also known as the Push to Contact Source API.

Prerequisites to API push send

  • The Org must have push enabled by provisioning.
  • A database in the org must have push enabled.
  • An app needs to exist and be made available to mobile devices with specialized code included.
  • Said app needs to be installed on a mobile device with push enabled, which triggers consent with Acoustic Campaign.
  • An org admin user with push enabled and a token is the user that intends to make the API calls.
  • 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.

📘

Note:

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

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

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:

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.

Functionalities available

The Push to Segment API call has POST functionalities.

Swagger URL

https://api[your pod number].silverpop.com/restdoc/#!/channels/sendpush_to_contact_source_post

Scenarios that can be accomplished using this API

  • Send to contact source using a published message that was created in Campaign Automation.
  • Mobile app messages supported:
  • Simple
  • Simple + inbox
  • Simple + Expansion
  • Inbox only
  • In-App only
  • Data only

Features supported

  • Regular personalization can only be used with information known to WCA.
  • Relational table personalization supported published message (with 18.1 release).
  • API does check mobile app frequency limits and honors them.
  • Messages can be scheduled
  • Pre-processing can be specified, see preBlockingHours attribute.
  • Can schedule based on recipient's timezone, see useRecipientTimezone attribute

Path Parameters

Attribute

Data Type

Description

publishedMessageId [required]

string

ID of the published message to be sent

When a mobile app message is created, you have the option to Publish the message in Mobile Push Send Experience on the Schedule this Message page. By selecting the Publish button, the message will be available on the Published message screen and on this page, the Published Message ID is also displayed to that it may be used in an API.

Request Body

sendJobSpecification

Attribute

Data Type

Description

contactSourceId [optional]

long

ID of contact source (ie, database, contact list or query)

campaignName [optional]

string

Campaign name

messageName [required]

string

Message name

folder [optional]

string

Message folder location

scheduledDate [optional]

string

Date on which Push Notification is to be sent.

preBlockingHours [optional]

int

Value representing the blocking time before sending the push notification.

useRecipientTimeZone [optional]

Boolean

Whether or not to use recipient time zone for push notification

📘

Note:

A published message that is already used in an API can be edited in Watson Campaign Automation UI. The published message will have to be republished in order for the latest message to be used in the API call.

Swagger URL

https://api[your pod number].silverpop.com/restdoc/#!/channels/sendpush_to_contact_source

Sample JSON Request Body

{
“contactSourceId”: “332229”,
“campaignName”: “Holiday 2017 Campaign”,
“messageName”: “First October Holiday Offer”,
“scheduledDate”: “2017-10-01T13:00:51.123+00:00”
}