HI, Questetra users! I’m HATANAKA, Questetra CTO.

Today, I would like to realize Making a phone call automatically in the middle of the Workflow by using the new function of v11.7, ‘Receive Task (Webhook): Correspond so that content of HTTP response can be configured’ and Twilio in combination.

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 plain calls have decreased. Yet, telephone is still important in cases of emergency contact.

I suppose it is superior in that immediacy is high and that you can request the reaction of the opponent. 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 in advance to that, I will explain about Twilio and “API for making phone calls”.

https://www.twilio.com/

Twilio is a cloud service that supports phone-related communication such as telephone, SMS, video phone. By utilizing Twilio’s API, you can incorporate phone and other functions into the computer system.

This time, I use “Voice API Call” among the APIs of Twilio.

Twilio Voice API Call

It will be realized by the following two steps.

  1. Send a POST request to the Twilio API and send a “Phone Call” instruction. Conveying Twilio account and the call destination number. At this point, the content to talk is not included.
  2. When the phone is connected, there is an HTTP request of callback 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.

In a rough outline, the processing goes as the following.

  1. At the Step of “Input”, enter “Destination phone number” and “Contents of talk”
  2. Using AND gateway, split the flow in two. the upper flow goes to “Voice API Call” which is the step 1 I mentioned earlier. The lower flow corresponds to the step 2. Therefore, as for the flow of actual processing “upper flow” is done first and “lower flow” is done later.
  3. In the Service Task (Data assignment) the callback URL is calculated. The callback URL is the URL of Receive Task (Webhook) in 5 below.
  4. 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.
  5. When the phone is connected, there is a callback from Twilio to the Receive Task (Webhook). The Receive Task (Webhook) returns the Contents of talk to Twilio. Twilio speaks the contents to the callee.

Next, Data Items. I won’t use “Title”.
For humans, there are only two, “Phone number” and “Contents of talk”.
“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 Type Required Permission at “Input” Step
Title No Editable
Phone number String type single line Yes Editable
Contents of talk 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, the settings of Service Task (Data assignment). It calculates the URL of 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, the settings of Throwing Message Intermediate Event (HTTP). It accesses to Twilio’s API for outgoing a phone call.
Before doing it, I will show you a list of variables used in the App.

Variable Value
AccountSID Account ID of Twilio
AuthToken token used for accessing API. Something like a password.
PhoneNumber The phone number to call. Those 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

  • Account SID
  • AUTHTOKEN

on the dashboard right after logging in. You can confirm the value of AUTHTOKEN by clicking on “View”.


Regarding the calling phone number, you move to “Phones” from “All Products & Services” in the side menu and there buy a phone number. The things that can be done are different depending telephone number, but in the case of Japanese telephone number, I think that they all have the functions of voice call (VOICE) and fax. Please purchase a number that can make a voice call.

As Twilio is a global service, so you need to specify the phone number in international phone format. If you purchased a Japanese phone number, for example, specify it starting with “+ 81”.

Now, the settings of Throwing Message Intermediate Event (HTTP). It accesses Twilio 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, settings of Receive Task (Webhook). It returns “Contents of talk” against callback from Twilio.
#{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 Contents of talk is following the XML format referred as TwiML.

TwiML for Programmable Voice

<Say> is the tags that narrate the texts of in between. There are other tags such as <Play> which is playing audio files. The elements voice specifies the type of voice, language specifies the language respectively. loop specifies the number of repetitions of auto reading.

That is all, for the settings.

One caution to tell for the ending.
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, begin with “+81”.