There are a number of use cases around specifically initiating outbound WhatsApp from Flex - that are not off-the-shelf capabilities within the Flex UI. Since the Flex UI reacts to Tasks, these typically originate from an inbound message coming in from the customer - at which point an agent can converse with the customer via the Flex Chat UI interface. Sometimes though, we (the agent, CRM, or external system) need to be the initiators of the WhatsApp conversation.
This plugin provides support for initiating outbound Whatsapp tasks as an agent.
This plugin enables a front-end dialog screen allowing an agent to enter a phone number (international E-164 format) and create a new task for himself. Since WhatsApp has limitations around the types of messages that are allowed in an outbound use case, the plugin also enable a drop-down list with pre-defined messages to initiate the conversation. To support the task creation, the following Twilio Function was added:
- create-wa-task.js: This Twilio Function is called when the agent clicks in Create Task. It receives the destination number and also the worker identity, so the task can be created only for them. For security reasons, it only accepts calls from within Flex
To deploy this plugin, you will need:
-
An active Twilio account with Flex provisioned. Refer to the Flex Quickstart to create one.
-
WhatsApp set up as a channel on flex. Refer to the WhatsApp in Flex article to learn how to do it.
-
npm version 5.0.0 or 6 installed (type
npm -vin your terminal to check) -
Node version 10.12.0 or later installed (type
node -vin your terminal to check) -
A mobile device with WhatsApp installed
-
Twilio CLI along with the Flex CLI Plugin and the Serverless Plugin. * Run the following commands to install them:
# Install the Twilio CLI npm install twilio-cli -g # Install the Serverless and Flex as Plugins twilio plugins:install @twilio-labs/plugin-serverless twilio plugins:install @twilio-labs/plugin-flex@beta- The Twilio CLI with the Serverless and Flex Plugins are recommended for local development and debugging purposes, but you have the option to use the Functions UI in the Twilio Console.
Before we begin, we need to collect all the config values we need to run the plugin on your Flex application:
| Config Value | Description |
|---|---|
| Account Sid | Your primary Twilio account identifier - find this on the Console Dashboard. |
| Auth Token | Your Twilio Auth Token, which acts as your password - find this on the Console Dashboard. |
| Chat Service SID | Unique identifier for your Flex Chat Service. You can find this on the Programmable Chat Dashboard. |
| Twilio WhatsApp Number | The WhatsApp number to use when sending messages to a WhatsApp recipient. You can find this either on the Twilio Sandbox for WhatsApp page if you're using a test number, or the WhatsApp Senders if you've enabled personalized WhatsApp numbers. |
| Proxy Service SID | Unique identifier for a Flex Proxy Service. You can check this in the Proxy Dashboard. |
| TaskRouter Agent Available Activity SID | The unique identifier for the Agent Available Activity. Used to set the agent activity as online when creating the Outbound Task. You can find this in TaskRouter Dashboard, by accessing your Flex Workspace, then Activities |
| TaskRouter Workspace SID | Your Flex Workspace automatically created for routing purposes. Obtainable here. |
| Chat Channel SID | The unique identifier for the Chat Task Channel. You can fin this in the TaskRouter Dashboard, then Task Channels |
After the above requirements have been met:
-
Clone this repository
git clone REPO_URL -
Deploy your Twilio function
cd serverless
? Copy the Environment Variables example file to .env
cp .env.example .env
? Fill the .env file with your environment variables
twilio serverless:deploy
- Deploy your Twilio Plugin
cd ..
? Copy the Environment Variables example file to .env
cp .env.example .env
? Fill the .env file with your TaskRouter Activity SID and the Twilio Serverless Domain obtained after Function deployment
? Install dependencies
npm install
? Copy appConfig file to your production file
cp public/appConfig.example.js public/appConfig.js
twilio flex:plugins:deploy --major --changelog "Changelog here"
To test the plugin locally, run the following command:
twilio flex:plugins:startNavigate to http://localhost:3000.
That's it!
If you need to deliver the created task to a specific agent (i.e. most likely the agent who performed the action that initiated the SMS task being created), then you will have included their worker SID in the targetWorkerSid parameter of your function REST API call.
To complete the necessary workflow routing, you can add a filter to your Workflow to look for this task attribute, and act upon it using Known Agent Routing. See example filter below.
A new Flex Flow is needed in order to create a Whatsapp task without the need of a Studio flow. Luckily, Flex allows you to keep two Flows, one with Studio and other with Task as the integrationType. Execute the API call below in order to create your new flex Flow
curl -X POST \
https://flex-api.twilio.com/v1/FlexFlows \
--data-urlencode "ChannelType=whatsapp" \
--data-urlencode "IntegrationType=task" \
--data-urlencode "Enabled=false" \
--data-urlencode "FriendlyName=Flex WhatsApp To Task Flow" \
--data-urlencode "ContactIdentity=+1888XXXXXXX" \
--data-urlencode "ChatServiceSid=ISXXXXXX" \
--data-urlencode "Integration.WorkspaceSid=WSXXXXXX" \
--data-urlencode "Integration.WorkflowSid=WWXXXXXX" \
--data-urlencode "Integration.Channel=TCXXXXXX \
--data-urlencode "LongLived=false" \
--data-urlencode "JanitorEnabled=true" \
-u ACXXXXXX:XXXXXXX
IMPORTANT: You must keep this flow disabled, or Flex will find a conflict. The flow is still going to work for that purpose.
Due to WhatsApp limitations when proactively contacting end users, it is best for agents to send the first message by using a pre-defined message using the Canned Responses component included in this plugin. There are two important steps to register new WhatsApp templates
You can follow our official documentation to better understand how to register new WhatsApp Templates
The Canned Responses component was created using a static MenuList, so in order to make your template available for agents you will need to change the src/components/CannedResponses/CannedResponses.jsx file, by adding a new MenuItem to the render method, like the example below:
render() {
return (
/* Rendering canned responses. This is an example in which templates are hard-coded. They can be dynamic using Twilio Sync */
<CannedResponsesStyles>
<FormControl className="form">
<InputLabel className="input-label" htmlFor="response">Canned Responses</InputLabel>
<Select
value={this.state.response}
onChange={this.handleChange}
name="response"
>
<MenuItem value="Hello! We're reaching out to talk to you about your request. Please reply with YES to talk to one of our agents.">Greeting</MenuItem>
<MenuItem value={`Hello. I'm ${this.manager.workerClient.attributes.full_name} and I'm responsible for your request with us. Please reply with YES to engage in a conversation with us.`}>Personal Greeting</MenuItem>
<MenuItem value="This is my third canned response.">Canned Response 3</MenuItem>
</Select>
</FormControl>
</CannedResponsesStyles>
)
}
};IMPORTANT: Remember to replace the placeholders for actual variables in your code. In the example above, we're replacing it for the agent's full name.
Run twilio flex:plugins --help to see all the commands we currently support. For further details on Flex Plugins refer to our documentation on the Twilio Docs page.
Check out CONTRIBUTING for more information on how to contribute to this project.
MIT © Twilio Inc.
This plugin was based on the function-flex-outbound-sms and the plugin-agent-autoresponse. Many thanks to the original contributors:
No warranty expressed or implied. Software is as is.