SlackからKARTEの接客サービスの公開／非公開状態を切り替える

<html><head></head><body>こんにちは、Customer Engineerの島本です！ 
こないだ錦糸町にある黄金湯に行ってきたのですが、 
女湯はコンパクトな作りのためセルフロウリュウでアツアツにできてとても良かったです！ 
<img src="https://ik.imagekit.io/plaid/bb207543-cf14-430d-bf7a-79ec1941f2de/IMG_1383.jpg" alt="IMG_1383.jpg">
さて、KARTE をサイトの障害やメンテナンス情報といった急を要するような情報をユーザーに届けるために活用頂いている方も多いかと思いますが、その場合常にKARTE の管理画面にアクセスできる状態でないといけないという制約が発生します。
そんな時に、「KARTE の管理画面以外から接客サービスの公開非公開を変えたいな。社内のコミュニケーションツール使って変えられたら楽なのに」と思ったことはありませんか？
なんと、KARTE Craft を使うことで外部サービスからKARTE の接客サービスの公開非公開を変えることを実現できます！
今回は「Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える」方法について紹介します。イメージとしてはこんな感じです。 
<img src="https://ik.imagekit.io/plaid/e57b8788-01af-42cb-86e5-bb7142fc1377/%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-09-0422.51.59.png" alt="スクリーンショット2023-09-0422.51.59.png">
<h1 id="処理の流れ">処理の流れ</h1>
全体の処理の流れは、次の通りです。 
<img src="https://ik.imagekit.io/plaid/cff24487-efb7-4ba0-bf26-7ef96349dd72/ms-teams-change-campaign-status.png" alt="ms-teams-change-campaign-status.png">
実現する上で必要なプロダクトやオプションは以下になります。
<ul>
<li><a href="https://karte.io/" target="_blank" rel="noreferrer">KARTE</a></li>
<li><a href="https://ecosystem.plaid.co.jp/product/karte-craft" target="_blank" rel="noreferrer">KARTE Craft</a></li>
</ul>
また、Craft Functions とMicrosoft Teams との連携では次の3つの機能を利用します。
<ul>
<li><a href="https://learn.microsoft.com/ja-jp/microsoftteams/platform/webhooks-and-connectors/how-to/add-outgoing-webhook?tabs=urljsonpayload%2Cdotnet" target="_blank" rel="noreferrer">Teams 送信 Webhook</a>
<ul>
<li>@メンションを使用してチャネル内のメッセージを外部サービスに送信し応答する</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/endpoint" target="_blank" rel="noreferrer">Craft Endpoint トリガー</a>
<ul>
<li>Craft Functionを実行するためのHTTPエンドポイント</li>
</ul>
</li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-toggleenabled" target="_blank" rel="noreferrer">Toggle campaign's enabled status API</a>
<ul>
<li>接客サービスの公開・非公開を制御するAPI</li>
</ul>
</li>
</ul>
<h1 id="実装手順">実装手順</h1>
実装の手順は次の通りです。 
大きく分けてTeams 側と KARTE 側のそれぞれの設定があります。
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Craft Functions の エンドポイントURLを作成する</li>
<li>Teams でチームを作成する</li>
<li>Teams で作成したチームに送信 Webhookを作成する</li>
<li>Teams 送信 Webhookの HMAC トークンを Craft Secret Manager に登録する</li>
<li>Craft Functions を作成する</li>
</ol>
順番に見てみましょう。
<h2 id="1. API v2 アプリを作成する">1. API v2 アプリを作成する</h2>
まず、Toggle campaign's enabled status API を利用するためのAPI v2アプリを作成します。 
<img src="https://ik.imagekit.io/plaid/bfe2f6a8-b78c-4c95-ad91-db59ecc03a9b/image(5).png" alt="image(5).png">
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を&nbsp;<code>token</code>&nbsp;に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.toggleEnabled</code>: API に必要</li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンを控えておく</li>
</ul>
「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。
<h2 id="2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する">2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h2>
API v2 アプリのアクセストークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要が無くなります。 
<img src="https://ik.imagekit.io/plaid/116765b1-4d21-4d74-8d3e-e5a4e4431e5b/image(6).png" alt="image(6).png">
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたアクセストークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。
<h2 id="3. Craft Functions の エンドポイントURLを作成する">3. Craft Functions の エンドポイントURLを作成する</h2>
Craft Functionsを作成して一度保存した後に、エンドポイント設定からURLを作成します。 
<img src="https://ik.imagekit.io/plaid/a1c8021e-4690-40ad-8e91-2efb5cad5176/image(7).png" alt="image(7).png">
作成したエンドポイントURLはTeams で作成する送信 WebhookのコールバックURLに記載します。
<h2 id="4. Teams でチームを作成する">4. Teams でチームを作成する</h2>
チームを作成してKARTE の接客サービスのステータスを変更するメンバーを追加します。
<h2 id="5. Teams で作成したチームに送信 Webhookを作成する">5. Teams で作成したチームに送信 Webhookを作成する</h2>
KARTE Craftにメッセージを送信するための送信 Webhookを作成します。 
コールバック URLには先程控えておいたCraft Functions の エンドポイントURLを記載します。
<ul>
<li>
送信 Webhook を作成するチームを選択し、[チームを管理 &gt; アプリ] から<code>送信 Webhook を作成</code>をクリック
</li>
<li>
次の画面で アプリの詳細を設定 
<img src="https://ik.imagekit.io/plaid/11d09e63-5f7f-4e09-8f06-995e14d4acf3/%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-09-0413.15.32.png" alt="スクリーンショット2023-09-0413.15.32.png">
<ul>
<li>名前
<ul>
<li>Webhook タイトルと @メンション タブ</li>
</ul>
</li>
<li>コールバック URL
<ul>
<li>Craft Functions の エンドポイントURL</li>
</ul>
</li>
<li>説明
<ul>
<li>プロファイル カードとチーム レベルのアプリ ダッシュボードに表示される詳細な説明文</li>
</ul>
</li>
<li>プロフィール画像
<ul>
<li>Webhook のアプリ アイコン (省略可能)</li>
</ul>
</li>
</ul>
</li>
<li>
作成をクリックするとハッシュ ベースのメッセージ認証コード (HMAC) ダイアログが表示されるため、セキュリティトークンを控えておく 
<img src="https://ik.imagekit.io/plaid/da0179b4-9498-49b4-bb12-dbc41336dec9/%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-09-0413.44.42.png" alt="スクリーンショット2023-09-0413.44.42.png">
</li>
</ul>
<h2 id="6. Teams 送信Webhookの HMAC を Craft Secret Manager に登録する">6. Teams 送信Webhookの HMAC を Craft Secret Manager に登録する</h2>
先程と同様に、Teams 送信 WebhookのHMAC トークンを Craft Secret Manager のシークレットとして登録します。
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたHMAC トークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。
<h2 id="7. Craft Functions を作成する">7. Craft Functions を作成する</h2>
Teams から受け取った情報を元に接客サービスの公開非公開を切り替えるためのCraft Functions のファンクションを作成します。 
サンプルとなるソースコードは、GitHubで公開しています。 
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/ms-teams-change-campaign-status" target="_blank" rel="noreferrer">craft-codes/craft-functions/ms-teams-change-campaign-status at main · plaidev/craft-codes · GitHub</a>
実装内容は、次のとおりです。
<ol>
<li>リクエストに含まれるHMAC証明書の認証を行う</li>
<li>Teams からステータスを変更する接客サービスの内容を受け取る</li>
<li>KARTE の接客サービスの公開／非公開を切り替える</li>
<li>Teams にステータスを変更した接客の情報を送信する</li>
</ol>
Craft Functions作成画面のcode に サンプルコードのindex.js の内容を貼り付け、modules に modules.json の内容を貼り付けます。冒頭に以下の2つを定数に指定します。
<ul>
<li>シークレット名
<ul>
<li>KARTE_APP_SECRET_NAME
<ul>
<li>Craft Secret Manager に登録したAPI v2のSecret名を貼り付ける</li>
</ul>
</li>
<li>TEAMS_OUTGOING_WEBHOOK_SECRET_NAME
<ul>
<li>Craft Secret Manager に登録した HMACトークンのSecret名を貼り付ける</li>
</ul>
</li>
</ul>
</li>
</ul>
<pre><code class="hljs">const KARTE_APP_SECRET_NAME = '';
const TEAMS_OUTGOING_WEBHOOK_SECRET_NAME = '';
</code></pre>
以下の場合にはエラーメッセージがTeams に返ってくるようにしていますが、必要に応じて変更してください。
<ul>
<li>HMAC トークンが間違っている場合
<ul>
<li><code>提供された認証情報が無効です。正しい認証情報を提供して再度試してください。</code></li>
</ul>
</li>
<li>接客IDが間違っている／入力されていない場合
<ul>
<li><code>入力データ内に接客サービスIDが見つかりませんでした。</code></li>
</ul>
</li>
<li>ステータスが間違っている／入力されていない場合
<ul>
<li><code>入力データ内にtrue/falseが見つかりませんでした。</code></li>
</ul>
</li>
</ul>
これで、Teams から投稿した際にファンクションが実行され、KARTE の接客のステータスを変更する設定が完了しました。
<h1 id="注意点">注意点</h1>
サンプルコードを使用する場合、いくつか注意点がありますのでご留意ください。
<ul>
<li>KARTE の接客サービスの公開／非公開を切り替えるためには、接客サービス毎のIDとステータス情報が必要になります。サンプルコードでは、Teams から接客サービスIDとステータス情報（true/false）を受け取った場合にステータスを切り替える実装になっているため、事前に対象の接客サービスIDを控えておいてください。</li>
<li>サンプルコードでは1投稿につきステータス変更できる接客はひとつになります。投稿する際に複数の接客サービスIDとステータスを入力しても、最初に入力した方しか変更されないため分けて投稿してください。</li>
<li>Teams 送信 Webhookでは、5秒以内にテキストが返ってこない場合は、<code>Sorry, there was a problem encountered with your request</code>というエラーが返ってきます。Craft Functionsの実行に時間がかかっている場合があるため、上記エラーが返ってきたときには、再度投稿を試してください。</li>
</ul>
以上となります。
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
では、実際に動かしてみましょう！！
まず、対象の接客サービスIDを控えておきます。 
<img src="https://ik.imagekit.io/plaid/995116f2-13a3-41e2-8407-2c0c6a3d2838/%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-09-0515.05.25.png" alt="スクリーンショット2023-09-0515.05.25.png">
現在は停止中なので、Teams から投稿して公開状態に切り替えてみようと思います。
<img src="https://ik.imagekit.io/plaid/e57b8788-01af-42cb-86e5-bb7142fc1377/%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-09-0422.51.59.png" alt="スクリーンショット2023-09-0422.51.59.png"> 
作成した送信 Webhookをメンションして、接客サービスIDとステータス情報を入力して投稿したところ、接客のステータスが変わったと返信がきました！
実際に管理画面で公開状態に切り替わっているか確認してみましょう。 
<img src="https://ik.imagekit.io/plaid/de0f489e-1367-4e9f-8e76-d3adf0ad5dc4/%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-09-0422.53.53.png" alt="スクリーンショット2023-09-0422.53.53.png"> 
接客のステータスが公開中に切り替わっていますね！！
<h1 id="おわりに">おわりに</h1>
今回はCraft Functionを実行するためにCraft Endpoint トリガーを使いましたが、一般的にエンドポイント（URL）が流出すると誰でも叩ける状態になってしまうというセキュリティリスクがあります。
Teams の送信 Webhook にはTeams と指定された外部サービス間の呼び出しを認証するために使用されるHMAC セキュリティトークンが用意されているため、不正な操作を防止することができ、安心して利用できますね。
「うちはTeams じゃなくてSlack 使ってるんだけどなあ」と思ったそこのあなた！ 
安心してください。Slack からでもKARTE 接客サービスの公開／非公開状態を切り替えることできます。
その内容については8月に入社したkoha が執筆してくれますので乞うご期待！！！！！！
※2023/9/12追記 
早速執筆してくれたみたいなのでこちらもぜひご一読ください！ 
<a href="https://solution.plaid.co.jp/202309-slack-change-campaign-status">SlackからKARTEの接客サービスの公開／非公開状態を切り替える</a>
<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 Craftを使って「Microsoft TeamsからKARTEの接客サービスの公開／非公開状態を切り替える」方法について紹介します。