2023年5月1日を持ちまして、株式会社KDDIウェブコミュニケーションズのTwilioリセール事業が終了したため、本記事に記載されている内容は正確ではないことを予めご了承ください。

はじめに

みなさん、こんにちは。
KDDIウェブコミュニケーションズのTwilio事業部エバンジェリストの高橋です。

2020/4/30（日本時間だと2020/5/1）、Twilio Studioに関して大きなアップデートが発表されました。

これにより、Twilio StudioのREST APIがv2にアップデートされ、APIベースでStudioフローの作成や更新ができるようになりました。

ではさっそく、どのようなことができるのかを確認してみましょう。

StudioのAPIってどういうこと？

Twilio Studioは皆さんご存知ですよね。
まぁ、この記事を読んでいる方であれば、何度か触ったことがあるかと思います。
簡単にいえば、ドラッグアンドドロップでコールフローやメッセージフローが作れるツールで、エンジニアでなくても電話やSMSを簡単に扱えるところが大きな特長です。

そんなノンプログラミングツールとしてのStudioですが、なぜAPIが必要なのでしょうか。
実は、非エンジニアにとってはとても便利なStudioなのですが、エンジニアにとってはフローのメンテナンスをすべて管理コンソールで行わなくてはならないのが逆に面倒だったりします。

Studioは元々、フローデータをJSON形式で書き出したり、それを読み込んで新しいフローを作ることができました。しかしこれらの作業はすべて管理コンソールから行う必要があり、CI/CDツールとの連携などができないなど、使いづらかったのも事実です。

今回のアップデートにより、JSONの書き出しや更新、さらにはバージョン管理機能のAPIが追加されたので、もう管理コンソールを使わないでもTwilio Studioを自由に扱うことができるようになったのです。

やってみよう

以下の作業の前に、Twilio CLI（Version2.0.1以降）をインストールしておきます。
バージョンは以下のコマンドで確認できます。

% twilio -v
twilio-cli/2.0.1 darwin-x64 node-v10.8.0

フローの新規作成

今回作成するフローのJSONは以下の通りです。
Twilio CLIが使える場所にdefinition.jsonという名前で保存してください。

definition.json

{
  "states": [
    {
      "transitions": [
        {
          "event": "incomingMessage"
        },
        {
          "event": "incomingCall",
          "next": "SayHello"
        },
        {
          "event": "incomingRequest"
        }
      ],
      "type": "trigger",
      "name": "Trigger",
      "properties": {
        "offset": {
          "y": 0,
          "x": 0
        }
      }
    },
    {
      "transitions": [
        {
          "event": "audioComplete"
        }
      ],
      "type": "say-play",
      "name": "SayHello",
      "properties": {
        "say": "こんにちは、世界！",
        "voice": "alice",
        "language": "ja-JP",
        "loop": 1,
        "offset": {
          "y": 240,
          "x": -140
        }
      }
    }
  ],
  "initial_state": "Trigger",
  "flags": {
    "allow_concurrent_calls": true
  },
  "description": "Hello World"
}

これは、着信があると「こんにちは、世界！」と女性の声が流れるフローです。すでにStudioをお使いの方であれば想像がつくかと思いますが、TriggerウィジェットのIncoming Callに、Say/Playウィジェットが１つだけつながっているものです。

では、このJSONファイルをアップロードしてみましょう。
アップロードは以下のコマンドで行います。

% twilio api:studio:v2:flows:create \
--friendly-name 'Hello World' \
--status published \
--definition "`cat definition.json`"

--definitionのパラメータを使って、先程保存したJSONファイルを読み込ませています（catコマンドはバックスラッシュで囲むところを気をつけてください）。
コマンドが成功すると、以下のような応答が返ります。

SID                                 Friendly Name  Status     Revision
FWabe889fbe1650134e76508f2315877a4  Hello World    published  1

では、実際に作成されたフローを管理コンソールで確認してみましょう。

どうやらちゃんとできているようです。中身も確認してみましょう。

ちゃんとできていますね。

既存のフローをダウンロードする

JSONファイルを作れば、フローが新規で作成できることはわかりましたが、JSONファイルをスクラッチで作るのは大変です。管理コンソールを使えば、フローをJSONにエクスポートすることもできます（TriggerウィジェットのShow Flow JSONボタンを押す）が、Studio API V2では、エクスポートもAPIで実行できます。

では、先程新規作成したフローデータをダウンロードしてみます。ダウンロードするためにはフローのSIDが必要なので、まずはそれを調べるAPIを使います。

% twilio api:studio:v2:flows:list

既存のフローのリストが返ります。

SID                                 Friendly Name       Status     Revision
FWabe889fbe1650134e76508f2315877a4  Hello World         published  1

では、このフローデータの定義部分だけをJSONファイルとしてダウンロードしてみます。
このコマンドを実行するためには、jqコマンドがインストールされている必要があります（Macユーザであれば、brew install jqでインストールできます）。

% twilio api:studio:v2:flows:fetch \
--sid FWabe889fbe1650134e76508f2315877a4 \
-o json | jq '.[0].definition' > hello-world.json

--sidに、先程調べたフローのSIDを指定します。
-o jsonは、出力結果をJSONファイルとして表示させるためのものです。
フローデータのJSONには、定義情報以外も含まれているため、定義情報だけを抜き出すのが、jq '.[0].definition'です。
最後にそれをhello-world.jsonに書き出しています。

できあがったhello-world.jsonは、先程と同じJSONファイルです。

フローデータを更新する

では今度は、既存のフローデータを更新してみましょう。
今ダウンロードしたhello-world.jsonをエディタで開き、こんにちは、世界の部分を別の文字列に変更して保存します。

hello-world.json（一部抜粋）

    {
      "transitions": [
        {
          "event": "audioComplete"
        }
      ],
      "type": "say-play",
      "name": "SayHello",
      "properties": {
        "say": "ようこそ、スタジオバージョン２へ！",
        "voice": "alice",
        "language": "ja-JP",
        "loop": 1,
        "offset": {
          "y": 240,
          "x": -140
        }
      }
    }

更新するためのコマンドは以下のとおりです。

% twilio api:studio:v2:flows:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--commit-message "Update test" \
--status published \
--definition "`cat hello-world.json`"

--sid には、ダウンロードしたフローと同じものを指定します。
コマンドが成功すると、以下のような応答が戻ります。

SID                                 Friendly Name  Status      Revision
FWabe889fbe1650134e76508f2315877a4  Hello World    published   2

管理コンソールで更新されたフローを確認してみましょう。

ちゃんと更新されていますね。

まとめ

StudioフローをAPIベースで新規作成したり更新することができるようになることで、エンジニアの皆さんはメンテナンスがしやすくなりますね。
ただ、実際の開発環境では、いきなりフローを更新したりすることは避けたく、事前にテストしてから本番に切り替えるといった作業が必要になります。
次回は、そのあたりを中心に現場で使えるStudio API V2をご紹介したいと思います。
Twilio CLI（Studio操作編②）

Twilio（トゥイリオ）とは

https://cloudapi.kddi-web.com
Twilioは音声通話、メッセージング（SMS/チャット）、ビデオなどの様々なコミュニケーション手段をアプリケーションやビジネスへ容易に組み込むことのできるクラウドAPIサービスです。初期費用不要な従量課金制で、各種開発言語に対応しているため、多くのハッカソンイベントやスタートアップなどにも、ご利用いただいております。

Twilio CLI（Studio操作編①）