CustomEvent
This help page is for Desktop Studio. This information is also available for CXone Studio.
|
Creates a custom event through which you can deliver unique data. Custom events allow users to pass a string to a specific agent. They can be generated in response to an agent-related action such as OnAnswer. They can also be generated before an agent is assigned as long as TargetAgent is populated in this action's properties. The generated custom event enters the agent event stream. To receive a custom event, join the agent session to listen for events, for example, using the get-next-event paradigm. Custom events are useful if the existing events don't quite fit your use case. |
Supported Script Types
|
|
|
|
|
|
|
Generic |
Chat | Phone | Voicemail | Work Item | SMS |
Input Properties
These properties define data that the action uses when executing.
Property |
Description |
---|---|
Caption |
Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon. |
TargetAgent |
The ID of the agent that the custom event is targeting. The Studio script populates the AgentId variable after the OnAnswer event for an inbound call. The custom event only executes when the AgentId is populated. If you would like to send a custom event prior to agent assignment, you must supply an agent ID to the TargetAgent field. |
EventName |
Enter the name you for the custom event. Multiple events with the same name overwrite each other. Only the most recent event name is kept. This field is case-sensitive. |
PersistInMemory |
If an event is executed when an agent is logged out and you’d like them to receive the event once they log back in, set this value to true. Otherwise, set as false. |
Data |
Data payload for this event. |
Result Branch Conditions
Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.
Condition |
Description |
---|---|
Default | Path taken unless the script meets a condition that requires it to take one of the other branches. It is also taken if the action's other branches are not defined. |
OnAgentNotConnected | Path taken if the destination agent is not connected. |
Script Example
In this script example, the branches exemplify three scenarios in which you'd spawn a custom event:
-
Branch 1: Initiating and receiving a custom event before any agent interaction. The custom event is received by the get-custom-event loop when a contact presses 1.
View example payload
{ "sessionId": "aUF6WkZJeW1nNno4NUp1eEhwZkxGdVgzaUJIRjIyMWlkaUQ2NkN0ejN0VkFyODQ4UFBZV3BiOVhRUT09", "events": [ { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "type": "CustomEvent", "eventName": "This can be anything", "data": "Menu Press 1" } ] }
-
Branch 2: Initiating and receiving a custom event prior to any agent interaction. The custom event is received by the get-custom-event loop when a contact presses 2. Also, another custom event is spawned after the Reqagent fires and before the agent answers the call.
View example payload
Payload before any agent interaction:
{ "sessionId": "NGVFOEd4UmJIdnlGWCtLblFEanRRSldtU2hDcXgxc1JhSUVHZ0NKNXdBSVRxa0F3MjhiOCtQM2E=", "events": [ { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "type": "CustomEvent", "eventName": "This can be anything", "data": "Menu Press 2" { ] }
Payload after Reqagent fires and before the agent answers the call:
{ "sessionId": "NGVFOEd4UmJIdnlGWCtLblFEanRRSldtU2hDcXgxc1JhSUVHZ0NKNXdBSW4xeThiR0M2R1FBYlBhZz09", "events": [ { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "type": "CustomEvent", "eventName": "This can be anything", "data": "Menu Press 2 and post reqAgent" { ] }
-
Branches 2 & 3: Initiating and receiving a custom event after an agent answers the call.
View example payload
{ "sessionId": "aktmZEY1aFpDWlVwM0FzenhzTHZ2TnhJanpsZjR5SXhsekYwaUN2TjFYbUcwOW82cjRsZVdIc1FKdz09", "events": [ { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "Type": "CallContactEvent", "ContactID": "510965166955", "MasterID": "510965166955", "Status": "Active", "OriginalState": "False", "CallType": "Regular", "DNIS": "", "ANI": "", "Skill": "23097992", "IsInbound": "True", "StartTimeUTC": "2024-07-12T15:46:38.000Z", "StartTime": "2024-07-12T15:46:38.000Z", "LastStateChangeTimeUTC": "2024-07-12T15:47:11.000Z", "LastStateChangeTime": "2024-07-12T15:47:11.000Z", "ScreenPopUrl": "", "DisconnectCode": "NA", "IsLogging": "False", "Timeout": "", "AllowDispositions": "True", "Label": "", "IsLinked": "False", "TimeZones": "", "FinalState": "False", "OtherInformation": "", "OtherInformationNewFormat": "", "BlendingToSkillName": "", "DeliveryType": "None", "CustomData": "", "ComplianceRecord": "False", "ConfirmationRequired": "False", "ParentContactId": "0", "OmniGroupId": "0", "ExternalId": "", "AnsMachineOverride": "False", "AnsMachineOverrideEndTime": "", "CustomerCardUrl": "", "InteractionId": "6a006eee-03d3-49fd-8aa9-614482684721", "IsRequireManualAccept": "False", "PhoneCallRefusalTimeOut": "45", "FaxMachineOveride": "False" }, { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "type": "CustomEvent", "eventName": "This can be anything", "data": "This is a sample message after onAnswer" }, { "IISHost": "AOA-B32COR01", "VCHost": "AOA-B32COR01", "Type": "Mute", "AgentMuted": "True" } ] }
Create Custom Events via API
You can also create a custom event with the custom-event API . This may be necessary if the CustomEvent action does not meet the requirements of your use case. Because services typically already consume the agent event stream, this can be a convenient method of sharing data without needing to implement your own custom endpoint. This is particularly relevant for small scope apps or microservices.
![Closed](../../../../Skins/Default/Stylesheets/Images/transparent.gif)
You ask contacts their favorite color in the IVR Automated phone menu that allows callers to interact through voice commands, key inputs, or both, to obtain information, route an inbound voice call, or both.. You package and pass this selection as a custom event named FavoriteColor. You also have a companion service running with your agent application that listens for the FavoriteColor event. This lets you pass the contact's color selection to the companion service. The service then displays the color inside the agent application.
Using the API is similar to the Studio action, except you use parameters instead of properties. Using CXone APIs also requires that you implement API authentication. When using the API, be sure to:
-
Name the event.
- Assign a target agent in the agentId parameter or Target Agent property of the Studio action. You can use the ID from the AgentId variable. This is automatically populated after the OnAnswer event. If you want to send a custom event before an agent is assigned, you must still supply an agent ID.
- Set the persistInMemory field. If the agent is logged out, this determines whether they will receive the event after logging back in.
- Populate the Data field, which is the payload as a string.
- Consume the custom event with the get-next-event API
or Get Next Event Studio action.
Below is an example of creating a custom event via API:
Example curl:
curl -X PUT "https://api-$AREA.$DOMAIN/incontactapi/services/v30.0/agents/$AGENT_ID/custom-event?eventName=From_Postman&persistInMemory=false&data=Sent_from_Postman"
Request Type: PUT
Fields:
Parameter | Type | Details |
---|---|---|
agentId | String | The agent ID value that identifies the target agent. |
eventName | String | The name of the event. This must be used by any consumers of the event. |
persistInMemory | Boolean | If the agent identified by agentId is not currently logged in, the event will either be ignored or remain for the agent once they log back in. |
data | String | Any string of data. |