CustomEvent

This help page is for CXone Studio. This information is also available for Desktop Studio.

A calendar with a checkmark in it.

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

A square with a line branching from it that goes to three other squares.

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

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.

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

  • Branches 2 & 3: Initiating and receiving a custom event after an agent answers the call.

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.