
Hi Questetra users! I’m Hatanaka, Questetra’s CTO.
Today, I would like to try making a phone call automatically in the middle of a Workflow by using one of the new functions in v11.7, the Receive Task (Webhook), so that the content of the HTTP response can be configured in combination with Twilio.
v11.7 2018-06-11 Equipped the Open Form that Receives Entry in the Middle of Workflow
With the development of email and SNS, opportunities to make standard phone calls have decreased. Still, telephones are important in cases of emergency contact.
I suppose a phone call is superior in that it is immediate and you can request the reaction of the other person. Telephones are still serving as a notification function.
Now, I am going to create a simple Workflow App for making a phone call in the middle of a Workflow.
But before that I will explain about Twilio and the API for making phone calls.
Twilio is a cloud service that supports phone-related communication such as phone calls, SMS, video calls, etc. By utilizing Twilio’s API you can incorporate phone calls and other functions into the computer system.
This time, I will use Twilio’s Voice API Call.
It will be acieved by the following two steps.
- Send a POST request to the Twilio API and send a phone call instruction conveying your Twilio account and the call destination number. At this point the call content is not included.
- When the call is connected, there will be a callback HTTP request from Twilio for a specific URL. In response to the request, return the content to be spoken in XML (referred to as TwiML). A URL for a callback is specified when requesting 1 above.
Now, we go back to the Workflow App; here is the diagram.
As a rough outline, the process goes as follows:
- At the Input Step enter destination phone number and call contents.
- Using the AND gateway, split the flow in two. The upper flow goes to the Voice API Call which is in step 1 mentioned earlier. The lower flow corresponds to step 2. Therefore, as for the actual processing, the upper flow is done first and the lower flow is done later.
- In the Service Task (Data assignment) the callback URL is generated. The callback URL is the URL of the Receive Task (Webhook) in 5 below.
- At the Throwing Message Intermediate Event (HTTP), the request to Twilio’s API is executed. At this point, the outgoing call is done via Twilio.
- When the phone is connected there is a callback from Twilio to the Receive Task (Webhook). The Receive Task (Webhook) returns the call contents to Twilio, and Twilio relays the contents to the recipient.
Next, the Data Items must be configured. I won’t use “Title”.
For users there are only two we will use, “Phone number” and “Call Contents”.
“API Key” is used in the Receive Task (Webhook), and “callback url” is used to temporarily hold the URL of the Receive Task (Webhook).
Data Item Name | Data-type | Required | Permission at “Input” Step |
---|---|---|---|
Title | – | No | Editable |
Phone number | String-type single line | Yes | Editable |
Call Contents | String-type multiple lines | Yes | Editable |
API Key | String-type single line | No | Only display |
Initial value #{#randomString(20)} |
|||
callback url | String-type single line | No | Only display |
Next, we will set up the Service Task (Data assignment), which generates the URL of the Receive Task (Webhook).
#{data['1']}
retrieves the value of “API Key”.
Data Item | callback url |
---|---|
Value or Expression | |
https://XXXXXXXX.questetra.net/System/ReceiveTask/Http/1234/5/#{processInstanceId}/#{data['1']}/receive |
Next, let’s look at the settings of the Throwing Message Intermediate Event (HTTP), which accesses Twilio’s API for outgoing phone calls.
Before doing this I will show you a list of variables used in the App.
Variable | Value |
---|---|
AccountSID | Account ID of Twilio |
AuthToken | token used for accessing the API, a bit like a password. |
PhoneNumber | The phone number that will be called. Purchased from Twilio. Designated in international call format. |
Since I will use Twilio, I need an account in Twilio.
After acquiring the Twilio account and logging in, I can check on the dashboard right after logging in.
- Account SID
- AUTHTOKEN
You can confirm the value of AUTHTOKEN by clicking on “View”.
For calling phone numbers, go to “Phones” under “All Products & Services” in the side menu and buy a phone number from there. What you can do depends on the telephone number, but in the case of Japanese telephone numbers I think that they all have voice calls and fax. Please purchase a number that can make voice calls.
As Twilio is a global service, you need to specify the phone number in the international phone format. If you purchased a Japanese phone number, for example, it must start with +81.
Now, we will look at the settings of the Throwing Message Intermediate Event (HTTP), which accesses Twilio’s Voice API Call.
Access URL | https://api.twilio.com/2010-04-01/Accounts/${var[AccountSID]}/Calls.json |
---|---|
HTTP Method | POST (application/x-www-form-urlencoded) |
Security | Connect with Basic Authentication |
User name | ${var[AccountSID]} |
Password | ${var[AuthToken]} |
The Send parameters are as follows.
Parameter name | Value |
---|---|
From | ${var[PhoneNumber]} |
To | “Phone number” |
Url | 「callback url」 |
Finally, here are the settings of the Receive Task (Webhook), which returns the call contents to the Twilio callback.
#{data['3']}
retrieves the value of “Contents of talk”. XML escaping is done with #escapeXml()
.
String-type data item with the API key | API Key |
---|---|
Method of receiving HTTP request | POST |
Content Type of HTTP request | application/x-www-form-urlencoded |
String-type data item that will save the request body | |
Content Type of HTTP response | text/xml;charset=UTF-8 |
Body of HTTP response | |
<?xml version="1.0" encoding="UTF-8"?> <Response> <Say voice="alice" language="ja-JP" loop="3">#{#escapeXml(data['3'])}</Say> </Response> |
The call content is following the XML format referred to as TwiML.
<Say>
is a tag that narrates the containing text. There are other tags such as <Play>
which plays audio files. voice
specifies the type of voice, and language
specifies the language respectively. loop
specifies the number of automatic repetitions.
That is all for the settings.
One final note.
Since Twilio is a global service, you need to specify phone numbers in the international telephone format.
Phone numbers to be entered at the Input Step must be specified, for example in Japan, beginning with +81.
Pingback: Phone Number Verification through Web Form Application – Questetra Support
Pingback: Examples of Collaborations with Other Systems and BPM Workflow (June, 2019) – QUESTETRA BPM SUITE