Trigger Custom Event
/rest/api/v1.3/events/{eventName}
Request
-
eventName: string
Event Name
object
Trigger Custom Event
-
customEvent:
object customEvent
customEvent.
-
recipientData:
array recipientData
Array of Recipients with Optional Data
object
-
eventDateDataMapping(optional):
string
custom eventDateDataMapping.
-
eventNumberDataMapping(optional):
string
custom eventNumberDataMapping.
-
eventStringDataMapping(optional):
string
custom eventStringDataMapping.
object
-
optionalData:
array optionalData
Array of optional data containing name value pairs.
-
recipient:
object recipient
Information about the Recipient.
array
object
-
customerId:
string
Recipient's Customer ID.
-
emailAddress:
string
Recipient's Email Address.
-
emailFormat:
string
Allowed Values:
[ "HTML_FORMAT", "TEXT_FORMAT" ]
Email Format. -
emailMD5Hash:
string
Recipient's Email MD5 Hash.
-
emailSHA256Hash:
string
Recipient's Email SHA256 Hash.
-
listName:
object listName
Profile List to which the Recipient belongs.
-
mobileNumber:
string
Recipient's Mobile Number.
-
recipientId:
number
Recipient's RIID.
object
-
folderName(optional):
string
Folder Name
-
objectName(optional):
string
Profile List Name.
Response
- application/json
Default Response
array
Trigger Custom Event Response
-
Array of:
object items
Response for individual recipient.
object
-
errorMessage(optional):
string
Error Message, if any, that occurred during the merge or trigger operations.
-
recipientId(optional):
number
The Responsys ID (RIID) of the recipient.
-
success(optional):
boolean
Indicates success or failure.
Examples
Tip:
Need Higher API Call Limits? We have an API on Asynchronous API with the same functionality. Please use the Asynchronous Trigger a Custom Event.You can set up a Program to listen for one or more custom events, which in turn can start a program or be used in a program event switch. This API is used to trigger a specific custom event. The Program will use the existing members of a profile list that are specified in the API request.
- Sending duplicate names in the recipientData results in an error message (MULTIPLE_RECIPIENTS_FOUND).
- A single request is limited to 200 recipients. If you need to trigger a custom event for more than 200 recipients, then you should submit multiple requests to trigger the custom event.
-
Responsys requires the Enactment Batching feature to be enabled when using trigger custom event with mobile app campaigns in Program. Otherwise, the mobile app campaign events in the program will not be processed. However, there are some tradeoffs to consider before enabling the feature. Please refer to the section "Enactment Batching and How It Affects Processing" in the Send Requests topic for more details.
If you have the Real-time Events feature enabled for your account, and you need to send near-real-time messages based on the custom event, then ensure that the custom event you specify is of type Real-time. The Get Custom Events API does not return custom event types in its response, but you can view the custom events and their types by accessing the Define Custom Event Types page in the Account administrator section of Responsys. Contact the Responsys Account Administrator for assistance if you do not have access. For more information, see the Defining Custom Event Types topic in the Oracle Responsys Help Center.
When Enactment Batching is used, the Responsys Account Admin must check the "Include Mobile App Channel RIIDs" check box for the custom event's definition. (In Responsys, this setting is found in Accounts > Account Customization > Global Settings > Define custom event types). With this option set, Responsys creates an enactment for each device associated with every Profile RIID; otherwise, the Push channel enactments will NOT enter the program and by extension, it will not send any push messages to the intended recipients. To avoid duplicate emails when email is part of the orchestration, marketers who orchestration the program must add a data switch immediately before the Email event.
- The Profile List parameters that can be specified are one of
recipientId
,emailAddress
,customerId
,mobileNumber
,emailMD5Hash
, andemailSHA256Hash
. The system processes the attributes in the above-listed order and accepts the first non-null value found. - To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro currency symbol is escaped as \u20AC, the yen currency symbol is escaped as \u00A5, an umlauted u is escaped as \u00FC, an accented e is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.
The following example shows how to raise Custom Events for Cross-channel Marketing Programs.
FIELDS | DESCRIPTION |
---|---|
Authorization | AUTH_TOKEN |
Accept | application/json |
Sample Request Body:
{ "customEvent": { "eventNumberDataMapping": null, "eventDateDataMapping": null, "eventStringDataMapping": null }, "recipientData": [ { "recipient": { "customerId": 1, "emailAddress": null, "listName": { "folderName": "WS_REST_SAMPLE", "objectName": "wsrest" }, "recipientId": null, "mobileNumber": null, "emailFormat": "HTML_FORMAT" }, "optionalData": [ { "name": "CUSTOM1", "value": "value1" } ] } ] }
Sample Response:
[ { "errorMessage": null, "success": true, "recipientId": 72067 } ]