CustomEvent

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.

Dependencies

This action is found on the API Actions palette.

Supported Script Types

Generic	Email	Chat	Phone	Voicemail	Work Item	SMS	Digital

Input Properties

These properties define data that the action uses when executing.

Property	Description
Add Caption	Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon.
Target Agent	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.
Event Name	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

Some actions in this example script may not yet be available in CXone Studio.

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.

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.