Twilio コネクト

概要

Twilio Connect は、ユーザのTwilioアカウントへのアクセスを認証し、ユーザのアプリケーションから電話番号を購入したり、電話を架けたり、SMSを送信したり、ログデータへのアクセスを可能にしたりします。 皆さんのお客様は、自身のTwilioアカウントを使っているため、皆さんがサービス代金を請求することについて気にかける必要はありません。 Twilioが直接、皆さんのお客様へサービス代金を請求します。

更に、皆さんのお客様は、皆さんへ自身の Twilio通話やSMSログデータへの Connect App のアクセスを許可することができます。 この情報を用いて、皆さんのアプリケーションに解析させたり、読み取り専用で様々な用途に活用して頂けます。

すぐに使い始めたいですか?Twilio クライアント クイックスタートですぐに始めましょう。

Connect App の管理

アカウント画面のAppsページから、Connect Apps を作成します。 Connect Apps をアップデートするには、Appsページを使うか、新しい Connect REST APIを用いることができます。

ヘルパーライブラリ

Twilio ヘルプライブラリ を使って簡単にユーザのTwilioアカウントへ認証されたアクセスを実現できます。 認証で提供された AccountSID を入れるだけです。

ベスト プラクティス

Twilio Connect はユーザアプリケーションにおける新しい考え方です。 ベストプラクティス では、Connect App がセキュアでエラーフリーであるために守るべきガイドラインを紹介します。

動作のしくみ

Connect App を作る際、ユーザーから2つの違うパーミッションを要求することができます。

「データ読み取り権限」 は、アプリケーションに、音声通話・SMSをはじめとする各種ログに対する読み取りを許可し、解析や読み取り専用の様々なケースに活用できます。

「課金権限」 は、アプリケーションに、電話番号を購入させたり、音声通話をしたり、SMSを送信したりすることをはじめ、Twilioが直接ユーザに課金する対象となる行為を許可します。

Connect Appを作成した後は、公開するページにHTMLコードを埋め込みます。 このHTMLコードは、ユーザにConnect APPが自身のTwilioアカウントを使うことを承認する「接続ボタン」として表示されます。 アプリケーションの利用者が Twilio アカウントを持っていない場合は、Twilio にサイン アップするよう求められます。

これらのパーミッションは、相互排他ではありません。 「データ読み取り権限」 と「課金権限」を両方要求することもできます。 もし、Connect App のパーミッションを変更した場合、ユーザが再度 Connect Appを承認しない限り、新しいパーミッションは利用できません。

ユーザが Connect App を承認した後、Twilioは AccountSID を AuthorizeRedirectUrl のURLにGETのクエリパラメータとして加え、リダイレクトします。 この AccountSid がユーザアカウントへのアクセスを与えるものです。 この、AccountSid と AuthToken を用いて認証を行うことができます。 もし、接続ボタンのターゲットURLにおけるクエリパラメータに "state" を付け加えると、Twilio はこのパラメータを AuthorizedRedirectUrl に渡します。 これはAuthorizeURL へメタデータ、例えば、お客様のユーザ名や固有識別子などをを渡すような場合に便利です。

「課金権限」パーミッション (APIでは "post-all") を持っている場合、電話番号を買ったり、音声通話を架けたり、SMSを送信したりするために、このアカウントの全URLに対し POST をすることができます。 「データ読み取り権限」パーミッション (APIでは "get-all") を持っている場合、そのユーザアカウントの /Accounts に対してGETをかけ、すなわち、全てのリソースを読み取ることができます。

ベスト プラクティス

やってよいこと
  1. 接続ボタンは認証フォームに隠してに設置します。
    Twilio Connect では、エンド ユーザーの代わりにリクエストを発行する許可をアプリケーションに与えることができますが、エンド ユーザーの認証メカニズムとして機能することはありません。 したがって、ユーザーが開発するアプリケーションで認証メカニズムを提供しなければなりません。 詳細については、認証のセクションを参照してください。

    接続ボタンを設置する場合は、ユーザに Connect App からの利用代金は直接Twilioから請求がくる旨を予め告知しておきべきです。

  2. 他のページへのリダイレクトは AuthorizeURLの後で行う。
    AuthorizeURL は ConnectApp のみが使うべきものです。 Twilio はユーザの AccountSid を AuthorizeURL へ渡します。 このAccountSid を然るべく格納した後で、他のページへリダイレクトを行うべきです。

  3. Deauthorize URL を使う
    ユーザがConnect App から権限を剥奪した時、Twilio は DeauthorizeCallbackURL に対してHTTPリクエストをかけます。 これをデータベースに反映するようにしてください。

やってはいけないこと
  1. AccountSidを第三者から可視にしないこと
    Twilio APIで生成される全てのリクエストは AuthToken で認証される必要があります。AccountSid も他のユーザ情報同様、厳重に扱ってください。

  2. Connect Appのパーミッションをむやみに変更しないこと
    前述の通り、Connect Appが必要なパーミッションを変更してしまうと、ユーザがConnect Appを再認証するまで利用することができません。 Connect App のパーミッションを頻繁に変えると、どのアカウントにどのパーミッションが与えてあるのか分からなくなる可能性があります。 パーミッションは新しい機能がそれを必要としたときだけ変更することをお勧めします。

パーミッション

Twilio の Connect App には2つのパーミッションがあります。

「データ読み取り権限」

この権限は、Connect App に、音声通話、SMS、録音内容、トランスクリプションを含む全てのデータを閲覧させます。 さらに、他の Connect App で生成されたデータや、サブアカウント、親アカウントに対してもアクセス権を持ちます。 このパーミッションだけを持つ Connect App はユーザアカウントに対し、HTTP GET だけを行えます。

課金権限

この権限は、Connect App に、音声通話の送受信、SMSの送受信、電話番号の購入といった、料金が発生するアクションを許可します。 ただし、親アカウントのリソースへのアクセス権(例えば電話番号に対する) は持ちません。 むしろ、AccountSid を AuthorizeURL へ通すことによって、ユーザに代わって電話番号を買わなければなりません。

TwilioがAuthorize URLに返してきたAccountSidは、ユーザアカウントに属する当該Connect Appへの利用に限ったサブアカウントです。 これにより、他のConnect Appがデータを書き換えることなく、当該Connect Appで電話番号を買ったり、音声通話をしたりすることを実現します。

Connect App 設定オプション

Connect App は、認証フローやアカウントポータル内の各所への様々な設定オプションがあります。

オプション 説明
フレンドリーネーム Connect App の名前 認証画面と認証済みアプリケーションリストに表示されます。 必須
アプリケーションロゴ Connect App に関連づけられたロゴや写真 認証画面と認証済みアプリケーションリストに表示されます。
会社名 Connect App 開発社名 認証画面と認証済みアプリケーションリストに表示されます。 必須
説明 Connect App の簡単な使途説明 認証画面に表示されます。
ホームページURL Connect App のURL。認証済みアプリケーションリストに表示されます。
利用規約URL Connect App の利用規約へのURL。 認証済みアプリケーションリストに表示されます。
Authorize URL 認証フローの最後でリダイレクトされる先のURL。 ユーザが Connect App を承認した場合、このURLに対し、GETによってAccountSid をパラメータとして渡します。

ユーザが拒否した場合このURLに対し、GET によって 「error=unauthorized_client」をパラメータとして渡します。
Deauthorize URL ユーザーが Connect App へのアクセスを無効化したときに、Twilio がリクエストを送信する URL です。これはサーバー間リクエストです。ユーザーがこの場所に転送されることはありません。

このリクエストで、次の 2 つのパラメーターが送信されます。
  • AccountSid 認証を拒否したユーザの AccountSid
  • ConnectAppSid 認証を拒否されたConnect App の ConnectAppSid
  • Deauthorize URL HTTP メソッド DeauthorizedCallbackUrl へリクエストを送信する際に、Twilio が使用する HTTP のメソッドです。 GET か POST を選択できます。
    アクセス必須 Connect App が必須とするアクセスタイプ。 詳細は、パーミッションのセクションを参照してください。

    Need some help?

    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.