Skip to contentSkip to navigationSkip to topbar
On this page

Task Channel Definitions


Flex is a multichannel contact center. We support a number of channels out-of-the-box, and are constantly adding more. As of version 1.0 we support the following native channels:

  • Voice
  • SMS
  • WebChat with Media Attachments
  • Facebook Messenger
  • WhatsApp
  • RCS

With the Task Channel Definition API you can also add custom channels and override the behavior of existing ones.


Steps to add a custom channel

steps-to-add-a-custom-channel page anchor

To add a custom channel, you need to make changes in the following places:

  • Add a custom channel in TaskRouter
  • Trigger the custom channel to be routed to the agent
  • Define how the custom channel is rendered in the UI with Task Channel Definition API

Task Channel Definition API

task-channel-definition-api page anchor

All task channels that Flex UI handles are defined and registered by the Task Channels API. Flex registers its default Task Channel definitions (see below), but users and plugins can register their own. When task-based components are rendered, the first matching channel definition for a given task will be used. If there is more than one channel definition match for a task, then the most recently registered definition will be used. This allows you to register a more specific channel definition to override the behavior of a general one.

See below interface TaskChannelDefinition for what can be set up. All parameters are optional; the parameters from the Default task channel definition will be used if not specified. The most important property of a task channel definition is the isApplicable callback function. The callback receives a task as an argument and must return Boolean true if this definition can be used to handle the given task.

In a task channel definition you can specify:

  • callback to determine which tasks are applicable
  • strings (templates) to use in different Flex components based on task status
  • colors to be used in task list based on task status
  • icons to be shown in task list, tabs, and canvases based on task status
  • custom components to be added to task based components if channel is applicable
  • custom components to be replaced in task based components if channel is applicable

Predefined Task Channels definitions are available via Twilio.Flex.DefaultTaskChannels objects for reference. Channels that are defined by default:

  • Call - Twilio.Flex.DefaultTaskChannels.Call
  • Chat - Twilio.Flex.DefaultTaskChannels.Chat
  • Chat SMS - Twilio.Flex.DefaultTaskChannels.ChatSms
  • Chat Messenger - Twilio.Flex.DefaultTaskChannels.ChatMessenger
  • Chat WhatsApp - Twilio.Flex.DefaultTaskChannels.ChatWhatsApp
  • Default - Twilio.Flex.DefaultTaskChannels.Default
(warning)

Warning

It is not recommended to change Twilio.Flex.DefaultTaskChannels at runtime. You should create your own definition and register it instead.


Override Predefined Task Channels definitions Notifications

override-predefined-task-channels-definitions-notifications page anchor

Predefined Task Channels definitions are available via Twilio.Flex.DefaultTaskChannels and they can be altered with custom logic when required.


Override Default Chat Channel notifications

override-default-chat-channel-notifications page anchor

The example below demonstrates how you can define your own custom icon for browser notification of an IncomingTask with channel type Chat

1
const originalChatNotifications = Flex.DefaultTaskChannels.Chat.notifications.override.IncomingTask;
2
Flex.DefaultTaskChannels.Chat.notifications.override.IncomingTask = {
3
...originalChatNotifications,
4
options: {
5
...originalChatNotifications.options,
6
browser: {
7
...originalChatNotifications.options.browser,
8
options: {
9
...originalChatNotifications.options.browser.options,
10
icon: “CUSTOM_ICON_URL
11
}
12
}
13
}
14
};

Override Default Voice Channel notifications

override-default-voice-channel-notifications page anchor

The example below demonstrates how you can define your own custom icon for browser notification of an IncomingTask with channel type Voice

1
const overrides = Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask;
2
Flex.DefaultTaskChannels.Call.notifications.override.IncomingTask = (notification, cancel) => {
3
overrides(notification, cancel);
4
notification.options.browser.options.icon = CUSTOM_ICON_URL”;
5
};

Tasks can be rendered depending on which media type they support. We have helper functions to define custom channels that support the following media type:

  • Call - voice call based
  • Chat - messaging based like WebChat, SMS, Facebook Messenger, etc.
  • Generic - no media

Creating custom channel definitions with helper functions

creating-custom-channel-definitions-with-helper-functions page anchor

Flex has the following helper functions to create channel definitions with default values for chat, call, and generic.

Chat channel creation with default chat templates:

1
Flex.DefaultTaskChannels.createChatTaskChannel(name: string, isApplicable: TaskChannelApplicableCb,
2
icon: string | React.ReactNode = "Message", iconActive: string | React.ReactNode = "MessageBold", color: string = defaultChannelColors.chat): TaskChannelDefinition

Call channel creation with default templates:

Call channel definition uses callbacks to determine the icon and colors (based on call state and destination to render)

Flex.DefaultTaskChannels.createCallTaskChannel(name: string, isApplicable: TaskChannelApplicableCb): TaskChannelDefinition

Generic channel creation with default templates:

1
Flex.DefaultTaskChannels.createDefaultTaskChannel(name: string, isApplicable: TaskChannelApplicableCb,
2
icon: string | React.ReactNode = "GenericTask", iconActive: string | React.ReactNode = "GenericTaskBold", color: string = defaultChannelColors.custom): TaskChannelDefinition

Registering custom channels

registering-custom-channels page anchor

To register a task channel definition use:

Flex.TaskChannels.register(definition: TaskChannelDefinition, mergeWithDefaultChannel = true);

You must register your channel definitions before Flex finishes initializing.

For example:

1
const myOwnChatChannel = Flex.DefaultTaskChannels.createChatTaskChannel("myChat",
2
(task) => task.taskChannelUniqueName === "chat" && task.attributes.somethingSpecial === "myCustom");
3
// can modify myOwnChatChannel here
4
5
Flex.TaskChannels.register(myOwnChatChannel);

  • Flex.TaskChannels.unregister(myOwnChatChannel); - to unregister previously registered channel
  • Flex.TaskChannels.getRegistered(); - to get all registered task channels
  • Flex.TaskChannels.getForTask(task: ITask); - to get a matching task channel definition for a task

Complete TaskChannelDefinition Interface

complete-taskchanneldefinition-interface page anchor
1
export enum TaskChannelCapability {
2
Info = "Info", // whether channel has info panel
3
Call = "Call", // whether channel has call canvas capabilities
4
Chat = "Chat", // whether channel has chat canvas capabilities
5
Video = "Video", // whether channel has video calling capabilities
6
Wrapup = "Wrapup" // whether channel needs to go to Wrapup state before can be completed
7
}
8
9
export type TaskCallbackType<T> = (
10
task: ITask,
11
componentType: React.ComponentType,
12
...args: Array<any>
13
) => T;
14
export type TaskStatusBasedTypeBase<T> = {
15
Reserved?: T;
16
Assigned?: T;
17
Wrapping?: T;
18
Completed?: T;
19
Canceled?: T;
20
Pending?: T;
21
};
22
export type TaskStatusBasedType<T = string> =
23
| T
24
| TaskCallbackType<T>
25
| TaskStatusBasedTypeBase<T>;
26
export type TaskChannelApplicableCb = (task: ITask) => boolean;
27
28
export type TaskChannelComponentRegistration = {
29
target: keyof FlexComponents;
30
component: React.ReactChild;
31
options?: ContentFragmentProps;
32
};
33
34
export type TaskChannelComponentRemoveRequest = {
35
target: keyof FlexComponents;
36
key: React.Key;
37
options?: RemoveComponentCallOptions;
38
};
39
40
/**
41
* Defines a task channel
42
*
43
* @export
44
* @interface TaskChannelDefinition
45
*/
46
export interface TaskChannelDefinition {
47
// for internal usage, will be set to an array of callbacks to invoke to unregister custom components
48
_registrationCallbacks?: Array<Function>;
49
50
name: string;
51
52
/**
53
* Used in TaskList, TaskCard, Canvases
54
*/
55
colors?: {
56
main?: TaskStatusBasedType<string>;
57
};
58
59
/**
60
* Returns whether this task channel is applicable for a given task.
61
* @param task task instance to evaluate the channel for
62
*/
63
isApplicable: TaskChannelApplicableCb;
64
65
/**
66
* Icons to render to the task channel
67
*/
68
icons?: {
69
/**
70
* List icon to be used in TaskList and TaskCardList
71
*/
72
list?: TaskStatusBasedType<string | React.ReactNode>;
73
/**
74
* Icon to be used in Tab headers if tab is not selected
75
*/
76
main?: TaskStatusBasedType<string | React.ReactNode>;
77
/**
78
* Icon to be used in Tab headers if tab is selected and in Task Canvases as the main icon
79
*/
80
active?: TaskStatusBasedType<string | React.ReactNode>;
81
};
82
83
/**
84
* Templates for components
85
*/
86
templates?: {
87
IncomingTaskCanvas?: {
88
firstLine?: TaskStatusBasedType<string>;
89
secondLine?: TaskStatusBasedType<string>;
90
};
91
CallCanvas?: {
92
firstLine?: TaskStatusBasedType<string>;
93
secondLine?: TaskStatusBasedType<string>;
94
};
95
TaskListItem?: {
96
firstLine?: TaskStatusBasedType<string>;
97
secondLine?: TaskStatusBasedType<string>;
98
extraInfo?: TaskStatusBasedType<string>;
99
};
100
TaskCanvasHeader?: {
101
title?: TaskStatusBasedType<string>;
102
endButton?: TaskStatusBasedType<string>;
103
};
104
TaskCard?: {
105
firstLine?: TaskStatusBasedType<string>;
106
secondLine?: TaskStatusBasedType<string>;
107
};
108
TaskInfoPanel?: {
109
content: TaskStatusBasedType<string>;
110
};
111
Supervisor?: {
112
TaskCanvasHeader?: {
113
title?: TaskStatusBasedType<string>;
114
endButton?: TaskStatusBasedType<string>;
115
};
116
TaskInfoPanel?: {
117
content: TaskStatusBasedType<string>;
118
};
119
TaskOverviewCanvas: {
120
firstLine?: TaskStatusBasedType<string>;
121
secondLine?: TaskStatusBasedType<string>;
122
};
123
};
124
};
125
126
/**
127
* Set of capabilities, used to render Tabs
128
*/
129
capabilities: Set<TaskChannelCapability>;
130
131
/**
132
* Character limit of a message.
133
*/
134
charLimit: number;
135
136
/**
137
* Custom components to be added for this task channel. E.g. custom Tabs.
138
* Supports only components that have a static "Content" property
139
*/
140
addedComponents?: Array<TaskChannelComponentRegistration>;
141
142
/**
143
* Custom components to be replaced for this task channel.
144
* Supports only components that have a static "Content" property
145
*/
146
replacedComponents?: Array<TaskChannelComponentRegistration>;
147
148
/**
149
* Custom components to be removed for this task channel
150
*/
151
removedComponents?: Array<TaskChannelComponentRemoveRequest>;
152
153
/**
154
* Custom component props to be passed in if we have a matching task channel.
155
* Works only for task based components.
156
*/
157
// componentProps?: {
158
// [K in keyof FlexComponents]?: any;
159
// };
160
}

Adding a Tab to custom channel

1
MyCallChannel.addedComponents = [
2
{
3
target: "TaskCanvasTabs",
4
component: <MyTab
5
key="myTab"
6
icon={<img src="https://someimage.png" />}
7
iconActive={<img src="someimage.png" />}
8
/>
9
}
10
];

Replacing a component (e.g. TaskInfoPanel or MessagingCanvas)

1
const MyComponent = <div key="X">My Call Task Info Panel</div>;
2
MyCallChannel.replacedComponents = [
3
{ component: MyComponent, target: "TaskInfoPanel" }
4
];

Replacing a component conditionally

1
MyCallChannel.replacedComponents = [
2
{ component: MyComponent, target: "MessagingCanvas", options:
3
{ if: (props) => props.task.status === "wrapping" }
4
}
5
];

Change strings based on task types (e.g., for end task button in the header):

1
myOwnChatChannel.templates.TaskCanvasHeader.endButton = {
2
Assigned: "End Task",
3
Reserved: undefined,
4
Wrapping: "Wrap up",
5
Completed: "Template1",
6
Canceled: "Template2",
7
Pending: "Template3"
8
};

Removing a component conditionally (e.g., remove action button from TaskListItem if task is in state "wrapping")

1
Flex.DefaultTaskChannels.Call.removedComponents = [{
2
target: "TaskCanvasHeader",
3
key: "actions",
4
options: {
5
if: (props) => props.task.status === "wrapping"
6
}
7
}];

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.