Intercom

2026年版 Intercom API と Slack API 完全ガイドと連携方法

ⓘ本ページはプロモーションが含まれています

お得なお知らせ

スポンサードリンク
タイプ別にすぐ選べる

2026年、ビジネス競争力を上げる2ルート

"組織を動かす"立場と"個人スキルを伸ばす"立場では必要な打ち手が違います。自分の役割で選んでください。

▷ 部門・全社でAIリテラシー研修を入れたい管理職・人事・経営層

【Kindle本】イノベーションOps 組織を動かすDX&AI導入プロセスのすべて

▷ 個人のビジネススキル・思考法を"本から"底上げしたい実務担当者

Kindle Unlimited 30日間無料で200万冊が読み放題 Kindle Unlimited 30日無料|ビジネス書読み放題▶

※積極的な自己学習が成長への近道です

▶ 耳で学ぶビジネススキルなら オーディオブックAudible 。日経BP・東洋経済系の話題作も対象です。


スポンサードリンク

1. API 概要と認証方式

このセクションでは、Intercom と Slack が提供する REST/GraphQL エンドポイントと、2026 年時点で推奨されている認証フローを把握します。正しいバージョン管理とトークン取り扱いは、後続の実装全体に影響を与えるため必読です。

1‑1. Intercom API の最新情報

Intercom の公式ドキュメント(2026‑07 更新)によれば、REST API は v2.0 系列が唯一のサポート対象となっており、旧バージョン(v1.x)は完全に非推奨です。また、OAuth 2.0 の Authorization Code Grant フローは 2025 年末に廃止され、現在は Personal Access Token (PAT) のみが利用可能です。

項目 内容
ベース URL https://api.intercom.io(HTTPS 必須)
推奨エンドポイント例 /contacts, /conversations, /companies (すべて v2.0 に統合)
認証方式 Bearer TokenAuthorization: Bearer <PAT> ヘッダーで送信
トークン取得場所 Intercom 管理画面 → Developer HubPersonal Access Tokens
有効期限・ローテーション 無期限だが、セキュリティポリシーに従い 90 日ごと の再発行を推奨

注記:OAuth が廃止されたことに伴い、サードパーティ製の SDK でも内部的に PAT に置き換えるアップデートが必要です。

1‑2. Slack API の最新スコープと認証フロー

Slack は依然として OAuth 2.0 を採用していますが、2026 年版では「Bot Token Scopes」のみで十分に機能します。実装時に最小権限の原則(Principle of Least Privilege)を守るため、以下のスコープを最低限付与してください。

スコープ 主な利用シーン
chat:write チャンネル・DM へのメッセージ送信
channels:read パブリックチャンネル情報取得
groups:read プライベートチャンネル(グループ)情報取得
im:read / mpim:read ダイレクトメッセージ・マルチパーティ DM の読み取り(通知対象の絞り込みに有用)
reactions:write (任意) メッセージへのリアクション付与

認証フローは次の手順です。

  1. アプリ作成https://api.slack.com/apps
  2. OAuth & Permissions タブで上記スコープを設定し、Redirect URL を登録
  3. インストール時に生成される Bot User OAuth Tokenxoxb-…)を環境変数で管理

Slack の公式ドキュメントは随時更新されますので、実装直前に必ず最新スコープ一覧を確認してください。


2. Webhook 設定とペイロード例

Intercom のイベントをリアルタイムで取得し、Slack に転送するための設定手順と、代表的な conversation.createdcompany.created ペイロード構造を示します。Webhook は署名検証が必須です。

2‑1. conversation.created の設定手順

Intercom の管理画面から対象イベントの Webhook を作成し、受信エンドポイントを自サーバーに指定します。

  1. Settings > Webhooks に移動
  2. 「Add webhook」 → イベント種別で conversation.created を選択
  3. 配信先 URL(例:https://example.com/intercom/webhook)を入力
  4. 任意で 署名シークレット を生成し、保存

ポイント:テストペイロード送信機能で受信サーバーの 200 OK 応答が確認できたら設定完了です。

ペイロード例(抜粋)

  • topic:イベント種別
  • id:会話 ID(冪等性チェックに使用)
  • conversation_message.body:本文テキスト

2‑2. company.created の設定手順

手順は上記と同様です。対象イベントだけを選択すれば、不要な通知を抑制できます。

ペイロード例(抜粋)

  • name:会社名
  • custom_attributes:任意の顧客属性(後続ロジックで利用可能)

ベストプラクティス:受信サーバーは HMAC‑SHA256 による署名検証を必ず実装し、改ざんや偽装を防止してください。


3. ノーコード統合の選択肢(中立的に紹介)

プログラミング不要で Intercom → Slack の通知フローを構築したい場合、主に ZapierMake (旧 Integromat) が利用されます。ここではそれぞれの設定手順と注意点だけを記載し、特定ベンダーへの過度な宣伝は控えています。

3‑1. Zapier を利用した構成

  1. Zapier のダッシュボードで 「Create Zap」
  2. TriggerIntercom – New Conversation(または New Event)を選択し、PAT を入力
  3. Action として Slack – Send Channel Message を設定。メッセージテンプレートに {{conversation_message.body}} などのプレースホルダーをマッピング
  4. テスト実行で Slack に期待通りのテキストが届けば、Zap を有効化

留意点:無料プランは月間 100 タスクまで。大量通知が必要な場合は有料プランへの移行が必須です。

3‑2. Make (Integromat) を利用した構成

  1. Make の「Create a new scenario」画面で Intercom – Watch Events モジュールを追加
  2. 対象イベントとして conversation.createdcompany.created を選択し、PAT で認証
  3. 次に Slack – Create a Message モジュールを接続。チャンネル ID とメッセージ本文(例:{{payload.conversation_message.body}})をマッピング
  4. Error handling タブでリトライ回数(最大 5 回)と指数バックオフの待機時間を設定し、レートリミット超過時に自動再試行できるようにする

留意点:無料プランは月間 1,000 操作まで。シナリオ実行頻度が高い場合は「フィルタ」モジュールで不要なイベントを除外し、コスト削減を図ります。


4. カスタム実装(Node.js と Python)

プログラムレベルの柔軟性が必要なケース向けに、Node.jsPython のサンプルコードと、実運用で推奨されるエラーハンドリング・リトライロジックを併せて提示します。

4‑1. Node.js 実装例と詳細なエラーハンドリング

ポイント解説

項目 実装内容
署名検証 crypto.timingSafeEqual で定数時間比較し、タイミング攻撃を防止
冪等性 未処理のイベントは 200 OK を返すだけに留め、重複通知はサーバ側で ID 管理(例:Redis Set)して防止
リトライ戦略 bullmq キューへ 指数バックオフ + jitter(内部実装)を設定し、レートリミットや 5xx エラーに自動再送
ログ・モニタリング console.error の代わりに Cloud Logging 等の構造化ログへ出力することが推奨

4‑2. Python 実装例と同等のハンドリング

  • リトライ実装rqRetry により指数バックオフ(1 → 2 → 4 → 8 → 16 秒)を自動適用。
  • エラーログは外部のロギングサービスへ出力することが望ましいです。

5. エラー処理・リトライ戦略とセキュリティベストプラクティス

5‑1. HTTP ステータス別ハンドリング表

ステータス 推奨アクション
200‑299 正常完了 → 成功ログを残す
400 署名不正・リクエストフォーマットエラー → ログのみ、再送は不要
401 / 403 トークン無効またはスコープ不足 → 管理者へ即時アラート(PagerDuty 等)
429 レートリミット超過 → 指数バックオフ + jitter(最小 1 s、最大 30 s)で再試行
500‑504 サーバー障害 → 最大 5 回 のリトライ後にキューへ永続化し、手動対応を促す

5‑2. 冪等性と重複排除

  • イベント ID(id)をキーに Redis Set を使用し、受信済み ID が存在する場合は即座に 200 OK を返すだけに留める。
  • 同一会話が複数回通知されないよう、Slack 側でも thread_ts を利用してスレッド化すると管理しやすい。

5‑3. リトライ実装例(指数バックオフ+ジッター)

  • Node.jssetTimeout(() => fn(), exponentialBackoff(attempt))
  • Pythontime.sleep(exponential_backoff(attempt))

5‑4. セキュリティ対策まとめ

項目 実装例
署名検証 HMAC‑SHA256(Intercom)・Signing Secret(Slack Events API)を使用
最小権限 Intercom は read:contacts, read:conversations; Slack は chat:write のみ付与
シークレット管理 Cloud Run → Secret Manager、Heroku → Config Vars、K8s → Secrets Store
トークンローテーション 90 日ごとに自動生成スクリプトを走らせ、旧トークンは即削除
監査ログ 受信・送信のリクエスト/レスポンスヘッダーを構造化ログで永続化(保持期間最低 90 日)

6. テスト、デプロイ、運用チェックリスト

6‑1. ローカル開発と自動テスト

  1. ngrok でローカルサーバーを外部公開し、Intercom の「Test webhook」から実際のペイロードを送信
  2. ユニットテスト(Jest / pytest)に以下シナリオを必ず含める
  3. 正常系:有効署名 → Slack へメッセージが届くか
  4. 異常系①:無効署名 → 400 が返るか
  5. 異常系②:Slack API で 429 発生時にリトライロジックが作動するか
  6. CI/CD(GitHub Actions)例

6‑2. デプロイ先別設定例

環境 Dockerfile / Procfile の要点
Heroku web: node index.js または web: gunicorn app:app(Python)
Cloud Run 上記 Dockerfile をビルドし、--allow-unauthenticated フラグで公開。環境変数は Secret Manager 経由で注入
AWS Lambda (Node.js) serverless.yml で HTTP API としてデプロイ、aws lambda invoke のリトライは Lambda の再試行設定でカバー

6‑3. 運用時のモニタリングと定期メンテナンス

項目 推奨ツール・チェック項目
ログ集約 Cloud Logging / Papertrail → severity:ERROR が一定時間以上続くとアラート
パフォーマンス指標 受信レイテンシ < 500 ms、Slack 送信成功率 > 99%
トークン有効期限 Cron ジョブで curl https://api.intercom.io/me を実行し 401 が返ったら自動通知
重複検知 Redis Set のサイズを定期的にモニタリングし、閾値超過時は TTL 設定の見直し
障害復旧手順 1) キュー残数確認 → 2) 手動リトライスクリプト実行 → 3) 必要ならデプロイロールバック

終わりに

本ガイドは、2026 年時点での Intercom API(PAT)Slack Bot Token を組み合わせて安全かつ拡張性のある通知基盤を構築するための包括的なロードマップです。

  • API バージョン・認証方式は公式ドキュメントの更新に随時追従してください。
  • エラーハンドリングとリトライは指数バックオフ+ジッターで実装し、レートリミットやサーバ障害への耐性を確保します。
  • セキュリティは署名検証・最小権限・シークレット管理の 3 本柱を徹底し、外部連携リスクを最小化します。

この手順をベースに、組織固有の要件(多言語対応、カスタム属性マッピングなど)へ段階的に拡張すれば、長期にわたって安定した顧客サポートフローを実現できます。


本稿は 2026 年 7 月時点の公開情報に基づき執筆しています。API の破壊的変更や新しい認証方式が追加された場合は、速やかに公式リファレンスをご確認ください。

スポンサードリンク

お得なお知らせ

スポンサードリンク
タイプ別にすぐ選べる

2026年、ビジネス競争力を上げる2ルート

"組織を動かす"立場と"個人スキルを伸ばす"立場では必要な打ち手が違います。自分の役割で選んでください。

▷ 部門・全社でAIリテラシー研修を入れたい管理職・人事・経営層

【Kindle本】イノベーションOps 組織を動かすDX&AI導入プロセスのすべて

▷ 個人のビジネススキル・思考法を"本から"底上げしたい実務担当者

Kindle Unlimited 30日間無料で200万冊が読み放題 Kindle Unlimited 30日無料|ビジネス書読み放題▶

※積極的な自己学習が成長への近道です

▶ 耳で学ぶビジネススキルなら オーディオブックAudible 。日経BP・東洋経済系の話題作も対象です。


-Intercom