KARTE Talkのエンドユーザーとのチャット対応をSlack経由でできるようにする

<html><head></head><body><p>こんにちは、Customer Engineerのgamiです！最近はスプラトゥーン3の「サイド・オーダー」を楽しみにしています。</p>
<p>さて、KARTE Talkではユーザーとチャットのやりとりをすることができますが、問い合わせの調査や対応を外部のチケット管理ツールで行う運用も一般的です。たとえばプレイドではGitHub Issuesを使って調査のエスカレーションやログの記録をしています。そのとき、GitHubのIssue側での変化を関連するトーク画面のノートに通知できると、たとえばIssueが解決したことをトーク画面側で素早く検知してユーザーにチャットで報告することができます。</p>
<p>そこで今回は、関連するGitHub Issueがopen/closeされたらKARTE Talkに通知する方法について紹介します。</p>
<h1 id="アウトプットイメージ">アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは次の通りです。</p>
<p>特定ユーザーとのトーク画面URLがトップコメントに貼られたGitHub Issueがopen/closeされた場合、<br>
<img src="https://ik.imagekit.io/plaid/150dbb1a-78a9-48b7-8e7c-09938bf72e24/%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-1716.42.43.png" alt="スクリーンショット2024-02-1716.42.43.png"></p>
<p>そのユーザーとのトーク画面のノートに通知されます。<br>
<img src="https://ik.imagekit.io/plaid/c02e307a-2ba2-4919-9d23-6e434b81f854/%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-1716.40.06.png" alt="スクリーンショット2024-02-1716.40.06.png"></p>
<p>構成図は次の通り。</p>
<p><img src="https://ik.imagekit.io/plaid/aa15ee30-e05d-431b-8034-c230a2f5833e/%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-1716.48.50.png" alt="スクリーンショット2024-02-1716.48.50.png"></p>
<p>GitHubのWebhookリクエストをCraft Functionsのエンドポイントに連携し、KARTE TalkのAPIを使ってノート投稿します。</p>
<h1 id="注意点">注意点</h1>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>KARTE TalkおよびGitHub Issueをすでに利用していることを前提とします</li>
<li>Craft Functions実行時に受け取るデータのサイズには上限があります。GitHub Webhookから受け取るデータサイズは比較的大きいため、上限を超える場合はKARTE Craft側での上限緩和が必要になります
<ul>
<li>参考: <a href="https://craft.developers.karte.io/craft-functions/triggers/data-format/index.html" target="_blank" rel="noreferrer">Function実行時に受け取るデータ | KARTE Craft Developer Portal</a></li>
</ul>
</li>
</ul>
<h1 id="設定手順">設定手順</h1>
<p>設定の手順は次の通りです。</p>
<ol>
<li>KARTE Talkのボットを作成する</li>
<li>API v2 アプリを作成する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>GitHubのWebhookを追加する</li>
</ol>
<p>順番に見てみましょう。</p>
<h2 id="1. KARTE Talkのボットを作成する">1. KARTE Talkのボットを作成する</h2>
<p>GitHubからの通知をノート投稿するために、KARTE Talkのボットを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/5e7a1fa2-1535-4ca7-8f8b-aee6a2b9ee5d/%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-1714.55.17.png" alt="スクリーンショット2024-02-1714.55.17.png"></p>
<ul>
<li>KARTE管理画面の[トーク &gt; トーク設定 &gt; ボット管理 &gt; 作成] から適当な名前でボットを作成する</li>
<li>作成したボットのBot Idをコピーする</li>
</ul>
<h2 id="2. API v2 アプリを作成する">2. API v2 アプリを作成する</h2>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。<br>
<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>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.talk.note.send</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをコピーしておく</li>
</ul>
<h2 id="3. Craft Functionsのファンクションを作成する">3. 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>関連するGitHub Issueの変更をKARTE Talkのノートに通知する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベルを指定</li>
</ul>
</li>
<li><code>KARTE_PROJECT_ID</code>
<ul>
<li>通知先KARTEプロジェクトのプロジェクトID</li>
<li>Talk画面URLの <code>?project=xxxx</code> の部分</li>
</ul>
</li>
<li><code>TALK_BOT_ID</code>
<ul>
<li>コピーしたBot Id</li>
</ul>
</li>
<li><code>KARTE_APP_TOKEN_SECRET</code>
<ul>
<li>コピーしたアクセストークン</li>
</ul>
</li>
</ul>
</li>
<li>[設定] タブで [ファンクションの有効化] にチェックを付けて [保存]</li>
</ul>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/github-to-talk-notification" target="_blank" rel="noreferrer">craft-codes/craft-functions/github-to-talk-notification at main · plaidev/craft-codes</a></p>
<h2 id="4. Craft Functionsのエンドポイントを作成する">4. 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="5. GitHubのWebhookを追加する">5. GitHubのWebhookを追加する</h2>
<p>GitHubのIssue側の変更をCraft Functionsに連携するために、GitHub側でWebhookを追加します。</p>
<p><img src="https://ik.imagekit.io/plaid/17d4d1d3-5d17-40c7-b2bd-696f222a549b/%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-1716.30.13.png" alt="スクリーンショット2024-02-1716.30.13.png"></p>
<ul>
<li>GitHubの対象リポジトリの画面で、[Settings &gt; Webhooks &gt; Add Webhook] からWebhookを作成</li>
<li>次の内容を入力して保存
<ul>
<li>Payload URL
<ul>
<li>コピーしたCraft FunctionsのエンドポイントURLを入力</li>
</ul>
</li>
<li>Content type
<ul>
<li>[application/json] を選択</li>
</ul>
</li>
<li>Which events would you like to trigger this webhook?
<ul>
<li>[Let me select individual events. &gt; Issues] を選択</li>
</ul>
</li>
</ul>
</li>
</ul>
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<p>問題なく設定できていれば、特定ユーザーとのトーク画面URLがトップコメントに貼られたGitHub Issueがopen/closeされた場合、<br>
<img src="https://ik.imagekit.io/plaid/150dbb1a-78a9-48b7-8e7c-09938bf72e24/%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-1716.42.43.png" alt="スクリーンショット2024-02-1716.42.43.png"></p>
<p>そのユーザーとのトーク画面のノートに通知されるはずです。<br>
<img src="https://ik.imagekit.io/plaid/c02e307a-2ba2-4919-9d23-6e434b81f854/%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-1716.40.06.png" alt="スクリーンショット2024-02-1716.40.06.png"></p>
<p>正しく通知されない場合は、ファンクションのログをご確認ください。特に <code>message size is over maximum message size</code> というエラーログが出ている場合は、「注意点」に記載した通り、Craft Functions実行時に受け取るデータのサイズの上限に抵触しているため、上限の緩和が必要です。</p>
<h1 id="おわりに">おわりに</h1>
<p>今回は関連するGitHub Issueがopen/closeされたらKARTE Talkにノート投稿でお知らせする方法について紹介しました。</p>
<p>問い合わせ対応のエスカレーションをGitHub Issuesでやっている場合、トーク画面上でGitHub Issues側の進捗を確認できるのは非常に便利です。また、GitHubに限らず同様のWebhookの仕組みがあるチケット管理ツールでもCraft Functionsを使うと同じような連携が実現可能です。</p>
<p>ぜひ皆さんも試してみてください！</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 Talkではユーザーとチャットのやりとりをすることができますが、問い合わせの調査や対応を外部のチケット管理ツールで行う運用も一般的です。今回は、関連するGitHub Issueがopen/closeされたらKARTE Talkに通知する方法について紹介します。