Zendesk Switchboardでカスタムボットを構築する方法：開発者向けガイド

Zendeskのメッセージングインフラストラクチャと直接連携するカスタムボットを構築する必要がある場合は、Zendesk Switchboardを使用する必要があります。このルーティングレイヤーは、Sunshine Conversations内で、どのシステム（ボット、サードパーティAI、または人間のエージェント）が各顧客との会話を制御するかを決定します。

カスタム連携を構築すると、最大限の柔軟性が得られます。ロジック、引き継ぎルール、およびボットが異なるチャネルでどのように動作するかを制御できます。ただし、開発リソースと継続的なメンテナンスも必要になります。

APIの複雑さを伴わずに自動化を必要とするチームには、より簡単な方法があります。 Switchboardの構成を必要とせずに、ボットのオーケストレーションを自動的に処理します。ただし、ネイティブ連携が提供する完全な制御が必要な場合は、このガイドで完全な設定について説明します。

必要なもの

始める前に、以下を確認してください。

• Zendesk Suite Professional以上 - Switchboard APIには、少なくともProfessionalプランが必要です。これは、エージェント1人あたり月額115ドルから始まります。
• Sunshine Conversations API認証情報 - Zendesk管理センターからキーID、シークレット、およびアプリIDが必要です。
• Webhookエンドポイント - Zendeskが会話イベントを送信できる安全なHTTPSエンドポイント。
• 開発環境 - ボットは、Webhookを受信してAPI呼び出しを行うために、インターネットアクセスのある場所にホストされている必要があります。

Suite Professionalを使用していない場合、または利用可能な開発リソースがない場合は、当社のマネージドソリューションのようなものが、API構成を必要とせずに、標準のZendeskチャネルを介して接続します。

Zendesk Switchboardの概念を理解する

Switchboardは最初は抽象的に感じられるかもしれません。実際にどのように機能するかを分解してみましょう。

Switchboardとその連携

Switchboardを交通整理員と考えてください。顧客とビジネスシステムの間で、各会話を適切な宛先にルーティングします。

会話を処理できるすべてのシステムは、Switchboard連携として表示されます。これには以下が含まれます。

• Zendesk AIエージェント（ネイティブボット、zd:answerBotとして識別されます）
• AIエージェントAdvanced（Ultimate搭載、ultimateとして識別されます）
• エージェントワークスペース（人間のエージェント、zd:agentWorkspaceとして識別されます）
• サードパーティボット（OAuth経由のマーケットプレイス連携）
• カスタム連携（Webhookベースのボット）

出典：Zendesk Switchboardドキュメント

連携状態：アクティブ、保留中、スタンバイ

各Switchboard連携は、特定の会話に対して3つの状態のいずれかに存在します。

状態	意味	イベント配信
アクティブ (Active)	現在会話を制御している	すべてのイベントを受信
保留中 (Pending)	制御を引き継ごうとしている（グレースフルハンドオフ）	すべてのイベントを受信
スタンバイ (Standby)	バックグラウンドで待機している	イベントはデフォルトで抑制される

一度にアクティブ (Active) にできる連携は1つだけです。アクティブな連携は、顧客メッセージに応答することが期待されるものです。ボットがスタンバイ状態の場合、conversation:messageイベントを受信しません。

出典：Zendesk Switchboardドキュメント

制御転送操作

ボットは、4つの主要な操作を処理する必要があります。

操作	いつ使用するか
passControl	別のシステムへのエスカレーション（通常はエージェント）
releaseControl	会話が完了し、デフォルトにリセット
offerControl	一時的に制御を共有するグレースフルハンドオフ
acceptControl	提供されたハンドオフを受け入れる

ほとんどの場合、passControlをキーワード"next"とともに使用して、デフォルトの次の応答者として構成されている連携（通常はエージェントワークスペース）にエスカレーションします。

出典：Zendesk Switchboardドキュメント

ステップ1：Sunshine Conversations API認証情報を取得する

ボットは、Sunshine Conversations APIを介してZendeskと通信します。必要な認証情報を取得する方法は次のとおりです。

まず、Zendesk管理センターにログインします。 アプリと連携 (Apps and integrations) に移動し、次に Conversations APIに移動します。以前にAPI認証情報を作成したことがない場合は、APIキーを作成 (Create API key) をクリックします。

以下を受け取ります。

• キーID (Key ID) （API認証のユーザー名として機能します）
• シークレット (Secret) （パスワードとして機能します。安全に保管してください）
• アプリID (App ID) （Sunshine Conversationsアプリを識別します）

3つの値をすべて保存します。ボットが行うすべてのAPI呼び出しで使用します。

Switchboardを一覧表示する簡単なAPI呼び出しで認証情報をテストします。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

Switchboardの詳細を含むJSON応答が得られた場合、認証情報は機能しています。

出典：Zendesk管理センタードキュメント

ステップ2：カスタム連携を作成する

ボットがSwitchboardに参加する前に、Sunshine Conversationsで連携として存在する必要があります。これにより、Zendeskがボットにイベントを送信するために使用するWebhookエンドポイント登録が作成されます。

Create Integration APIを使用します。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "type": "custom",
    "name": "my-custom-bot",
    "webhooks": [{
      "target": "https://your-bot-endpoint.com/webhook",
      "triggers": ["conversation:create", "conversation:message"]
    }]
  }'

応答にはidフィールドが含まれます。この連携IDを保存します。次のステップで必要になります。

出典：Zendesk Conversations APIリファレンス

ステップ3：連携をSwitchboardに追加する

連携があるだけでは十分ではありません。会話の制御を実際に受信できるように、Switchboardに追加する必要があります。

まず、Switchboard IDを見つけます。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
  --user '{key_id}:{secret}'

次に、カスタム連携をSwitchboardにリンクするSwitchboard連携を作成します。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards/{switchboard_id}/switchboardIntegrations \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{
    "name": "my-custom-bot",
    "integrationId": "{custom_integration_id}",
    "deliverStandbyEvents": false,
    "nextSwitchboardIntegrationId": "{agent_workspace_integration_id}"
  }'

主要なパラメータの説明：

• name: ボットの読みやすい識別子
• integrationId: ステップ2のID
• deliverStandbyEvents: アクティブに処理していない会話を追跡する必要がない限り、falseに設定します
• nextSwitchboardIntegrationId: 通常はエージェントワークスペース連携ID。ボットがエスカレーションするときに会話がどこに行くかを決定します

出典：Zendesk Conversations APIリファレンス

ステップ4：ボットのWebhookを構成する

ボットはZendeskからリアルタイムイベントを受信する必要があります。ステップ2で設定したWebhook構成は、これらのイベントの送信先を定義しますが、エンドポイントはそれらを適切に処理する必要があります。

必要なWebhookイベント

少なくとも、ボットは以下をサブスクライブする必要があります。

• conversation:create - 新しい会話が開始されました
• conversation:message - 顧客がメッセージを送信しました
• switchboard:passControl - 制御がボットに渡されたか、ボットから渡されました
• switchboard:releaseControl - 会話が解放されました（チケットがクローズされました）

Webhookペイロード構造

各Webhookには、イベントの配列が含まれています。メッセージイベントは次のようになります。

{
  "app": { "id": "5ebee0975ac5304b664a12fa" },
  "webhook": { "id": "5f4eaef81e3dcc117c7ba48a", "version": "v2" },
  "events": [{
    "id": "5f74a0d52b5315fc007e798a",
    "createdAt": "2020-09-30T15:14:29.834Z",
    "type": "conversation:message",
    "payload": {
      "conversation": {
        "id": "f52b01137aa6c250bc7251fa",
        "activeSwitchboardIntegration": {
          "id": "67dc32a58d289d63bfeb6346",
          "name": "my-custom-bot"
        }
      },
      "message": {
        "author": { "type": "user" },
        "content": { "type": "text", "text": "I need help with my order" }
      }
    }
  }]
}

制御されていることを確認する

メッセージに応答する前に、activeSwitchboardIntegrationオブジェクトを確認してください。 nameがボットのSwitchboard連携名と一致しない場合は、応答しないでください。会話は別のシステムによって処理されています。

出典：Zendeskメッセージ受信ドキュメント

ステップ5：制御転送ロジックを実装する

ボットが顧客の問題を解決できないと判断した場合、人間のエージェントにエスカレーションする必要があります。ここでpassControlが登場します。

基本的なエスカレーション

次に構成された連携（通常はエージェントワークスペース）に制御を渡すには：

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/passControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"switchboardIntegration": "next"}'

チケットフィールドに入力するためのメタデータを渡す

最も強力な機能の1つは、ハンドオフ中にZendeskチケットフィールドに入力することです。 passControl呼び出しにメタデータを含めます。

{
  "switchboardIntegration": "zd-agentWorkspace",
  "metadata": {
    "dataCapture.systemField.priority": "high",
    "dataCapture.systemField.tags": "bot-escalated,shipping-issue",
    "dataCapture.systemField.group_id": "360000123456",
    "dataCapture.ticketField.54321": "Order #12345",
    "first_message_id": "603012d7e0a3f9000c879b67"
  }
}

これにより、チケットの優先度が自動的に設定され、タグが追加され、特定のグループに割り当てられ、カスタムフィールドに入力され、エージェントが表示する会話履歴の量が制御されます。

解決後の制御の解放

ボットが顧客の問題を完全に解決した場合は、releaseControlを呼び出して会話をリセットします。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/releaseControl \
  -X POST \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{}'

これにより、アクティブな連携がクリアされます。顧客が後で戻ってきた場合、デフォルトの応答者から新たに開始されます。

出典：Zendesk Conversations APIリファレンス

ステップ6：カスタムボット連携をテストする

本番環境に移行する前に、連携の各部分が正しく機能することを確認してください。

テストチェックリスト

1. Webウィジェットまたはメッセージングチャネルを介してテスト会話を作成します
2. ボットがconversation:createイベントを受信することを確認します
3. テストメッセージを送信し、ボットがconversation:messageを受信することを確認します
4. ボットがactiveSwitchboardIntegration.nameが一致する場合にのみ応答することを確認します
5. passControlフローをトリガーしてエスカレーションをテストします
6. 正しいメタデータを使用してエージェントワークスペースでチケットの作成を確認します
7. チケットをクローズし、自動化の実行後に制御がボットに戻ることを確認します

一般的なテストの問題

問題	考えられる原因
ボットがイベントを受信しない	連携がSwitchboardにないか、アクティブでないときにdeliverStandbyEventsがfalseです
二重応答	アクティブな状態でない場合でもボットが応答しています
ハンドオフでチケットが作成されない	間違ったnextSwitchboardIntegrationIdまたは不正な形式のpassControlペイロード
メタデータがチケットに表示されない	正しくないフィールドキー形式またはフィールドID

出典：Zendeskエージェントワークスペースドキュメント

一般的なパターンとベストプラクティス

チャネル固有のルーティング

異なるチャネルでは、異なるデフォルトの応答者が必要になることがよくあります。 Update Integration APIを使用して、チャネルごとのデフォルトを構成します。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations/{channel_integration_id} \
  -X PATCH \
  --user '{key_id}:{secret}' \
  -H 'content-type: application/json' \
  -d '{"defaultResponderId": "{switchboard_integration_id}"}'

たとえば、WhatsAppの会話をエージェントに直接ルーティングし（高価値チャネル）、Webウィジェットトラフィックを最初にボットに送信します。

移行中の段階的なロールアウト

あるボットプラットフォームから別のボットプラットフォームに移行する場合は、移行中に両方を同時に実行します。

1. 両方のボットをSwitchboard連携として追加します
2. 特定のブランドまたはチャネルを各ボットにルーティングします
3. 新しいボットを検証するときに、トラフィックを徐々にシフトします
4. 移行が完了したら、古いボット連携を削除します

会話履歴の制御

デフォルトでは、Zendeskはチケットを作成するときに最後の10件のメッセージを含めます。完全な会話を含めるには、会話が開始されたときに最初のメッセージIDを追跡します。

{
  "metadata": {
    "first_message_id": "{first_message_id}"
  }
}

エージェントが完全な会話履歴を表示できるように、これをpassControl呼び出しで渡します。

一般的な問題のトラブルシューティング

会話が間違った連携でスタックしている

エスカレーションされたはずのボットと顧客が話している場合は、ボットがpassControlまたはreleaseControlを正しく呼び出していることを確認してください。また、ボットのSwitchboard連携でnextSwitchboardIntegrationIdが構成されていることを確認してください。

メタデータがチケットに渡されない

フィールドキーは、正確なパターンに従う必要があります。

• 標準フィールド：dataCapture.systemField.{field_name}
• カスタムフィールド：dataCapture.ticketField.{field_id}

Zendesk管理センターでカスタムフィールドIDを再確認してください。これらは数値であり、UIに表示されるフィールド名ではありません。

ハンドオフがサイレントに失敗する

ボットが受信するすべてのWebhookイベントのロギングを有効にします。 passControlを呼び出しているのに、Switchboardの変更が表示されない場合は、API認証情報に正しいスコープがあり、ペイロードJSONが有効であることを確認してください。

不明なアクティブな連携状態

現在どの連携が会話を制御しているかわからない場合は、Get Conversation APIを使用します。

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id} \
  --user '{key_id}:{secret}'

応答でactiveSwitchboardIntegrationプロパティを確認します。

Zendeskボットオーケストレーションへのより簡単なアプローチ

カスタムSwitchboard連携の構築と維持には、継続的な開発リソースが必要です。 Zendeskがプラットフォームを更新するにつれて、チームはWebhookインフラストラクチャ、APIバージョニング、エラー処理、および継続的なメンテナンスを処理する必要があります。

APIの複雑さを伴わずに自動化を必要とするチームには、別のアプローチを提供します。 eesel AIは、Switchboardの構成を必要とせずに、オーケストレーションを自動的に処理します。

仕組みは次のとおりです。

• API構成は不要 - Zendeskの標準チャネルを介して連携します
• コンテンツから学習 - AIは、ヘルプセンター、過去のチケット、およびドキュメントでトレーニングされます
• 自動ルーティング - 会話は、手動のSwitchboard設定なしで、ルールに基づいてルーティングされます
• プレーンな英語のエスカレーションルール - JSONの代わりに、「常に請求に関する紛争を人間にエスカレーションする」のようなルールを定義します

ビジネスプランには、顧客に直接応答するAIエージェント機能、チケットルーティング用のAIトリアージ、および本番環境に移行する前に過去のチケットに対してテストするためのバルクシミュレーションが含まれています。プランは月額239ドル（年間請求）から始まり、7日間の無料トライアルが付いています。

適切な選択は、チームの技術力によって異なります。ネイティブSwitchboardは、複雑なカスタムロジックに最大限の柔軟性を提供します。私たちのアプローチは、インフラストラクチャ作業なしで高度な自動化が必要な場合に、より迅速な価値実現を提供します。