Menu

Actions Framework

The Flex UI is constantly emitting event data that describes how the user is interacting with the Flex UI. As you write Plugins, the Actions Framework allows you to harness these events and define your own logic to describe how you want the Flex UI, CRM Data, or any other data, to change. You can register events before or after an action fires, or even replace the behavior of an Action!

Auto-Generated Documentation for the Flex UI is now available as a beta distribution. The auto-generated documentation is accurate and comprehensive, and so may differ from what you see in the official Flex UI documentation.

Register and Invoke an Action

Actions.registerAction(name: string, action: ActionFunction, payloadUpdate?: PayloadUpdateFunction)

Registers a named action and provides the code that should be run when invoking it. The payloadUpdate method is optional, and used for triggering a callback to modify the payload given to action invocation.

Actions.invokeAction(name: string)

Invokes a named action. Returns a Promise.

Actions.addListener(name: string, action: ActionFunction)

Implements a custom function to be triggered either Before or After specific Action.

Add and Remove Event Listeners

You can add and remove event listeners.

Events supported:

before[eventName] (for example "beforeAcceptTask")
Called when a named action is triggered but before the action body is run. You can abort the action that is provided with event body.

after[eventName]
Called after the action has stopped executing.

Replace an Action

Actions.replaceAction(name: string, action: ReplacedActionFunction)

Replaces the default implementation of a named action and provides an alternative implementation. The replaced action will be called with the same parameters as the original implementation, so you can add additional logic, then invoke the original action in your replacement function.

Common use cases and examples

Add an Action after a Task is accepted

Raises a javascript alert after an Agent has clicked to accept any task.

flex.Actions.addListener("afterAcceptTask", (payload) => alert("Triggered after event AcceptTask"));

Ask for confirmation before accepting a Task

Generates a prompt before Task Acceptance; prevent that Action from running with an abort command if the user doesn't confirm.

flex.Actions.addListener("beforeAcceptTask", (payload, abortFunction) => {
    alert("Triggered before event AcceptTask");
        if (!window.confirm("Are you sure you want to accept the task?")) {
            abortFunction();
        }
});

Customizing an Existing Action

Replaces the original Action for AcceptTask. Injects custom logic to alert about the replacement, but executes the original Action.

flex.Actions.replaceAction("AcceptTask", (payload, original) => {
    return new Promise<void>((resolve, reject) => {
        alert("I have replaced this Action");
        resolve();
    }).then(() => original(payload));
});

Registering a Custom Action

Registers a custom Action called MyAction, which makes a HTTP request. We then add a listener to the action CompleteTask which then invokes this custom Action. For example this could be used to update your CRM system.

flex.Actions.registerAction("MyAction", (payload) => {
    return 
        fetch("https://my.server.backend.com/test")
        .then(response => {
            alert("Triggered MyAction with response " + JSON.stringify(response));
        })
        .catch(error => {
            console.log(error);
            throw error;
        });       
});


flex.Actions.addListener("afterCompleteTask", (payload) => {return flex.Actions.invokeAction("MyAction")});

Sending a message after a Task is completed

Sends a post-conversation message once the task is in a wrap-up state. Could be used to send a survey, or notify a user that the agent closed the session.

flex.Actions.replaceAction("WrapupTask", (payload, original) => {
    // Only alter chat tasks:
    if( payload.task.taskChannelUniqueName !== "chat" ) {
        original(payload);
    } else {
        return new Promise(function(resolve, reject) {
          // Send the message:
          flex.Actions.invokeAction("SendMessage", {
            body: 'Thanks for chatting. Your session is now closed.',
            channelSid: payload.task.attributes.channelSid
          }).then(response => {
            // Wait until the message is sent to wrap-up the task:
            resolve(original(payload));
        });
    });
}

List of Actions

The following Actions are currently supported.

Voice

  • ToggleMute - mutes current call (if one exists).
  • HangupCall - payload: {task?: ITask, sid?: string} - hangs up current call (if one exists).
  • HoldCall - payload: {task?: ITask, sid?: string, holdCallMusicUrl?: string} - holds current call (if one exists).
  • UnholdCall - payload: {task?: ITask, sid?: string} - unholds current call (if one exists).
  • StartOutboundCall - payload: {destination?: string, queueSid?: string, callerId?: string, taskAttributes?: object} - places an outbound call
    • destination: the destination phone number to make the outbound call; required
    • queueSid: assigns the task to a specific queue; optional
    • callerId: defines the number that appears on the users device for the call; optional
    • taskAttributes; custom attributes for the Task; optional

Chat

  • SendMessage - payload: {channel?: ChannelState, channelSid?: string, body: string, messageAttributes?: any} - sends message with body to channel defined by ChannelState.
  • SetInputText - payload: {channel?: ChannelState, channelSid?: string, body: string} - sets message edit field to body in chat UI for channel ChannelState.
  • SendTyping - payload: {channel?: ChannelState, channelSid?: string} - sends typing indicator execution to other party in the channel.

All above Actions need either channel or channelSid parameter.

Agent

  • SelectTask - payload: {task?: Task, sid?: string} - selects task in the task list. Also called when user clicks the task manually.
  • AcceptTask - payload: {task?: Task, sid?: string} - agent accepts the task.
  • RejectTask - payload: {task?: Task, sid?: string} - agent rejects the task.
  • CompleteTask - payload: {task?: Task, sid?: string} - completes a task that is either pending or assigned. Called from UI by the Complete Task button. If applicable, will result in WrapupTask action being called.
  • WrapupTask - payload: {task?: Task, sid?: string} - wraps up the task if applicable.
  • SetActivity - payload: {activityAvailable?: boolean, activityName?: string, activitySid?: string, rejectPendingReservations?: boolean} - sets Activity of the user. Called by UI when selecting activity from Profile widget.
  • ShowDirectory - displays workers directory at the agent desktop view.
  • HideDirectory - hides workers directory at the agent desktop view.
  • TransferTask - payload: {task?: ITask; sid?: string; targetSid: string; options?: any;} - transfer a provided task to a target worker. Called by UI when a task is transfered via Worker Directory.
    • task?: ITask; // task to be transferred (either this or next one needed)
    • sid?: string; // sid of the task to be transferred
    • targetSid: string; // sid of the worker or queue to be transferred to
    • options?: any; // TransferOptions as defined in the TaskRouter SDK
  • CancelTransfer - payload:{task?: ITask, sid?: string;} - cancel a task that was being transferred to a target worker.
    • task?: ITask; // task to be transferred (either this or next one needed)
    • sid?: string; // sid of the task to be transferred
  • KickParticipant - payload: {targetSid?: string; participant?: ConferenceParticipant;} - remove a participant from a call
    • targetSid?: string; // sid of the participant (either this or participant has to be provided
    • participant?: ConferenceParticipant; // participant object
  • HoldParticipant - payload: {targetSid?: string; participant?: ConferenceParticipant;} - put a call participant on hold
    • targetSid?: string; // sid of the participant (either this or participant has to be provided
    • participant?: ConferenceParticipant; // participant object
  • Logout - payload: {forceLogout?: boolean, activityName?: string, activitySid?: string} - try to logout user from current session if there are no current activities preventing it.
  • ToggleDTMFDialpad - payload: {task: ITask; open?: boolean;} - used to explicitly open or close DTMF dialpad.
  • SetDTMFDialpadDigits - payload:{task: ITask; digits: string;} - used to set digits in the DTMF dialpad

Supervisor

  • MonitorCall - payload: {task?: ITask, sid?: string, extraParams?: any} - monitor a provided ongoing call of another agent. Invoked from a Supervisor UI at Task Overview pane.
  • StopMonitoringCall - payload: {task?: ITask, sid?: string} - stop monitoring a call.
  • SelectTaskInSupervisor - payload: {task?: ITask, sid?: string} - select a task in Supervisor UI. Deselect a current task if provided task is undefined.
  • SelectWorkerInSupervisor - payload: {worker?: IWorker, workerSid?: string} - select an agent in Supervisor UI. Deselect a current worker if worker is undefined.
  • SetWorkerActivity - payload: {workerSid: string, activitySid: string} - update an agent's activity

General

  • NavigateToView - payload: {viewName: string} - navigates user to a view defined by the provided view name.
  • HistoryPush - URL path or payload: {pathname: string, search: string, hash: string, state: {[key: string]: any}} - adds a history entry, leading to view change or redirect.
  • HistoryReplace - URL path or payload: {pathname: string, search: string, hash: string, state: {[key: string]: any}} - adds a history entry, leading to view change or redirect.
  • HistoryGo - integer - goes to a specific history entry, identified by its relative position to the current page (with the current page being relative index 0).
  • HistoryGoBack - goes back to the previous history entry.
  • HistoryGoForward - goes forward to the next history entry.
  • ToggleSidebar - payload: {open: boolean} - opens or closes the sidebar.
  • SetComponentState - payload: {name: string, state: any} - alters the current state of a component. Component states is a componentName => key/value pairs dictionary in Redux store that this action manipulates. Payload is defined as name is the name of the component and state is an Javascript object. The Action will update the state in the store under name by shallow merging state with current state. Developers can use this action and this state to both control native Flex controls and also keep a convenient state for their own components. Natively currently two controls are supported ("AgentTaskCanvasTabs", "SupervisorCanvasTabs") with one state value selectedTabName that holds the uniqueNameof currently selected tab of the respective tab controls.

Using SetComponentState

Flex.Actions.invokeAction("SetComponentState", { name: "AgentTaskCanvasTabs", state: { selectedTabName: "info" } });
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.