Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のコンバージョンイベントの成果をSlackに通知する方法

<html><head></head><body><p>こんにちは、Customer Engineerのgamiです！最近、近所の革小物屋さんでちょっと良いペンケースを買いました。</p>
<p>さて、KARTEにはKARTE Talkというウェブチャットの機能があり、KARTEの管理画面経由でオペレーターがWebサイト上のエンドユーザーとチャットのやり取りができます。</p>
<p><a href="https://karte.io/feature/talk/" target="_blank" rel="noreferrer">KARTE Talk｜ウェブチャットでの双方向コミュニケーション | CX（顧客体験）プラットフォーム KARTE（カルテ）</a></p>
<p>一方で、出先などでKARTEの管理画面を開けないときにも気軽にチャット対応をしたいというニーズがあります。そんなとき、普段使っているチャットツールを介してエンドユーザーへのチャット返信ができると便利です。</p>
<p>そこで今回は、KARTE Craftを使ってKARTE Talkのエンドユーザーとのチャット対応をSlack経由でできるようにする方法について紹介します。</p>
<h1 id="アウトプットイメージ">アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは次の通りです。</p>
<p>エンドユーザーからのチャットメッセージはSlackに自動で通知されます。オペレーターはそのSlackスレッドに返信をします。</p>
<p><img src="https://ik.imagekit.io/plaid/9f5598a7-5cb5-4d43-b0bc-b70b2664c75a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2018.51.32.png" alt="スクリーンショット2024-02-2018.51.32.png"></p>
<p>すると、エンドユーザーのウェブチャットにSlackで投稿したオペレーターの返信が反映されます。</p>
<p><img src="https://ik.imagekit.io/plaid/f606ef6e-57a8-4ee2-813d-2e06b20839ad/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2018.52.29.png" alt="スクリーンショット2024-02-2018.52.29.png"></p>
<p>構成図は次の通り。</p>
<p><img src="https://ik.imagekit.io/plaid/8b3bab54-868f-419b-94ee-a8415fa617c2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2021.12.21.png" alt="スクリーンショット2024-02-2021.12.21.png"></p>
<p>大きくいうと、次の2つの処理があります。</p>
<ul>
<li>KARTE to Slackの連携
<ul>
<li>KARTE Talkが受け取ったエンドユーザーのメッセージをSlackのスレッドに同期する</li>
</ul>
</li>
<li>Slack to KARTEの連携
<ul>
<li>Slackが受け取ったオペレーターのメッセージをKARTE Talkのチャットに同期する</li>
</ul>
</li>
</ul>
<p>ちなみに今回紹介するテンプレートでは、Craft Functionsの1つのファンクションの中に両方の処理を実装をしています。</p>
<h1 id="注意点">注意点</h1>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>KARTE Talk、KARTE Craft、Slackを利用していることを前提としています</li>
</ul>
<h1 id="設定手順">設定手順</h1>
<p>設定の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>Slack Appを作成し、対象Slackチャンネルに追加する</li>
<li>API v2 アプリの アクセストークンとSlack App の OAuth Token を Craft Secret Manager に登録する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</li>
<li>Slack AppのEvent Subscriptionsを追加する</li>
</ol>
<p>順番に見てみましょう。</p>
<h2 id="1. API v2 アプリを作成する">1. API v2 アプリを作成する</h2>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>bot</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>talk.message.get</code></li>
<li><code>talk.message.sendFromOperator</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
<li>[基本設定 &gt; Bot Id] をメモしておく</li>
</ul>
<p>今回はKARTE Talkへの投稿をbotとして実行するので、アプリタイプをbotにする点に注意してください。</p>
<h2 id="2. Slack Appを作成し、対象Slackチャンネルに追加する">2. Slack Appを作成し、対象Slackチャンネルに追加する</h2>
<p>SlackのAPIを利用するためのSlack Appを作成してチャンネルへ追加します。</p>
<ul>
<li><a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">SlackのApplications画面</a> から[Create New App]をクリック</li>
<li>Create an appの画面で [From scratch] を選択</li>
<li>Slack App名を入力し、Slackの対象ワークスペースを選択</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/2de46e75-afc9-4d6f-92a5-444e6a1aa71e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1812.57.49.png" alt="スクリーンショット2023-07-1812.57.49.png"></p>
<ul>
<li>作成したアプリを選択し、[OAuth &amp; Permissions]をクリック</li>
<li>[Scopes &gt; Bot Token Scopes] から次のscopeを追加し保存
<ul>
<li><code>chat:write</code></li>
<li><code>channels:history</code></li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/0696d92f-ec7b-4c5d-9327-cddfbc143039/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-07-1813.01.11.png" alt="スクリーンショット2023-07-1813.01.11.png"></p>
<ul>
<li>[OAuth &amp; Permissions &gt; Install to Workspace] をクリック</li>
<li>認証画面で [許可する] をクリック</li>
<li>生成された [Bot User OAuth Token] をメモする</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/f96bb42a-bb85-4fea-9fea-c202d26aaab5/add_slack_app_to_channel.png" alt="add_slack_app_to_channel.png"></p>
<ul>
<li>Slackの画面から、通知したいSlackチャンネルを開く</li>
<li>[インテグレーション &gt; アプリを追加する] から、作成したSlack Appをチャンネルに追加</li>
</ul>
<h2 id="3. API v2 アプリの アクセストークンとSlack App の OAuth Token を Craft Secret Manager に登録する">3. API v2 アプリの アクセストークンとSlack App の OAuth Token を Craft Secret Manager に登録する</h2>
<p>トークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png"></p>
<p>下記の手順を、「API v2 アプリの アクセストークン」と「Slack AppのBot User OAuth Token」の両方についてそれぞれ実施してください。</p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>[シークレットの値] にコピーしたアクセストークンを入力し、作成</li>
</ul>
<h2 id="4. Craft Functionsのファンクションを作成する">4. Craft Functionsのファンクションを作成する</h2>
<p>Craft Functionsのファンクションを作成します。作成手順は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>KARTE Talkのエンドユーザーとのチャット対応をSlack経由でできるようにする</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベル</li>
</ul>
</li>
<li><code>SLACK_CHANNEL_ID</code>
<ul>
<li>利用するSlackチャンネルのID</li>
</ul>
</li>
<li><code>SLACK_TOKEN_SECRET</code>
<ul>
<li>Slack AppのBot User OAuth Tokenを登録したシークレットの名前</li>
</ul>
</li>
<li><code>SLACK_APP_USER_ID</code>
<ul>
<li>作成したSlack AppのSlack上でのメンバーID（後述）</li>
</ul>
</li>
<li><code>KARTE_APP_TOKEN_SECRET</code>
<ul>
<li>API v2 アプリのアクセストークンを登録したシークレットの名前</li>
</ul>
</li>
<li><code>KARTE_BOT_ID</code>
<ul>
<li>作成したKARTE API v2のBot Id</li>
</ul>
</li>
<li><code>IGNORE_TALK_ACCOUNTS</code>
<ul>
<li>Slack通知の対象から発言を除外したいKARTE TalkオペレーターIDがいる場合は、カンマ区切り文字列で指定します
<ul>
<li>例: <code>bot-xxxxxxx,yyyyyyy</code></li>
</ul>
</li>
<li>特にbotによる投稿を除外したい場合に利用します</li>
<li>作成時は設定しなくても問題ありません</li>
</ul>
</li>
<li><code>KVS_KEY_PREFIX</code>
<ul>
<li>Craft KVSのレコードのkey名に付与する接頭辞</li>
<li><code>KARTE_TALK_VIA_SLACK</code> など適当な値でOKです</li>
</ul>
</li>
<li><code>KVS_EXPIRE_MINUTES</code>
<ul>
<li>Craft KVSのレコードの生存期間（分）</li>
<li>この設定値の期間だけ、KARTE側user_idとSlackスレッドIDの対応関係がCraft KVSに保持されます</li>
<li>たとえば <code>1440</code> に設定すると、同一ユーザーからの問い合わせは最後のやりとりから24h以内であればSlackの同一スレッドに投稿され、それ以降は新規問い合わせとみなされて新しいSlackスレッドが立ち上がります</li>
</ul>
</li>
</ul>
</li>
<li>[設定 &gt; ファンクションの有効化] にチェックを付けて [保存]</li>
</ul>
<p><code>SLACK_APP_USER_ID</code>の設定がわかりにくいのですが、追加したSlackのチャンネル画面から作成したSlack Appのプロフィールを開き、[メンバーIDをコピー]からコピーできる <code>U</code> から始まる値を入力してください。この設定によって、Slack上でのSlack App自身のメッセージをCraft Functions側で無視することができるようになります。</p>
<p><img src="https://ik.imagekit.io/plaid/ef71a609-7add-40c4-8499-265153cf73ac/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2019.05.27.png" alt="スクリーンショット2024-02-2019.05.27.png"></p>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/karte-talk-via-slack" target="_blank" rel="noreferrer">craft-codes/craft-functions/karte-talk-via-slack at main · plaidev/craft-codes</a></p>
<h2 id="5. Craft Functionsのエンドポイントを作成する">5. Craft Functionsのエンドポイントを作成する</h2>
<p>作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png"></p>
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h2 id="6. API v2 アプリにCraft Functions の Hook v2 トリガーを設定する">6. API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</h2>
<p>作成したAPI v2アプリの設定で、Craft Functions の Hook v2 トリガーを追加します。</p>
<p><img src="https://ik.imagekit.io/plaid/ee276388-cd91-4190-ae84-d4e169536080/add_hook_v2_trigger.png" alt="add_hook_v2_trigger.png"></p>
<ul>
<li>[ストア &gt; API v2設定] から作成したアプリを選択</li>
<li>[hook設定 &gt; 編集] をクリック</li>
<li>[トリガー設定] で次のトリガーを追加
<ul>
<li><code>KARTE Talk: ユーザーからのメッセージ送信時</code></li>
<li><code>KARTE Talk: オペレーターからのメッセージ送信時</code></li>
</ul>
</li>
<li>[チャネル設定 &gt; Craft &gt; hook status &gt; 有効にする] にチェックを付け、作成したファンクションを選択</li>
<li>アプリ設定を保存</li>
</ul>
<h2 id="7. Slack AppのEvent Subscriptionsを追加する">7. Slack AppのEvent Subscriptionsを追加する</h2>
<p>SlackチャンネルのやりとりをCraft Functionsのエンドポイントに連携するための設定をSlack Appに追加します。</p>
<p><img src="https://ik.imagekit.io/plaid/829b8bba-0ae1-4070-918f-119a5f9c7f0b/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-219.45.56.png" alt="スクリーンショット2024-02-219.45.56.png"></p>
<ul>
<li><a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">SlackのApplications画面</a> から作成したSlack Appを選択</li>
<li>[Event Subscriptions &gt; Request URL] に、作成したCraft FunctionsのエンドポイントURLを入力</li>
<li>[Subscribe to bot events] に次のイベントを追加
<ul>
<li><code>message.channels</code></li>
</ul>
</li>
<li>Appを保存し、ワークスペースにAppをインストールしなおす</li>
</ul>
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<ul>
<li>エンドユーザーとして、ウェブチャットからメッセージを送信する</li>
<li>エンドユーザーからのチャットメッセージがSlackに自動で通知されることを確認する</li>
<li>オペレーターとして、そのSlackスレッドに返信をする</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/9f5598a7-5cb5-4d43-b0bc-b70b2664c75a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2018.51.32.png" alt="スクリーンショット2024-02-2018.51.32.png"></p>
<ul>
<li>エンドユーザーのウェブチャットにSlackで投稿したオペレーターの返信が反映されることを確認</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/f606ef6e-57a8-4ee2-813d-2e06b20839ad/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882024-02-2018.52.29.png" alt="スクリーンショット2024-02-2018.52.29.png"></p>
<p>もしうまく動作しない場合は、Craft Functionsのログを確認してみてください。</p>
<h1 id="補足: KARTE Talkのオペレーターアカウントで返信する">補足: KARTE Talkのオペレーターアカウントで返信する</h1>
<p>今回のソリューションは、デフォルトでは作成したKARTE API v2アプリに紐付くBotユーザーでエンドユーザーへのチャット返信が行われます。一方で、SlackのアカウントとKARTE Talkのオペレーターを紐付けることで、「このSlackアカウントでメッセージ送信した場合はこのKARTE Talkオペレーターとして返信する」といったことも可能です。</p>
<p>その場合は、Craft Functionsにある次のコードに、 Slack IDとKARTE TalkオペレーターIDの対応表を直接登録してください。</p>
<pre><code class="hljs"><span class="hljs-keyword">const</span> SLACK_KARTE_ACCOUNT_ID_MAP = {
  <span class="hljs-literal">default</span>: KARTE_BOT_ID,
  <span class="hljs-comment">// SlackのメンバーID: 'KARTE TalkのオペレーターID' の組を登録すると、対応するオペレーターからの返信としてメッセージを送信できる</span>
  U2ABCDEFG: <span class="hljs-string">'a1234567890b1234567890c1'</span>, <span class="hljs-comment">// 例。 左がSlackのメンバーID、右がKARTE TalkのオペレーターID</span>
};
</code></pre>
<p>なお、KARTE TalkのオペレーターIDは [Talk &gt; トーク設定 &gt; オペレーター管理] から取得できます。</p>
<h1 id="おわりに">おわりに</h1>
<p>今回はKARTE Talkのエンドユーザーとのチャット対応をSlack経由でできるようにする方法について紹介しました。</p>
<p>普段利用しているチャットツールの画面からエンドユーザーと気軽にウェブチャットのやりとりができるのは、オペレーターの体験としても便利です。KARTEのトーク画面を使った対応と併用もできるので、ぜひ皆さんも試してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer" target="_blank" rel="noreferrer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer" target="_blank" rel="noreferrer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>
</body></html>

KARTEの管理画面を開けないときにも気軽にKARTE Talkのチャット対応をしたいというニーズを想定して、KARTE Talkのエンドユーザーとのチャット対応をSlack経由でできるようにする方法について紹介します。