本項は、Twitterカスタマーエンゲージメントプレイブックとして、WebhookとREST APIエンドポイントを使用して基本的なチャットボットを構築する方法について説明します。このプレイブックでは、ウェルカムメッセージ、クイック返信、カスタムプロフィール、メディア添付、ボタンなどを使用できる、実際に機能するカスタマーエンゲージメントアプリケーションの作成に必要な知識を学んでいきます。

Webhookとは、Webアプリからリアルタイムで情報を通信するための手段です。ストリーミングとは異なり、Webhookではアクティビティの受信にアクティブな接続を必要としません。また、REST APIと違ってポーリングも不要です。

2006年の設立以来、Twitterは世界を変えるメッセージングプラットフォームの地位を確立してきました。ツイートは世界中にパブリックメッセージを配信するための手段です。ダイレクトメッセージは非公開で会話を行うための手段です。過去数年にわたり、Twitterではプライベートメッセージの改善に取り組んできました。

• ダイレクトメッセージで他のユーザーと、タイムラインからの公開ツイートをより簡単に共有できるようにしました。
• ダイレクトメッセージの文字数制限を1万文字まで増やしました。
• 誰からでもダイレクトメッセージを受信できるようにしました。
• ツイート、Twitterのプロフィール、さらにはウェブサイトからもダイレクトメッセージの会話を簡単に開始できるようにしました。
• メッセージ内のテキストとともにメディアやカードを表示できるようにすることで、ダイレクトメッセージをより魅力的かつ充実したものにしました。

現在Twitterではダイレクトメッセージをより良いチャンネルにすることに取り組んでいます。パーソナライズされたカスタマーエクスペリエンスを大規模に配信できるようなメッセージのやりとりを、開発者が構築できるようにします。そのため、Webhook経由でダイレクトメッセージをリアルタイムに取得できる機能と、よりスピーディかつ簡単に会話ができる機能を実装するREST APIを提供しています。

• ウェルカムメッセージ:企業はウェルカムメッセージを使用してユーザーにあいさつし、ダイレクトメッセージの会話を始める際に期待値を設定できます。ユーザーから最初のメッセージを送信してもらう必要はありません。企業は複数のウェルカムメッセージを作成し、ツイートやウェブサイト、アプリから特定のあいさつに直接ジャンプするディープリンクを作成できます。
• クイック返信:企業はクイック返信を使用することで、オプションのリストから選択してダイレクトメッセージに返信するための最適な方法をユーザーに提供できます。
• カスタムプロフィール:Twitterプロフィールのアバターやメッセージに付加される表示名よりも優先的に使用され、人間的な要素やチャットボットのエクスペリエンスがよりパーソナルなものになります。
• ボタン:メッセージにボタンを配置することで、ツイートの作成、アカウントのフォロー、Twitterアプリ内でのウェブサイト表示など、ダイレクトメッセージの会話の外での操作をアカウントが簡単に実行できるようになります。

優れたカスタマーエクスペリエンスの構築に必要なメッセージを取得するには、以下を行う必要があります。

• 適切な権限を持つTwitterアプリを作成することで、API経由でTwitterアカウントからダイレクトメッセージなどのアクティビティを受信できます。
• Twitterサインイン経由でOAuthを使用して、顧客のダイレクトメッセージを利用するための権限を取得する
• Webhookでユーザーアクティビティを受信するように構成し、必要なメッセージを取得する

受信したメッセージに応答し、新しい機能を使用してダイレクトメッセージ内にエクスペリエンスを作成するためには、以下を実行してください。

• ウェルカムメッセージRESTエンドポイントを使用してウェルカムメッセージの作成と管理を行う
• RESTエンドポイントを使用して、通常のメッセージやウェルカムメッセージにクイック返信とカスタムプロフィールを配置する
• RESTエンドポイントを使用して会話にメディアを追加する
  

ダイレクトメッセージサービスの使用を開始するには、開発者は複数の手順を実行する必要があります。

• 承認済み開発者アカウントの [Apps] ページでアプリを作成します。所属企業を代表してアプリを作成する場合は、Twitterの企業アカウントを使用してアプリを作成することをおすすめします。
• アプリページの権限のタブで [Read, Write and Access direct messages] を有効にします。
• [Keys and Tokens] タブで、アプリのコンシューマーキー（APIキー）とコンシューマートークン（APIシークレット）をメモします。
• 同じタブで、アプリのアクセストークンとアクセストークンシークレットを生成します。Twitterがアカウントイベントを送信するWebhook URLを登録するために、これらのアクセストークンが必要です。
• Twitterサインイン、およびユーザーコンテキストとTwitter APIの連携の仕組みに馴染みがない場合は、「アクセストークンの取得」を確認してください。イベントを受信するアカウントを追加する際、そのアカウントのアクセストークンを使用してイベントの受信登録を行います。
• 開発者ポータルの [Apps] ページに表示されているアプリの数値IDをメモします。アカウントアクティビティAPIへのアクセス権を申請する際は、このアプリIDが必要です。
  

Twitterアプリを作成したら、次にアカウントアクティビティAPIへのアクセス権を申請します。

サンドボックスティア、または有料のプレミアムアカウントアクティビティAPIティアにアクセスするには、開発者アカウントを設定する必要があります。開発者アカウントをまだ申請していない場合は、以下のリンクから申請してください。

開発者アカウントを申請する

開発者アカウントを取得したら、プレミアムアカウントアクティビティAPIへのアクセス権を設定しましょう。アカウントアクティビティAPI開発環境に接続するにはTwitterアプリが必要です。

1. ログインして [Dev Environments] ページに移動します。 
2. [Set up dev environment] をクリックし、環境に名前を付けて、環境で使用するTwitterアプリIDを指定します。サンプルのプレミアムエンドポイントURLの:env_nameトークンは、選択した環境名に置き換わります。たとえば、環境名として「prod」を使用する場合、URLのパターンは「https://api.x.com/1.1/account_activity/all/prod/webhooks」となります。
    

スクリプトとビジュアルダッシュボードを使用してアカウントアクティビティを設定する場合は、Twitterの開発チームがサポートするアカウントアクティビティダッシュボードを確認してください。

• アカウントアクティビティAPIへのアクセス権を取得したら、Twitter Webhookイベントを受信するWebアプリの開発、デプロイ、ホスティングを行う必要があります。 
• イベントを受信するためのWebhookとして使用するためのURLを持つWebアプリを作成します。これは受信Twitter Webhookイベントをリッスンするサーバーにデプロイされるエンドポイントです。 
  • URIパスは自由に設定できます。有効な例は次のとおりです: https://mydomain.com/service/listen
  • さまざまなソースのWebhookをリッスンする場合の一般的なパターンは次のとおりです: https://mydomain.com/webhook/twitter
  • 専用のURLにはポート仕様を含めることができません（https://mydomain.com:5000/NoWorkie）。
• Webhookのセキュリティ保護のガイドに記載されているとおり、はじめにTwitterのチャレンジレスポンス方式のチェック（CRC）でGETリクエストを受信し、適切にフォーマットされたJSON応答を返すコードを記述します。 
• Webhook URLを登録します。/webhooks.json?url= endpointへのPOSTリクエストを行います。このリクエストを行うと、Webアプリに対してTwitterからCRCリクエストが発行されます。Webhookの登録に成功すると、応答にWebhook IDが含まれます。このWebhook IDは、後でアカウントアクティビティAPIにいくつかのリクエストを行う際に必要となります。 
• 登録したURLにTwitterからアカウントWebhookイベントが送信されます。Webアプリで受信イベントのPOSTリクエストをサポートするようにしてください。これらのイベントはJSONでエンコーディングされます。Webhook JSONペイロードのサンプルについてはこちらを参照してください。
• Webアプリの準備ができたら、次にアクティビティを受信するアカウントを追加します。アカウントを追加（または削除）する際には、アカウントIDを参照するPOSTリクエストを行います。詳細については、サブスクリプションの追加に関するガイドを参照してください。
• アプリとWebhookが正しく構成されているかを検証するには、アプリで受信登録しているいずれかのTwitterアカウントが投稿したツイートを「いいね」にします。受信登録者が受信する各「いいね」について、Webhook URLへのPOSTリクエスト経由で「いいね」イベントを受信するはずです。

別のアカウントの代理として書き込み操作（ツイートやメッセージの作成）を行ったり、そのアカウントの個人情報を読み取ったりするには、アクセストークンを取得する必要があります。アクセストークンはTwitter APIを使用する際にユーザーコンテキストを提供します。

• ユーザー - Twitterの@user。Twitter APIのすべての書き込み操作でユーザーのコンテキストが必要です。チャットボットはTwitterアカウント上に存在し、独自のエンティティではありません。チャットボットの存在するアカウントはユーザーです。チャットボットとやりとりする顧客もユーザーです。Twitter上のすべてのメッセージは、2つのユーザーエンティティ間で送信されます。
• アプリ - Twitterアプリは承認済みの開発者アカウントで作成されます。アプリの所有ユーザーは常に1人だけです。アプリはTwitter APIを使用するためのベースコンテキストを提供します。
  

1. アプリを所有するユーザー/単一ユーザー - アプリを所有するユーザーの場合は、開発者ポータルの [Apps] ページからアプリの [Details] セクションにある [Keys and Tokens] タブでアクセストークンを生成できます。ページ最下部にある [Create] ボタンをクリックします。
2. アプリを所有していないユーザー/複数ユーザー - 複数のアカウントの代わりにアプリでアカウントアクティビティイベントを使用する場合、各ユーザーがアプリで認証を行って権限を付与する必要があります。これを実現するには、Twitterサインインを実装するWebアプリが必要です。

プロセスのこの時点で、開発者ポータルでのアプリケーションの設定、エンドポイントを保護するための最初のチャレンジレスポンス方式チェックの実行、自身のアプリケーションでコンテンツを公開する、または明示的な権限を付与した他のユーザーの代わりにコンテンツを公開するためのアクセストークンの取得に必要な情報がすべて揃っているはずです。ここからは、アプリで使用するさまざまなエンドポイントについて見ていきましょう。

会話型エクスペリエンスを実現するために、Twitterではダイレクトメッセージのデータを、そのエクスペリエンスの機能に関するメタデータを含むWebhook経由でリアルタイムに提供しています。さらに、メッセージの作成、ウェルカムメッセージとカスタムプロフィールデータの取得、これらの機能の管理を行うためのRESTエンドポイントが用意されています。以下の基本フローを理解することで、手順3で作成したサンプルアプリのクローンをベースに独自のアプリを設定できます。

• アカウントアクティビティAPIのWebhookセットアップ経由でダイレクトメッセージ（送受信）に関するデータが開発者にリアルタイムで提供される
  • アプリのWebhook URLを登録する:
    • POST account_activity/all/:env_name/webhooksに対するAPI呼び出し
    • 開発者は、1つの環境につきURLを1つだけ登録可能
  • 開発者は有効なアクセストークンを生成するために、Twitterサインイン経由でのアプリの認証をユーザーに依頼する
  • 新しいサブスクリプションを追加する（登録済みWebhookを介してユーザーの代わりにアプリでダイレクトメッセージを受信できるようにする）
    • POST account_activity/all/:env_name/subscriptionsに対するAPI呼び出し
    • ユーザーは有効なアクセストークンとアプリが必要（手順4）
  • PUT account_activity/all/:env_name/webhooksエンドポイントを使用してWebhook URLを検証する
  • GET account_activity/all/:env_name/webhooksエンドポイントを使用してWebhook構成を取得する
• GET direct_messages/events/listエンドポイントを使用して、過去30日間に送受信されたすべてのダイレクトメッセージを取得する
• GET direct_messages/events/showエンドポイントを使用して、IDに基づいてダイレクトメッセージを1つ取得する（このエンドポイントには時間制限がない）
• POST direct_messages/events/new (message_create)を使用してメッセージを送信する
  
  • このエンドポイントは、こちらのsend-direct-messageスクリプトで参照される
    

• POST direct_messages/welcome_messages/newを使用して新しいウェルカムメッセージを作成する
  • このエンドポイントは、こちらのcreate-welcome-messageスクリプトで参照される
• POST direct_messages/welcome_messages/rules/newを使用して、ウェルカムメッセージ用の新しいルールを作成する
  • このエンドポイントは、こちらのスクリプトで参照される

• DELETE account_activity/webhooks/:webhook_id/subscriptionsを使用してサブスクリプションを削除する
  • このエンドポイントは、こちらのスクリプトで参照される
• GET account_activity/webhooksを使用して現在のWebhook構成を取得する
  • このエンドポイントは、こちらのスクリプトで参照される

以下はアプリケーション構築の際に役立つデバッグツールのリストです。

• Postman - モックリクエストを構築する
• Ngrok - ローカルマシンでコードをテストする
• Runscope - APIフローの動作を開発者が確認できるようにする

ここまでで、リアルタイムでダイレクトメッセージにアクセスして、顧客に代わりパーソナライズされたエクスペリエンスを大規模に作成するためのソリューションが完成しました。これで、コンテキストに合ったウェルカムメッセージで会話を開始できます。クイック返信オプション付きのメッセージや、リンクを開くボタンがあるメッセージを作成したり、メッセージに魅力的なメディアを添付することができます。こうしたメッセージにカスタムプロフィールを配置して、人間とチャットボットのどちらが対応しているのかを明確にすることができます。こちらのサンプルのようにするのが理想的です。

この機能では、任意のダイレクトメッセージやウェルカムメッセージのPOSTリクエストにアクション誘導またはボタンを最大3つまで追加できます。ボタンは、Twitterアプリでユーザーに表示される、任意のhttps URLやアクション誘導を開くために使用され、自由にカスタマイズできます。

ボタンの目的は、WebビューやTwitterアプリの別の部分など、ダイレクトメッセージ以外の場所でユーザーが簡単に操作を実行できるようにすることです。たとえば、次の目的でアクション誘導を使用できます。

• ダイレクトメッセージのやりとりが終了したらツイートを作成する（例: チャットボットについて他のユーザーに知らせる、クーポンを共有する、一般提供する）。ツイートWebインテントURLスキームを使用することでこれを実現できます。
• ダイレクトメッセージのやりとりが終了したらユーザーアカウントをフォローする（例: やりとりが終了した時に企業からの最後のリクエストとして）。フォローボタンWebインテントURLスキームを使用することでこれを実現できます。
• 別のアカウントにダイレクトメッセージを送信する（例: マーケティング関連のチャットボットから、サポートが得られる専任のカスタマーサービスの@usernameにアカウントを誘導する）。ダイレクトメッセージディープリンクスキーム（twitter.com/messages/compose…）を使用することでこれを実現できます。
• メッセージ内よりも操作しやすいモバイルウェブページでやりとりを行うためにWebビューを開く（例: クレジットカードを使用して購入する、異なる製品の対照比較を行う）。

ボタンに関する技術情報については、こちらを参照してください。