「KARTE & Craft ソリューション開発オフサイト」に行ってきました！ (2023年 秋)

<html><head></head><body><p>こんにちは、Customer Engineeringの清水です！<br>
最近、休日の朝活にハマっていて週1で皇居ランをしています！</p>
<p>さて、KARTE Talkではチャット・メール・SMS・LINE・プッシュ通知などのツールでお客様とコミュニケーションを取ることが出来ますが、円滑なコミュニケーションをとる目的で「担当者がアサインされた時に通知を飛ばしたい」と思ったことはないでしょうか？</p>
<p>例えば次のようなケースです。</p>
<ul>
<li>自分が担当したいけれど、手が空いてなくて他の人に担当してもらいたい。KARTE Talkで担当者を変更すると、その内容が通知されるようにしたい。</li>
</ul>
<p>今回は、KARTEの「Hook v2」機能と「Craft Functions」を使ってKARTE Talkの担当者がアサインされた時にSlackに通知を飛ばす方法を紹介します。</p>
<p>以下のようなメッセージが、通知されるようになります。<br>
<img src="https://ik.imagekit.io/plaid/d8f28166-35b0-4e86-9751-3cf426730ff6/%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-12-1111.51.22.png" alt="スクリーンショット2023-12-1111.51.22.png"></p>
<h1 id="全体像">全体像</h1>
<p>実現する処理の全体像は、次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/7d454285-8510-43cd-83a0-642644031264/20231124_1603.png" alt="20231124_1603.png"><br>
KARTE TalkとCraft Functionsの連携では、次の2つの機能を利用します。</p>
<ul>
<li><a href="https://developers.karte.io/reference/assign-hook-v2" target="_blank" rel="noreferrer">Hook v2 の Assign Hook</a>
<ul>
<li>KARTE Talk で担当オペレーターが変更されたことをトリガーに、新しい担当オペレーターの情報を hook する</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/hook-v2" target="_blank" rel="noreferrer">Craft Hook v2 トリガー</a>
<ul>
<li>Hook v2 起動時に Craft Functions を実行する</li>
</ul>
</li>
</ul>
<h1 id="実装手順">実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Slackアプリを作成する</li>
<li>Slackアプリをチャンネルに追加する</li>
<li>API v2アプリを作成する</li>
<li>Slack アプリの OAuth トークンを Craft Secret Manager に登録する</li>
<li>Craft Functions を作成する</li>
<li>Craft Hook v2 トリガーを設定する</li>
</ol>
<p>順番に説明します。</p>
<p>まず、手順1,2,4は以前に投稿した記事、<br>
「<a href="https://solution.plaid.co.jp/202307-hookv2-slack-integration">KARTE CraftでKARTEの接客ステータス変更時にSlack通知をする</a>」<br>
の同見出しの手順と全く同じです。ここでは、手順3,5,6を説明します。</p>
<h2 id="3. API v2アプリを作成する">3. API v2アプリを作成する</h2>
<p>Assign Hookを利用するためのAPI v2アプリを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/80e19272-b6da-44a6-926b-92b10e97683c/%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-12-0115.50.16.png" alt="スクリーンショット2023-12-0115.50.16.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリの種類] を<code>token</code>に設定</li>
<li>Scopeとして<code>talk.operator.get</code>を追加</li>
</ul>
<p>※「アプリの種類」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h2 id="5. Craft Functions を作成する">5. Craft Functions を作成する</h2>
<p>Slackに通知を飛ばすためのCraft Functions のファンクションを作成します。<br>
サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/new-assignment-slack-notification" target="_blank" rel="noreferrer">craft-codes/craft-functions/new-assignment-slack-notification at main · plaidev/craft-codes</a></p>
<p>実装内容は、次のとおりです。</p>
<ol>
<li>Hook v2経由で新しい担当オペレーターの情報を受け取る</li>
<li>Slack に通知するメッセージ内容を作成</li>
<li>Slack API の chat.postMessage を使ってメッセージを送信</li>
</ol>
<p>Craft Functions作成画面のコードタブのコードにサンプルコードのindex.js の内容を貼り付け、モジュール に modules.json の内容を貼り付けます。また、以下の3つをCraft Functions作成画面の変数タブで指定します。</p>
<div class="TableScroll"><table>
<thead>
<tr>
<th>変数名</th>
<th>概要</th>
</tr>
</thead>
<tbody>
<tr>
<td>KARTE_PROJECT_ID</td>
<td>KARTEのプロジェクトID</td>
</tr>
<tr>
<td>SLACK_CHANNEL_ID</td>
<td>送信先のSlackチャンネルID</td>
</tr>
<tr>
<td>SLACK_TOKEN_SECRET</td>
<td>手順4でCraft Secret Managerに登録したSlack アプリの OAuth トークン</td>
</tr>
</tbody>
</table></div>
<p>サンプルコードでは、Slack に通知するメッセージについて、割り当て先が未担当か未担当でないかによって通知するメッセージを出し分けています。</p>
<pre><code class="hljs">  <span class="hljs-keyword">let</span> msg;
  <span class="hljs-keyword">if</span> (operatorName === <span class="hljs-string">'未担当'</span>) {
    msg = <span class="hljs-string">`KARTE Talkのチャットでアサインが「未担当」になりました。\n`</span>;
  } <span class="hljs-keyword">else</span> {
    msg = <span class="hljs-string">`KARTE Talkのチャットでアサインが<span class="hljs-subst">${operatorName}</span>さんになりました。\n`</span>;
  }
  msg += <span class="hljs-string">`新規アサインされた担当のuser_idは<span class="hljs-subst">${assignedUser}</span>です。\n`</span>;
  msg += <span class="hljs-string">`Talk画面はこちらです。https://admin.karte.io/communication/v2/redirect_from_v1/<span class="hljs-subst">${assignedUser}</span>?project=<span class="hljs-subst">${KARTE_PROJECT_ID}</span>`</span>;

  <span class="hljs-comment">// Slack APIのchat.postMessageを使ってメッセージを送信</span>
  <span class="hljs-keyword">await</span> slackClient.<span class="hljs-property">chat</span>.<span class="hljs-title function_">postMessage</span>({
    <span class="hljs-attr">channel</span>: <span class="hljs-variable constant_">SLACK_CHANNEL_ID</span>,
    <span class="hljs-attr">text</span>: msg,
  });

</code></pre>
<h2 id="6. Craft Hook v2 トリガーを設定する">6. Craft Hook v2 トリガーを設定する</h2>
<p>最後にKARTE Talkでオペレータのアサインが変更される度にファンクションが実行されるように Hook v2 の設定をします。 Hook v2 の設定は API v2 アプリ上で行います。</p>
<p><img src="https://ik.imagekit.io/plaid/26d8dc69-5bff-4c0f-adbb-f56b1ec3f9d4/%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-12-0115.54.57.png" alt="スクリーンショット2023-12-0115.54.57.png"></p>
<ul>
<li>「2. API v2 アプリを作成する」で作成したアプリの設定画面を開く</li>
<li>[トリガー設定] に <code>KARTE Talk: オペレータのアサイン時</code> を指定</li>
<li>[チャネル設定 &gt; Craft] を有効化し、先ほど作成したファンクション名を入力</li>
</ul>
<p>これで、担当オペレーターが変更された時に先ほど作成したファンクションが実行され、Slackに通知が飛ぶ設定が完了しました。</p>
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
<p>KARTE Talkで担当者がアサインされた場合にSlack通知する実装が完成しました。<br>
実際に動作を確認してみましょう。</p>
<p>まず、「有効化」にチェックが入っていることを確認します。<br>
<img src="https://ik.imagekit.io/plaid/1b8f0459-cf97-42ea-9875-00d53536d13d/%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-12-0115.40.54.png" alt="スクリーンショット2023-12-0115.40.54.png"></p>
<p>KARTE Talk画面を開き、担当者を未担当から適当に変更してみます。<br>
<img src="https://ik.imagekit.io/plaid/8773576b-466c-4f94-a75a-4118fb42aa8d/%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-12-1113.27.15.png" alt="スクリーンショット2023-12-1113.27.15.png"></p>
<p>指定した Slack チャンネルに作成した Slack アプリから通知が飛んできました。<br>
<img src="https://ik.imagekit.io/plaid/ff6ee934-c2e0-4210-9e9f-a38751cca96c/%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-12-1118.26.24.png" alt="スクリーンショット2023-12-1118.26.24.png"></p>
<h1 id="おわりに">おわりに</h1>
<p>今回は「KARTE Talkで担当者がアサインされた場合にSlack通知する」方法を紹介しました。<br>
他にも、Talkのメッセージ送信時など各種トリガーからファンクションの実行が可能となっており、様々な応用が可能です。</p>
<p>ぜひ皆さんも、お試しくださいませ！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</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 Craftを使って「KARTE Talkで担当者がアサインされた場合にSlack通知する」方法について紹介します。