Instagram Channel

実際の利用者が主に Instagram Direct Message でブランドとやり取りしており、Agent に Instagram DM 上で直接返信させたい場合は Instagram channel を使います。

Codeer で Instagram を live にするうえで本当に重要なのは Webhook URL です。Instagram channel の Publish は主に Instagram webhook event の処理を開始するかどうかを切り替える役割で、実際の返答は紐づけた Agent の最新の公開済みバージョンが返します。

始める前に必要なもの

少なくとも一度 publish 済みの Agent
workspace の channel 編集権限
Instagram Business または Creator account
その Instagram account が、管理できる Facebook Page に接続されていること
Meta app
その Meta app で使える Instagram messaging 設定
Instagram メッセージを送信できる access token
外部公開された HTTPS の Codeer 環境

公開 HTTPS が必要な理由

Meta は外部から到達できる HTTPS webhook だけを受け付けます。Codeer の Webhook URL が公開 HTTPS で到達できない場合、Meta の webhook verify で失敗します。

Meta 側で準備するもの

Meta app
Instagram Business または Creator account
その Instagram account に接続された Facebook Page
Instagram messaging 関連設定
callback URL が Codeer の Webhook URL を指す webhook 設定
その Instagram account の messaging event subscription
Instagram メッセージを送信できる access token

Instagram Account ID、token、webhook subscription を同じ account にそろえる

Codeer は、受信した webhook event がこの channel のものかを Instagram Account ID で確認します。Account ID、access token、webhook subscription が同じ Instagram account に属していない場合、メッセージが無視されたり、Codeer が返信できなかったりします。

完全セットアップ手順

先に Codeer で Instagram channel を作成し、Webhook URL をコピーする
- 先に Codeer の Editor で対象 Agent を publish します。
- Channels を開きます。
- New Channel を押します。
- Instagram を選びます。
- 安定した Name と Slug を設定します。
- Instagram channel の Configuration で Webhook URL をコピーします。
- この時点では Codeer の Instagram channel をまだ publish しません。先に Meta 側で必要な値を集めて Codeer に保存し、その後 Meta に戻って webhook を設定・verify してください。
Instagram account の状態を確認する
- 対象 Instagram account が Business または Creator account であることを確認します。
- Facebook Page に接続されていることを確認します。
- あなたの Meta account に、その Instagram account と接続先 Page を管理する権限があることを確認します。
Instagram messaging の権限は通常、接続された Facebook Page 経由で管理されます

Meta 上で対象 Instagram account が見つからない場合は、まず Instagram account が professional account になっているか、正しい Page に接続されているか、Meta Business 権限にその asset が含まれているかを確認してください。
Meta app に Instagram messaging 設定を追加する
- Meta for Developers を開きます。
- Instagram DM に使う Meta app を開きます。
- Instagram product または messaging use case を追加します。
- ユーザーが DM を送る Instagram Business / Creator account を接続します。
- その app が Instagram account のメッセージを受信・送信できる権限を持っていることを確認します。
Meta dashboard の表示名は変わることがあります

Meta は App Dashboard の navigation や use case 名を随時変更します。重要なのは、app が正しい Instagram account に接続されていること、webhook verify が通ること、token が Instagram メッセージを送信できることです。
Instagram Account ID を取得する
- Meta App Dashboard、Instagram account settings、または Graph API tooling で対象 Instagram Business account ID を探します。
- この ID は通常、17841400000000000 のような長い数字です。
- その ID をコピーします。あとで Codeer の Instagram Account ID に貼り付けます。
Webhook Verify Token を作成する
- この channel 専用の Webhook Verify Token として、推測されにくい文字列を作ります。
- 控えておいてください。Meta の webhook 設定と Codeer フォームに同じ値を入力します。
Verify Token は access token ではありません

Webhook Verify Token は、Meta の webhook verify 用に自分で決める共有文字列です。Access Token は、Codeer が Instagram メッセージを送信するための token です。混同しないでください。
Meta App Secret をコピーする
- Meta App Dashboard で App Settings > Basic を開きます。
- App Secret を探してコピーします。
- あとで Codeer の Meta App Secret に貼り付けます。
Codeer は App Secret で webhook signature を検証します

Instagram webhook が Codeer に届くと、Codeer は Meta App Secret を使って X-Hub-Signature-256 を検証します。App Secret が違う場合、event は無視されます。
Instagram メッセージを送信できる access token を作成または取得する
- Meta App Dashboard、Graph API Explorer、または既存の Meta token flow で、Instagram メッセージを送信できる access token を取得します。
- token が、Codeer に Instagram Account ID として入力する Instagram account と同じ account に属していることを確認します。
- あとで Codeer の Access Token に貼り付けます。
本番公開前に token と権限状態を確認する

app が development mode のまま、または test token しかない場合、app roles を持つ人だけがテストできることがあります。一般ユーザーに提供する前に、Meta app、権限、token が本番 rollout 方針に合っていることを確認してください。
Codeer で Instagram 設定を保存する
- Codeer の Instagram channel に戻ります。
- Configuration に次を入力します。
  - Instagram Account ID
  - Webhook Verify Token
  - Meta App Secret
  - Access Token
- Instagram DM に応答する publish 済み Agent を選びます。
- 設定を保存します。
Meta で webhook を verify する前に Verify Token を保存してください

Meta が webhook を verify するとき、Meta は Codeer の Webhook URL を呼び出し、Meta 側で入力した verify token を渡します。Codeer は channel に保存済みの Webhook Verify Token と照合するため、この手順は Meta の verify / save より前に必要です。

選択できるのは publish 済み Agent だけです

Agent が一覧に出ない場合は、Editor に戻って publish してから、再度 Instagram channel ページに戻ってください。
Meta で webhook を設定する
- Meta app の Instagram / Webhooks 設定で callback を追加します。
- Callback URL に Codeer の Webhook URL を貼り付けます。
- 先ほど作成した Webhook Verify Token を入力します。
- Meta 側で verify / save を実行します。
- verify が成功したら、メッセージを受け取る Instagram account を subscribe します。
- Codeer がユーザーからの DM を受信できるように、少なくとも Instagram messaging event を subscribe します。
Codeer の Instagram channel を publish する
- webhook、Instagram Account ID、認証情報、Agent binding がそろったら channel を publish します。
- 新しい Instagram event の処理を止めたい場合は Unpublish を使います。

最初の live テスト

より多くの人に共有する前に、実際の Instagram account で一通り確認します。

対象 Instagram account の DM を開きます。
実際に近い text message を送ります。
Instagram DM で Agent の返信を受け取れることを確認します。
Codeer の Histories に戻り、会話が記録されていることを確認します。
返信が、紐づけた Agent の最新 publish 済み version から来ていることを確認します。

Troubleshooting

Instagram は接続できているのに返答が想定と違う場合は、次の順で確認してください。

正しい Agent version が publish 済みか。
Instagram channel が publish 済みか。
Meta webhook verify が成功しているか。
webhook が正しい Instagram account を subscribe しているか。
Instagram Account ID が webhook event と access token と同じ Instagram account に属しているか。
Instagram account が Business または Creator account で、正しい Facebook Page に接続されているか。
Webhook Verify Token が Meta webhook 設定の値と完全に一致しているか。
Meta App Secret が同じ Meta app のものか。
Access Token がまだ有効で、Instagram メッセージを送信できるか。