Zendesk Sunshine Conversationsのカスタム統合を構築する方法

Zendesk Sunshine Conversationsでカスタム統合を構築すると、お客様のビジネスニーズに合わせたメッセージングエクスペリエンスを作成できます。独自のCRMを接続したり、特殊なボットを構築したり、複雑な会話フローを調整したりする場合でも、Sunshine Conversations APIは必要な基盤を提供します。

このガイドでは、初期設定から本番環境へのデプロイまですべてを説明します。最後までには、メッセージを受信し、インテリジェントに応答し、必要に応じて人間のエージェントに引き継ぐことができる、動作するWebhookサーバーが完成します。公式リファレンスについては、Zendesk APIドキュメントを参照してください。

エンジニアリング作業をスキップしたい場合は、eesel AIが、数分でZendeskに接続し、自律的に会話を処理するノーコードの代替手段を提供します。

Zendesk Sunshine Conversationsは、WebhookとAPIを介してメッセージングチャネルをビジネスアプリケーションに接続します。

必要なもの

始める前に、次のものが揃っていることを確認してください。

Zendeskの要件：

• Zendesk Suite ProfessionalまたはEnterpriseプラン（Sunshine Conversations APIへのアクセスにはこれらの階層が必要です）
• Zendeskアカウントへの管理者アクセス
• プランに含まれる月間アクティブユーザー（MAU）が1,000人以上（追加のMAUパックは2,500 MAUあたり50ドルで利用可能）

技術的な要件：

• サーバー環境（このガイドではNode.jsを推奨）
• ローカルWebhookテスト用のngrok
• REST APIとWebhookの基本的な知識
• 本番環境用のHTTPSエンドポイント

プラン	年間価格	Sunshineアクセス	含まれるMAU
Suite Team	1エージェントあたり月額55ドル	基本的なメッセージングのみ	N/A
Suite Professional	1エージェントあたり月額115ドル	完全なAPIアクセス	1,000
Suite Enterprise	1エージェントあたり月額169ドル	完全なAPIアクセス	1,000

Sunshine Conversationsのアーキテクチャについて

Sunshine Conversationsは、Zendeskの統合メッセージングプラットフォームです。元々はSmooch.io（2019年にZendeskに買収）で、現在はZendesk Suite全体のメッセージングを強化しています。アーキテクチャは、構築する前に理解しておく必要のあるいくつかの重要な概念を中心に構築されています。

アプリ（Apps）： 各アプリは、ビジネスまたはブランドを表します。管理センターで、すべての会話データを含むアプリを作成します。

統合（Integrations）： これらは、Sunshine Conversationsと外部システム間の接続です。カスタム統合は、Webhookを使用してメッセージを送受信します。

会話（Conversations）： 会話は、ユーザーとビジネス間のメッセージのスレッドです。会話はチャネル間で永続化されます（ユーザーはWebチャットで開始し、WhatsAppで続行できます）。

Switchboard： これは、会話を「所有」する人を制御します。Switchboardは、ボット、エージェント、および統合間で会話をルーティングします。

認証（Authentication）： APIは、セキュリティを強化するために、基本認証（キーIDをユーザー名として、シークレットをパスワードとして）またはJWTトークンを使用します。

フローは次のようになります。顧客は、接続されているチャネル（Webウィジェット、WhatsAppなど）を介してメッセージを送信します。Sunshine Conversationsはメッセージを受信し、Webhook統合に転送します。サーバーはメッセージを処理し、応答方法を決定し、APIを介して応答を返送します。必要に応じて、統合はSwitchboardを介して人間のエージェントに制御を転送できます。

ステップ1：Sunshine ConversationsアプリとAPIキーを作成する

まず、アプリを作成し、API認証情報を生成する必要があります。

Zendesk管理センターに移動します。アプリと統合 > API > Conversations APIに移動します。

APIキーの作成をクリックし、「本番Webhook統合」のようなわかりやすい名前を付けます。次の3つの情報が表示されます。

• アプリID（App ID）： アプリの一意の識別子
• キーID（Key ID）： API認証のユーザー名として使用
• シークレットキー（Secret Key）： API認証のパスワードとして使用

これらの認証情報を安全に保管してください。すべてのAPI呼び出しに必要になります。シークレットキーは一度だけ表示されます。紛失した場合は、新しいキーペアを生成する必要があります。

環境変数を設定して、認証情報がコードから漏洩しないようにします。

export SUNSHINE_APP_ID="your_app_id"
export SUNSHINE_KEY_ID="your_key_id"
export SUNSHINE_SECRET="your_secret_key"

ステップ2：Webhook統合を設定する

次に、メッセージイベントを受信するWebhook統合を作成します。

管理センターで、統合 > Conversations統合に移動します。

統合の作成をクリックし、タイプとしてカスタムを選択します。以下を構成します。

ターゲットURL（Target URL）： ローカル開発の場合は、ngrok URLを使用します（これは次のステップで設定します）。本番環境の場合は、HTTPSエンドポイントを使用します。

トリガー（Triggers）： 受信するイベントを選択します。少なくとも、以下を有効にします。

• conversation:message - すべての受信メッセージを受信します
• postback - ボタンクリックとクイックリプライを受信します
• conversation:start - 新しい会話が開始されたときに通知します

シークレット（Secret）： Webhook署名検証用のランダムな文字列を生成します。これにより、リクエストが実際にZendeskから送信されることが保証されます。

Webhook ID（作成後に表示）と構成した共有シークレットを保存します。署名検証には両方が必要になります。

ステップ3：Webhookサーバーを構築する

メッセージを受信して応答する簡単なExpress.jsサーバーを構築しましょう。

まず、プロジェクトを初期化します。

mkdir sunshine-integration
cd sunshine-integration
npm init -y
npm install express crypto dotenv

index.jsファイルを作成します。

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' }));

// Webhook検証ミドルウェア
function verifyWebhook(req, res, next) {
  const signature = req.headers['x-smooch-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (hash !== signature) {
    return res.status(401).send('Unauthorized');
  }
  next();
}

// 受信メッセージを処理する
app.post('/webhook', verifyWebhook, async (req, res) => {
  const event = JSON.parse(req.body);

  // 受信をすぐに確認する
  res.status(200).send('OK');

  // イベントを処理する
  if (event.trigger === 'message:appUser') {
    await handleUserMessage(event);
  }
});

async function handleUserMessage(event) {
  const message = event.messages[0];
  const userId = event.appUser._id;
  const conversationId = event.conversation._id;

  console.log(`Received: ${message.text} from ${userId}`);

  // 簡単なエコー応答（ロジックを置き換えてください）
  await sendMessage(conversationId, `You said: ${message.text}`);
}

async function sendMessage(conversationId, text) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        author: { type: 'business' },
        content: { type: 'text', text: text }
      })
    }
  );

  if (!response.ok) {
    console.error('Failed to send message:', await response.text());
  }
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

.envファイルを作成します。

SUNSHINE_APP_ID=your_app_id
SUNSHINE_KEY_ID=your_key_id
SUNSHINE_SECRET=your_secret_key
WEBHOOK_SECRET=your_webhook_secret

サーバーを起動します。

node index.js

ステップ4：ngrokでローカルでテストする

Sunshine ConversationsにはパブリックHTTPSエンドポイントが必要なため、ngrokを使用してローカルサーバーを公開します。

ngrokをインストールし、トンネルを開始します。

ngrok http 3000

HTTPS URL（https://abc123.ngrok.ioのようなもの）をコピーします。管理センターで、このURLをターゲットURLとしてWebhook統合を更新します。

Zendesk Webウィジェットまたは接続されているチャネルを介してメッセージを送信して、統合をテストします。メッセージがサーバーコンソールに記録され、ボットがメッセージをエコーバックするはずです。

ステップ5：ボットからエージェントへのハンドオフ用にSwitchboardを構成する

Switchboardは、ボットがメッセージを処理するタイミングと、人間のエージェントが引き継ぐタイミングを制御します。これは、本番環境へのデプロイに不可欠です。

Switchboardの主要な概念：

• 制御のパス（Pass Control）： 所有権を別の統合にすぐに転送します
• 制御の提供（Offer Control）： ターゲットが受け入れるまで制御を共有します
• 制御の解放（Release Control）： 会話をデフォルトの状態に戻します

Switchboard IDを見つけるには：

async function getSwitchboardId() {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/switchboards`,
    {
      headers: { 'Authorization': `Basic ${auth}` }
    }
  );

  const data = await response.json();
  return data.switchboards[0].id;
}

人間のエージェントにエスカレーションするには：

async function escalateToAgent(conversationId, switchboardId, metadata = {}) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/switchboard/passControl`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        switchboardIntegration: 'zd:agentWorkspace', // Zendesk Agent Workspace
        metadata: {
          priority: 'high',
          topic: metadata.topic || 'general',
          ...metadata
        }
      })
    }
  );
}

メタデータを使用して制御を渡すと、Zendeskはチケットフィールドを自動的に入力し、優先度を設定し、トリガーに基づいて適切なチームにルーティングします。

ステップ6：メッセージングチャネルを接続する

統合は、Sunshine Conversationsに接続されているすべてのチャネルで動作します。利用可能なチャネルは次のとおりです。

• Webウィジェット（組み込み）
• WhatsApp Business API
• Facebook Messenger
• Instagram
• Apple Messages for Business
• LINE
• Telegram
• TwilioまたはMessageBird経由のSMS
• AndroidおよびiOS SDK

チャネルを追加するには、管理センター > チャネル > [チャネル名]に移動し、認証手順に従います。各チャネルには特定の要件があります。

• WhatsApp： Meta Businessの認証とWhatsApp Business APIアカウントが必要です
• Facebook/Instagram： Facebook Business Managerを介して接続します
• SMS： 電話番号付きのTwilioまたはMessageBirdアカウントが必要です

接続されると、すべてのメッセージはチャネルに関係なく、同じWebhookエンドポイントを通過します。新しいチャネルをサポートするためにコードを変更する必要はありません。

統合のテストとデバッグ

本番環境に移行する前に、統合を徹底的にテストしてください。

ローカル開発のベストプラクティス：

• デバッグ中にWebhookを再送信するには、ngrokの再生機能を使用します
• 受信したすべてのイベントと実行されたアクションについて、包括的なログを実装します
• テスト会話を作成し、メッセージから応答までの完全なフローを確認します

一般的なエラーと解決策：

エラー	原因	解決策
401 Unauthorized（不正なアクセス）	無効なWebhook署名	WEBHOOK_SECRETが統合設定と一致することを確認します
429 Too Many Requests（リクエストが多すぎます）	レート制限を超えました	指数バックオフを使用して再試行ロジックを実装します
403 Forbidden（アクセス禁止）	無効なAPI認証情報	キーIDとシークレットを確認します
Webhookタイムアウト	サーバーの応答> 10秒	Webhookをすぐに確認し、非同期的に処理します

レート制限： Sunshine Conversationsは、APIリクエストをデフォルトで1分あたり100に制限します。適切な処理を実装します。

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await delay(retryAfter * 1000);
  // リクエストを再試行します
}

会話サイズの制限： 会話には30,000メッセージの制限があります。古い会話をアーカイブして、この制限を下回るようにしてください。

セキュリティのベストプラクティス

本番環境への統合には、追加のセキュリティ対策が必要です。

認証情報の保存： 認証情報をバージョン管理にコミットしないでください。環境変数またはAWS Secrets ManagerやHashiCorp Vaultなどのシークレットマネージャーを使用します。Zendeskは、お客様のデータを保護するために業界標準のセキュリティプラクティスに従っています。

Webhook署名検証： 常にX-Smooch-Signatureヘッダーを検証します。これがないと、誰でも偽のWebhookをエンドポイントに送信できます。

HTTPSのみ： Sunshine Conversationsでは、本番環境のWebhook URLにHTTPSが必要です。有効なSSL証明書を使用してください。

JWT認証： セキュリティを強化するために、基本認証からJWTトークンに切り替えます。

function generateJWT() {
  const header = { alg: 'HS256', typ: 'JWT' };
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    scope: 'app',
    iat: now,
    exp: now + 600 // 10 分
  };

  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const signature = crypto
    .createHmac('sha256', process.env.SUNSHINE_SECRET)
    .update(`${encodedHeader}.${encodedPayload}`)
    .digest('base64url');

  return `${encodedHeader}.${encodedPayload}.${signature}`;
}

APIキーのローテーション： 定期的に新しいキーを生成し、古いキーを取り消します。Sunshine Conversationsは、ダウンタイムなしのローテーションのために複数のアクティブキーをサポートしています。

本番環境へのデプロイ

本番環境に移行する準備ができたら、このチェックリストに従ってください。

本番環境へのデプロイチェックリスト：

• ngrokから永続的なHTTPSエンドポイントに移行します
• 適切なエラー処理と再試行ロジックを実装します
• Webhookの失敗に関する監視とアラートを設定します
• デバッグ用のログ集約を構成します
• 実際のエージェントを使用してSwitchboardハンドオフをテストします
• レート制限がユースケースに影響を与えないことを確認します
• エスカレーションポリシーを文書化します

監視の推奨事項：

統合が正常であることを確認するために、次のメトリックを追跡します。

• Webhook配信成功率（目標：> 99％）
• 平均応答時間（5秒未満に保つ）
• エラータイプ別のエラー率
• チャネル別の会話量

Webhook配信の失敗、高いエラー率、およびレート制限への接近に関するアラートを設定します。

代替手段：より迅速な実装のためのeesel AI

カスタム統合を構築すると、完全に制御できますが、かなりの開発時間と継続的なメンテナンスが必要です。エンジニアリングのオーバーヘッドなしでAI搭載のメッセージングが必要な場合は、eesel AIを代替手段として検討してください。

eesel AIはZendeskに直接接続し、会話フロー全体を自動的に処理します。WebhookとSwitchboardロジックを構築する代わりに、次のことを行うだけです。

1. eesel AIをZendeskアカウントに接続します（ワンクリック統合）
2. 過去のチケット、ヘルプセンター、およびドキュメントでAIエージェントをトレーニングします
3. プレーンな英語でエスカレーションルールを構成します（「請求に関する紛争を財務チームにエスカレーションする」）
4. 本番環境に移行する前に、過去のチケットを使用したサンドボックスでテストします

側面	カスタム統合	eesel AI
セットアップ時間	2〜4週間	数分
必要な技術的専門知識	高（API、Webhook）	低（ノーコード）
AI機能	独自に構築する	LLMで事前に構築済み
メンテナンス	継続的な開発	マネージドサービス
価格モデル	Zendesk MAU +開発コスト	インタラクションごと（月額239〜639ドル）

カスタム統合は、標準パターンに適合しない独自のシステムがある場合や、高度に特殊化された会話フローが必要な場合に適しています。ZendeskにAIメッセージングを追加しようとしているほとんどのチームにとって、eesel AIはメンテナンスを減らし、より迅速な結果をもたらします。eeselの動作を確認するか、無料で試すことができます。

Zendesk Sunshine Conversationsで構築を開始する

Zendesk Sunshine Conversationsでカスタム統合を構築するために必要なものがすべて揃いました。APIキーの作成、Webhookの設定から、Switchboardの処理、本番環境へのデプロイまで、基盤が整っています。

次のステップは、特定のユースケースによって異なります。CRMと統合して顧客データを取得したり、ナレッジベースに接続してインテリジェントな応答を行ったり、メッセージコンテンツに基づいてカスタムルーティングロジックを構築したりできます。

カスタムルートが、チームが今すぐ取り組むことができる以上のエンジニアリングのように感じられる場合は、お手伝いできます。AIエージェントは数分でZendeskと統合し、必要に応じてチームにエスカレーションしながら、自律的に会話を処理します。eeselを無料で試すことができ、過去のチケットでテストして、本番環境に移行する前にどのように機能するかを正確に確認できます。