Craft FunctionsからCustom Search APIとPageSpeed insights APIを使い、検索上位記事のメタデータとパフォーマンスの相関分析を行う方法

<html><head></head><body>こんにちは、Customer Engineerの神谷です！最近、ムエタイを習い始めました。今年は総合格闘技の試合にも出たく、打撃にも本腰入れて頑張っていきます！ちなみに得意な打撃技は、ローキックと右オーバーハンドです。
さて今回は、KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法をご紹介します。なぜKARTE Talkで新規チャット問い合わせが来たらSlackに通知できると便利なのか、まずその理由を押さえておきましょう。主に、以下の2つではないでしょうか。
<ul>
<li>問い合わせがあった際にすぐ気づける
<ul>
<li>常にKARTE Talkの画面を注視していられればいいものの、実際はそうもいかない場面もあると思います</li>
<li>そのため、ユーザーから問い合わせが来た際にSlackに通知すれば、そのことに気づきやすくなり、対応も素早くできるようになるでしょう</li>
</ul>
</li>
<li>チームの皆で情報共有可能
<ul>
<li>Slackに通知した際に、グループメンションなどをつけておけば、チーム内の全員に通知が届きます</li>
<li>それにより、対応漏れなどのリスクも低減できる可能性があります</li>
</ul>
</li>
</ul>
このように、KARTE Talkで新規チャット問い合わせが発生した際にSlackに通知することで、ユーザーへの素早い対応やチーム内での情報共有がやりやすくなるでしょう。
<h2 id="アウトプットイメージ">アウトプットイメージ</h2>
KARTE Talkで新規チャット問い合わせが発生した際にSlackに通知することの意義はご理解いただけたと思うので、最終的なアウトプットイメージを、以下に示します。
<img src="https://ik.imagekit.io/plaid/2a023ad1-a125-4417-b723-cd228e23c49b/%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-03-1317.33.19.png" alt="スクリーンショット2024-03-1317.33.19.png">
今回は、問い合わせをしてきたユーザーのユーザーID及び、問い合わせ内容やどこのページで問い合わせが発生したのかをお知らせします。更にKARTE Talkの一覧画面への遷移URLも貼っておけば、それをクリックするだけで、すぐにKARTE Talkを開けます。
続いて、処理の全体像を以下に示します。
<img src="https://ik.imagekit.io/plaid/226662ad-a2a1-42ae-be1f-9a38eabdd6d3/%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-03-1317.32.26.png" alt="スクリーンショット2024-03-1317.32.26.png">
今回は、KARTE TalkとCraft Functionsを連携するのに、以下の2つの機能を利用します。
<ul>
<li><a href="https://developers.karte.io/reference/message-hook-v2" target="_blank" rel="noreferrer">Hook v2 の Message Hook</a>
<ul>
<li>KARTE Talk で新規チャット問い合わせが来たことを外部に連携します</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/hook-v2/index.html" target="_blank" rel="noreferrer">Craft Hook v2 トリガー</a>
<ul>
<li>Hook v2 起動時に Craft Functions を実行します</li>
</ul>
</li>
</ul>
<h2 id="設定手順">設定手順</h2>
設定の手順は次の通りです。
<ol>
<li>Slack appを作成し、対象Slackチャンネルに追加する</li>
<li>API v2アプリを作成する</li>
<li>Slack appの OAuth Token を Craft Secret Manager に登録する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</li>
</ol>
順番に見てみましょう。
<h3 id="1. Slack appを作成し、対象Slackチャンネルに追加する">1. Slack appを作成し、対象Slackチャンネルに追加する</h3>
まず、SlackのAPIを利用するためのSlack appを作成してチャンネルへ追加します。
<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>
<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">
<ul>
<li>作成したappを選択し、[OAuth &amp; Permissions]をクリック</li>
<li>[Scopes &gt; Bot Token Scopes] から次のscopeを追加し保存
<ul>
<li><code>chat:write</code></li>
</ul>
</li>
</ul>
<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">
<ul>
<li>[OAuth &amp; Permissions &gt; Install to Workspace] をクリック</li>
<li>認証画面で [許可する] をクリック</li>
<li>生成された [Bot User OAuth Token] をメモする</li>
</ul>
<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">
<ul>
<li>Slackの画面から、通知したいSlackチャンネルを開く</li>
<li>[インテグレーション &gt; アプリを追加する] から、作成したSlack appをチャンネルに追加</li>
</ul>
<h3 id="2. API v2アプリを作成する">2. API v2アプリを作成する</h3>
KARTEのAPIを利用するために、API v2アプリを作成します。 
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png">
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>talk.message.get</code>を選択します</li>
</ul>
</li>
</ul>
「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。
<h3 id="3. Slack appの OAuth Token を Craft Secret Manager に登録する">3. Slack appの OAuth Token を Craft Secret Manager に登録する</h3>
作成したSlack appのOAuthトークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。
<img src="https://ik.imagekit.io/plaid/de246508-2c91-40ac-a04a-c214af6542c7/create_slack_token_secret.png" alt="create_slack_token_secret.png">
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたBot User OAuth Tokenの値を [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3 id="4. Craft Functionsのファンクションを作成する">4. Craft Functionsのファンクションを作成する</h3>
Craft Functionsのファンクションを作成します。作成手順は次の通りです。
<img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png">
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>SLACK_TOKEN_SECRET</code>
<ul>
<li>Slackアプリの Bot User OAuth Tokenを登録したシークレット名です</li>
</ul>
</li>
<li><code>SLACK_CHANNEL_ID</code>
<ul>
<li>通知対象のSlackチャンネルIDです</li>
</ul>
</li>
</ul>
</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
なお、テンプレートのソースコードはGitHubで公開しています。 
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/talk-new-message-slack-mention" target="_blank" rel="noreferrer">craft-codes/craft-functions/talk-new-message-slack-mention at main · plaidev/craft-codes</a>
ここから、Craft Functionsのコードで重要な部分について、かいつまんでご説明します。
<pre><code class="hljs">// talk.message.getのパラメータを設定
 const userId = data.jsonPayload.data.user_id;
 const contentText = data.jsonPayload.data.content.text;
 const accessUrl = data.jsonPayload.extra.access_uri.url;

 let msg = '';
 msg += `新規チャット問い合わせが来ました！\n`;
 msg += `問い合わせをしたユーザーのID：${userId}\n`;
 msg += `問い合わせ内容：${contentText}\n`;
 msg += `問い合わせが発生したURL：${accessUrl}\n`;
 msg += `Talk一覧はこちら：https://admin.karte.io/communication/v2/workspace/`;
</code></pre>
この部分で、ユーザーから問い合わせがあった際に、そのユーザーIDや問い合わせ内容及び問い合わせが発生したページのURLを取得し、それらを通知メッセージにセットしています。この通知内容はあくまでも一例で、<code>msg</code>の中身を改変することにより、通知内容を自由にカスタマイズすることができます。
<h3 id="5. API v2 アプリにCraft Functions の Hook v2 トリガーを設定する">5. API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</h3>
作成したAPI v2アプリの設定で、Craft Functions の Hook v2 トリガーを追加します。
<img src="https://ik.imagekit.io/plaid/ee276388-cd91-4190-ae84-d4e169536080/add_hook_v2_trigger.png" alt="add_hook_v2_trigger.png">
<ul>
<li>[ストア &gt; API v2設定] から作成したアプリを選択</li>
<li>[hook設定 &gt; 編集] をクリック</li>
<li>[トリガー設定] で次のトリガーを追加
<ul>
<li><code>KARTE Talk: ユーザーからのメッセージ送信時 </code></li>
</ul>
</li>
<li>[チャネル設定 &gt; Craft &gt; hook status &gt; 有効にする] にチェックを付け、作成したファンクションを選択</li>
<li>アプリ設定を保存</li>
</ul>
<h2 id="実際に動かしてみる">実際に動かしてみる</h2>
実際に動作を確認してみましょう。問題なく設定ができていれば、ユーザーからチャット問い合わせが来た際に、Slackに通知が届くはずです。
<img src="https://ik.imagekit.io/plaid/2a023ad1-a125-4417-b723-cd228e23c49b/%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-03-1317.33.19.png" alt="スクリーンショット2024-03-1317.33.19.png">
余裕があれば、冒頭にグループメンションなどをつけてみて、ちゃんとメンションが届くかなども確かめてみてください。メンションのつけ方も、念の為に軽く紹介しておきます。基本的には、通知内容の冒頭にそれぞれ必要な要素を追加するだけです。
<h3 id="チャンネル全体にメンションしたい場合">チャンネル全体にメンションしたい場合</h3>
<pre><code class="hljs">msg += `&lt;!channel&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>冒頭に<code>&lt;!channel&gt;</code>を追加することで、通知時に@channelの全体メンションが発生します</li>
</ul>
<h3 id="特定のグループにメンションしたい場合">特定のグループにメンションしたい場合</h3>
<pre><code class="hljs">msg += `&lt;!subteam^グループID&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>ユーザーグループのグループIDは、 <code>その他 &gt; 自分のオーガナイゼーション &gt; メンバーディレクトリ</code> の順に進むと確認できます</li>
</ul>
<h3 id="個人にメンションしたい場合">個人にメンションしたい場合</h3>
<pre><code class="hljs">msg += `&lt;@ユーザーID&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>SlackのユーザーIDは、ユーザー名をクリックして、<code>プロフィールとアカウント</code>を選択すると確認できます</li>
<li>https://your-workspace.slack.com/team/U12345678の場合、<code>U12345678</code>がそれに該当します</li>
</ul>
<h2 id="おわりに">おわりに</h2>
今回は、KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法をご紹介しました！このソリューションを活用して、KARTE Talkをより便利に使っていただければ嬉しいです。KARTE TalkとCraft Functionsを使った有益なアイデアがまた思いつけば、皆さんにご紹介します。
<hr>
プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。
↓ パートナー企業になりたい
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
↓ PLAIDで働きたい
<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 Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法です。KARTE Talkでユーザーからの新規問い合わせがあったら、それをSlackに通知することで、素早く対応できます。KARTE Talkをお使いの方は、是非お試しください。