Webhook (英語)

Webhookは、特定のイベントが発生したときにアプリケーション間で送信される自動通知であり、HTTPリクエストを介してデータを送信することでリアルタイムの通信を可能にします。

Conversations Webhook を使用すると、会話の詳細と最新のメッセージ情報に即座にアクセスできるため、顧客からの問い合わせを効率的に管理できます。リアルタイムの統合をサポートして、メッセージのルーティング、エスカレーション、分析のワークフローを自動化し、包括的な会話とメッセージレベルのメタデータで運用レポートを強化します。

これらのWebhookを使用すると、サブスクリプション管理を介して受信メッセージと会話イベントの通知を受信できます。

Web インターフェイスで、[サブスクリプション管理] → [サブスクリプションの作成]** に移動します。チャネルメニューで 顧客エンゲージメント オプションを選択し、サブスクライブするイベントを選択します。

さらに、サブスクリプション管理 API エンドポイント (opens in a new tab) を使用して、必要なサブスクリプションを作成できます。

イベントの詳細については、以下のセクションを確認してください。

サポートされているイベント

Webhook は現在、主要なアクティビティについてリアルタイムで情報を得ることができるさまざまなイベントの種類をサポートしています。サポートされているイベントは次のとおりです。

メッセージング
- 受信メッセージ受信 (MO メッセージ)
- 送信メッセージ送信済み (MT メッセージ)
- メッセージが更新されました
- メッセージが削除されました
会話のライフサイクル
- 作成された会話
- 会話の割り当てが変更されました
- 会話の優先度が変更されました
- 会話ステータスが変更されました
- 会話キューが変更されました
- 会話フォームの変更
- 会話フォームのフィールドが変更されました
- 会話 SLA ポリシーの変更
- 会話の顧客が変更されました
- 会話の概要が変更されました
- 会話のトピックが変更されました
- 追加された会話タグ
- 会話タグの削除
エージェント
- エージェントのステータスが変更されました

イベント構造

イベントは、クライアントエンドポイントに送信されるマルチレベルの JSON オブジェクトとして表されます。

ルート JSON エレメント

ペイロードのルートには、次の 3 つの主要なイベントフィールドが含まれています。

type: 配信されるイベントのタイプを定義します。
payload: イベント固有のデータが含まれます。
timestamp: イベントの日時。

Webhook インテグレーターは、typeフィールドに基づいて受信イベントをフィルタリングして処理し、関連するイベントのみを処理できます。

JSON フィールド	種類	説明	サポートされている値
'タイプ'	列挙	イベントタイプの値	`INBOUND_MESSAGE` `OUTBOUND_MESSAGE` `INBOUND_MESSAGE_UPDATED` `CONVERSATION_DELETED` `CONVERSATION_CREATED` `CONVERSATION_STATUS_UPDATED` `CONVERSATION_ASSIGNMENT_UPDATED` `CONVERSATION_FORM_UPDATED` `CONVERSATION_QUEUE_UPDATED` `CONVERSATION_TAG_ADDED` `CONVERSATION_TAG_REMOVED` `CONVERSATION_NOTE_ADDED` `CONVERSATION_NOTE_UPDATED` `CONVERSATION_NOTE_REMOVED` `CONVERSATION_PRIORITY_UPDATED` `CONVERSATION_CUSTOMER_UPDATED` `CONVERSATION_TOPIC_UPDATED` `CONVERSATION_SUMMARY_UPDATED` `CONVERSATION_FORM_FIELD_UPDATED` `CONVERSATION_SLA_POLICY_UPDATED` `CONVERSATION_AGENT_STATUS_CHANGED`
'ペイロード'	入れ子になったオブジェクト	イベントペイロード	ペイロード構造を参照してください。
'タイムスタンプ'	タイムスタンプ	イベントのタイムスタンプ	'yyyy-MM-dd'T'HH:mm:ss のタイムスタンプ。SSSZ' 形式です。

例

json

{
  "type": "CONVERSATION_CREATED",
  "payload": { ... },
  "timestamp": "2023-06-20T16:44:24.572+00:00"
}

ペイロード構造

Webhook がトリガーされると、イベントに関する重要なデータを含む ペイロード が送信されます。この場合、ペイロードは、イベントを効果的に処理するために必要な重要な情報を提供する 2 つの主要なイベントカテゴリで構成されます。これらの要素は次のとおりです。

エージェントイベント: 可用性ステータスなど、エージェントのアクティビティに関連するEvents。
会話ライフサイクルイベント: 会話の開始、更新、終了など、のさまざまな段階を追跡するEvents。

これらの各要素は、受信側システムに必要なすべてのコンテキストを確保する上で特定の役割を果たします。

エージェント・イベント・ペイロード

このイベント構造は、CONVERSATION_AGENT_STATUS_CHANGEDイベントに適用されます。

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	一意のエージェント ID。	UUID v4 値。
`userId`	文字列	一意の暗号化されたユーザー ID。
'メール'	文字列	エージェントのメールアドレス。
'ロール'	列挙	エージェントの役割。	「エージェント」「スーパーバイザー」「ボット」
'ステータス'	入れ子になったオブジェクト	エージェントのステータスの詳細。	以下を参照してください。
'呼び出し側'	入れ子になったオブジェクト	呼び出し元 (変更を行ったエンティティ)。	以下を参照してください。

地位

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	一意の状態 ID。	UUID v4 値。
'名前'	文字列	ステータス名。	エージェントのステータスについてもっと読むを参照してください。
'グループ'	列挙	[状態] グループ。	「アクティブ」「忙しい」「インビジブル」「アウェイ」

会話イベントペイロード

通常、会話イベントは統一された構造に従います。すべてのイベントは、ID、状態、タイムスタンプなどのコア会話データを提供する一連の標準フィールドを共有します。イベントの種類によっては、より多くのコンテキストまたはデータを提供するために、追加のフィールドが含まれる場合があります。

つまり、すべての会話イベントは共通の基本構造を共有します。一部のイベントタイプは、特定の機能に関連する追加のフィールドを含めることで、これに基づいて構築されます。表にリストされているすべてのフィールドがすべてのイベントに表示されるわけではないことに注意してください。

会話イベントの種類の詳細については、以下の表を参照してください。

JSON フィールド	種類	イベントタイプの可用性	説明	サポートされている値
`id`	文字列	すべてのイベント。	一意の会話 ID。	UUID v4 値。
'ステータス'	列挙	すべてのイベント。	会話の状態。	「開く」「待機中」「解決済み」 `PENDING` (特定の場合にのみ使用可能) 「終了」
'キュー'	入れ子になったオブジェクト	すべてのイベント。	会話キューデータ。	以下を参照してください。
'優先度'	列挙	すべてのイベント。	会話の優先順位。	「低」「ノーマル」「高」「緊急」
'チャンネル'	列挙	すべてのイベント。	会話チャネル。	サポートされている Conversations チャネルのリストを参照してくださいです。
'方向'	列挙	すべてのイベント。	会話の方向。	「インバウンド」「アウトバウンド」
'担当者'	入れ子になったオブジェクト	すべてのイベント。	会話の担当者データ。	以下を参照してください。
「顧客」	入れ子になったオブジェクト	すべてのイベント。	会話の顧客データ。	以下を参照してください。
'フォーム'	入れ子になったオブジェクト	すべてのイベント。	会話フォームのデータ。	以下を参照してください。
'トピック'	文字列	すべてのイベント。	会話のトピック。
「概要」	文字列	すべてのイベント。	会話の要約。
'タイムスタンプ'	タイムスタンプ	すべてのイベント。	イベントのタイムスタンプ。同じタイムスタンプもルート構造の一部であることに注意してください。	'yyyy-MM-dd'T'HH:mm:ss のタイムスタンプ。SSSZ' 形式です。
'呼び出し側'	入れ子になったオブジェクト	すべてのイベント。	呼び出し元 (変更を行ったエンティティ)。	以下を参照してください。
'タグ'	入れ子になったオブジェクト	すべてのイベント。	関連付けられているすべての会話タグのリスト。	以下を参照してください。
'最後のメッセージ'	入れ子になったオブジェクト	次のバージョンでのみご利用いただけます。 `CONVERSATION_CREATED` `CONVERSATION_STATUS_UPDATED` `CONVERSATION_ASSIGNMENT_UPDATED` `CONVERSATION_FORM_UPDATED` `CONVERSATION_QUEUE_UPDATED` `CONVERSATION_TAG_ADDED` `CONVERSATION_TAG_REMOVED` `CONVERSATION_NOTE_ADDED` `CONVERSATION_NOTE_UPDATED` `CONVERSATION_NOTE_REMOVED` `CONVERSATION_PRIORITY_UPDATED` `CONVERSATION_CUSTOMER_UPDATED` `CONVERSATION_TOPIC_UPDATED` `CONVERSATION_SUMMARY_UPDATED` `CONVERSATION_FORM_FIELD_UPDATED` `CONVERSATION_SLA_POLICY_UPDATED`	追加の会話情報の取得に使用できる最後のメッセージ情報。	以下を参照してください。
'メッセージ'	入れ子になったオブジェクト	次のバージョンでのみご利用いただけます。 `INBOUND_MESSAGE` `OUTBOUND_MESSAGE` `CONVERSATION_MESSAGE_UPDATED` `CONVERSATION_DELETED`	完全なメッセージ・データ。	以下を参照してください。
'センチメント'	数値	`CONVERSATION_STATUS_UPDATED`イベントタイプで、ステータスが`CLOSED`の場合にのみ使用できます。	最終的な会話のセンチメント (会話が閉じられた後)。	-1.0 から 1.0
'フォームフィールド'	ネストされたオブジェクトのリスト	`CONVERSATION_STATUS_UPDATED`イベントタイプで、ステータスが`CLOSED`の場合にのみ使用できます。	最終的な会話フォームフィールドとそれぞれの値のリスト(会話が閉じられた後)。	以下を参照してください。
'フィールド'	入れ子になったオブジェクト	`CONVERSATION_FORM_FIELD_UPDATED`イベントタイプでのみ使用できます。	フィールドの名前と値が含まれます。	以下を参照してください。
'ノート'	入れ子になったオブジェクト	次のバージョンでのみご利用いただけます。 `CONVERSATION_NOTE_ADDED` `CONVERSATION_NOTE_UPDATED` `CONVERSATION_NOTE_DELETED`	会話メモのデータ。	以下を参照してください。
'ポリシー'	入れ子になったオブジェクト	`CONVERSATION_SLA_POLICY_UPDATED`イベントタイプでのみ使用できます。	会話 SLA ポリシーデータ。	以下を参照してください。
`addedTag`	入れ子になったオブジェクト	`CONVERSATION_TAG_ADDED`イベントタイプでのみ使用できます。	最近追加されたタグに関するデータ。	以下を参照してください。
`removedTag`	入れ子になったオブジェクト	`CONVERSATION_TAG_REMOVED`イベントタイプでのみ使用できます。	最近削除されたタグに関するデータ。	以下を参照してください。
'認証'	ネストされたオブジェクト	次のバージョンでのみご利用いただけます。 `INBOUND_MESSAGE` `INBOUND_MESSAGE_UPDATED` `INBOUND_MESSAGE_DELETED` `OUTBOUND_MESSAGE`	Live Chat でエンドユーザーを識別するために使用されるデータ。これには、電子メール、電話番号、外部 ID が含まれるか、識別データが含まれません。	「メール」「電話」 `EXTERNAL_ID` `NOT_AUTHENTICATED`

ペイロード要素

さまざまなペイロード要素の詳細については、次の表を参照してください。

担当者

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	エージェント ID。	UUID v4 値。
'名前'	文字列	エージェント名。
'メール'	文字列	エージェントのメールアドレス。
'ロール'	列挙	エージェントの役割。	「エージェント」「スーパーバイザー」「ボット」

顧客

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	顧客 ID。	UUID v4 値。
'名前'	文字列	顧客名。
`personId`	数値	関連付けられた People ユーザー ID。

形

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	フォーム ID。	UUID v4 値。
'名前'	文字列	フォーム名。

フォームフィールド

フィールドのリスト(下記参照)。

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	フィールド ID。	UUID v4 値。
'名前'	文字列	フィールド名。
'値'	文字列	フィールド値。

備考

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	ノート ID。	UUID v4 値。
'タイプ'	列挙	ノートタイプ。	'内部'、`JIRA_COMMENT`、'添付ファイル'
'コンテンツ'	オブジェクト	内容に注意してください。

政策

JSON フィールド	種類	説明	サポートされている値
`policyId`	文字列	SLA ポリシー ID。	UUID v4 値。
'ポリシー名'	文字列	SLA ポリシー名。
`severityId`	文字列	SLA 重大度 ID。	UUID v4 値。
`severityName`	文字列	SLA 重大度名。

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	タグ ID。	UUID v4 値。
'名前'	文字列	タグ名。

列

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	キュー ID。	UUID v4 値。
'名前'	文字列	キュー名。

最後のメッセージ

JSON フィールド	種類	説明	サポートされている値
'から'	文字列	メッセージ送信者 (メッセージの送信者/送信者)。	チャネルに応じて、英数字から UUID v4 値までの範囲です。
`to`	文字列	メッセージの送信先 (誰が/何をメッセージを受信したか)。	チャネルに応じて、英数字から UUID v4 値までの範囲です。
'方向'	列挙	メッセージの方向。	「インバウンド」、「アウトバウンド」
'チャンネル'	列挙	最後のメッセージチャネル。	サポートされている Conversations チャネルです。

メッセージ

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	一意のメッセージ ID。	UUID v4 値。
`messageId`	文字列	一意のプラットフォームメッセージ ID。	チャネルに応じて、英数字から UUID v4 値までの範囲です。
'から'	文字列	メッセージ送信者 (メッセージの送信者/送信者)。	チャネルに応じて、英数字から UUID v4 値までの範囲です。
`to`	文字列	メッセージの送信先 (誰が/何をメッセージを受信したか)。	チャネルに応じて、英数字から UUID v4 値までの範囲です。
'チャンネル'	列挙	最後のメッセージチャネル。	サポートされている Conversations チャネルです。
`conversationId`	文字列	メッセージが属する会話の一意の ID。	UUID v4 値。
`createdAt`	タイムスタンプ	メッセージ作成のタイムスタンプ。	'yyyy-MM-dd'T'HH:mm:ss のタイムスタンプ。SSSZ' 形式です。
`updatedAt`	タイムスタンプ	メッセージ更新タイムスタンプ。	'yyyy-MM-dd'T'HH:mm:ss のタイムスタンプ。SSSZ' 形式です。
'コンテンツ'	オブジェクト	メッセージの内容。	JSON で表されるテキスト、ビデオ、画像、またはその他の形式。
`socialContext`	文字列	`INBOUND_MESSAGE`イベントタイプでのみ使用できます。Facebook投稿およびInstagram投稿のソーシャルメディアコンテキストが含まれます。

社会的背景

JSON フィールド	種類	説明	サポートされている値
'ユーザー名'	文字列	ソーシャルメディアのユーザー名。

認証 (認証データ)

JSON フィールド	種類	説明	サポートされている値
`authenticationType`	列挙	Live Chat の顧客認証タイプ。	`NOT_AUTHENTICATED` 「メール」「電話」 `EXTERNAL_ID`
'値'	文字列	認証に使用される値 (電子メール、電話、または外部 ID)。
`personId`	数値	People データベース内のユーザーの ID。

すべてのペイロードで共有される一般データ

呼び出し元

JSON フィールド	種類	説明	サポートされている値
`id`	文字列	呼び出し元 ID。	`AGENT`呼び出し元タイプの場合、値は`agentId`です。`SYSTEM`呼び出し側タイプの場合、値は`null`です。
'名前'	文字列	呼び出し元名。	`AGENT`呼び出し元タイプの場合、値は「エージェント名」です。`SYSTEM`呼び出し側タイプの場合、値は`null`です。
'タイプ'	列挙	呼び出し元の種類。	'エージェント', 'システム'

Webhook の例

次の Webhook の例を確認して、関連する構造とデータを理解してください。これらの例は、イベントがどのように表現され、統合で効果的に処理する方法を明確にするのに役立ちます。

会話ステータスが更新されました

JSON の表示

会話は終了しました

JSON の表示

json

    {
      "type": "CONVERSATION_STATUS_CHANGED",
      "payload": {
        "id": "d1d1de2e-d8dc-4ad7-970e-acca0035e19d",
        "status": "CLOSED",
        "queue": {
          "id": "35b5e5b7-ac4a-40dc-872f-2a1403bcd770",
          "name": "Queue Name"
        },
        "priority": "NORMAL",
        "channel": "LIVE_CHAT",
        "direction": "INBOUND",
        "assignee": {
          "id": "fbcfe58e-a5c3-3a80-b569-f631dbb27c41",
          "name": "Agent Name",
          "email": "agent.name@example.com"
        },
        "customer": {
          "id": "68db05c2-2716-42c0-a251-880866cf4130",
          "name": "Customer Name",
          "personId": "2456"
        },
        "form": {
          "id": "a9b1e603-519a-4af1-a5e6-fd3426006811",
          "name": "Title"
        },
        "formFields": [
          {
            "id": "b57ab774-43b7-4b0c-929f-83c1d8eabb03",
            "name": "Field Name 1",
            "value": "234234"
          },
          {
            "id": "f79c8aa3-d0db-4a84-a040-d9559a66e817",
            "name": "Field Name 2",
            "value": "2222"
          },
          {
            "id": "b52c4acc-f612-43ee-b44c-881384750582",
            "name": "Field Name 3",
            "value": "B"
          },
          {
            "id": "abfa2add-66b4-498f-90d1-a523911ac88b",
            "name": "Checkbox",
            "value": "true"
          }
        ],
        "lastMessage": {
          "from": "5c6ea201-9d67-4ec8-9e40-edcd6800e795",
          "to": "2681dd24-9a31-4393-8ce1-356fbbe7d585",
          "direction": "OUTBOUND",
          "channel": "LIVE_CHAT"
        },
        "invoker": {
          "type": "AGENT",
          "id": "fbcfe58e-a5c3-3a80-b569-f631dbb27c41",
          "name": "Agent Name"
        },
        "tags": [
          {
            "id": "93edc97d-80a0-454a-bcaf-9a645194c335",
            "name": "Tag Name 1"
          },
          {
            "id": "54613516-b942-4428-b79d-dd8c856ecf90",
            "name": "Tag Name 2"
          },
          {
            "id": "cdd33109-fd0d-45f7-9907-fce548142c39",
            "name": "Tag Name 3"
          }
        ],
        "topic": "Topic Name",
        "sentiment": 1,
        "summary": "Summary",
        "timestamp": "2025-03-21T13:25:30.145+00:00"
      },
      "timestamp": "2025-03-21T13:25:30.145+00:00"
    }

会話の割り当てが更新されました

JSON の表示

会話キューが更新されました

JSON の表示

会話の顧客が更新されました

JSON の表示

会話フォームが更新されました

JSON の表示

会話の概要が更新されました

JSON の表示

会話のトピックが更新されました

JSON の表示

会話タグが追加されました

JSON の表示

会話タグの削除

JSON の表示

会話メモが追加されました

JSON の表示

会話メモが更新されました

JSON の表示

会話メモが削除されました

JSON の表示

送信された会話送信メッセージ (システム)

JSON の表示

json

  {
    "type": "OUTBOUND_MESSAGE",
    "payload": {
      "id": "b9263ee4-93b9-4352-912a-3b558f751276",
      "status": "OPEN",
      "queue": {
        "id": "35b5e5b7-ac4a-40dc-872f-2a1403bcd770",
        "name": "Queue Name"
      },
      "priority": "NORMAL",
      "channel": "LIVE_CHAT",
      "direction": "INBOUND",
      "assignee": {
        "id": "fbcfe58e-a5c3-3a80-b569-f631dbb27c41",
        "name": "Agent Name",
        "email": "agent.name@example.com"
      },
      "customer": {
        "id": "35b5e5b7-ac4a-40dc-872f-2a1403bcd769",
        "name": "Customer Name",
        "personId": "2500"
      },
      "form": {
        "id": "a9b1e603-519a-4af1-a5e6-fd3426006811",
        "name": "Title"
      },
      "topic": "Test Topic A",
      "summary": "Test Summary",
      "timestamp": "2025-03-21T13:12:06.496+00:00",
      "message": {
        "id": "f74f3515-2a8d-481a-9bd1-36ee1f905585",
        "messageId": "f74f3515-2a8d-481a-9bd1-36ee1f905585",
        "channel": "LIVE_CHAT",
        "from": "d21806c0-279e-418d-8caf-b96223fd8392",
        "to": "a48d5aad-f584-41c6-b5e3-c1e3a43b52d2",
        "conversationId": "b9263ee4-93b9-4352-912a-3b558f751276",
        "createdAt": "2025-03-21T13:12:06.495+00:00",
        "updatedAt": "2025-03-21T13:12:06.495+00:00",
        "content": {
          "text": "Hello, we hope this message finds you well. We have not received any updates from you in a while. As such, we will close this case and reject the request.",
          "type": "TEXT"
        }
      },
      "invoker": {
        "type": "SYSTEM",
        "id": null,
        "name": null
      },
      "tags": [
        {
          "id": "93edc97d-80a0-454a-bcaf-9a645194c335",
          "name": "Tag Name 1"
        },
        {
          "id": "54613516-b942-4428-b79d-dd8c856ecf90",
          "name": "Tag Name 2"
        },
        {
          "id": "cdd33109-fd0d-45f7-9907-fce548142c39",
          "name": "Tag Name 3"
        }
      ],
      "authentication": null
    },
    "timestamp": "2025-03-21T13:12:06.496+00:00"
  }

送信された会話アウトバウンドメッセージ(エージェント)

JSON の表示

受信した会話の受信メッセージ

JSON の表示

作成された会話

JSON の表示

会話メッセージが更新されました

JSON の表示

会話メッセージが削除されました

JSON の表示

会話フォームのフィールドが更新されました

JSON の表示

会話の SLA ポリシーが変更されました

JSON の表示

エージェントのステータスが変更されました

JSON の表示

はじめに Conversations

Webhook (英語)

サポートされているイベント

イベント構造

ルート JSON エレメント

ペイロード構造

エージェント・イベント・ペイロード

地位

会話イベントペイロード

ペイロード要素

担当者

顧客

形

フォームフィールド

備考

政策

タグ

タグ、タグの追加、タグの削除

列

最後のメッセージ

メッセージ

社会的背景

認証 (認証データ)

すべてのペイロードで共有される一般データ

呼び出し 元

Webhook の例

会話ステータスが更新されました

会話は終了しました

会話の割り当てが更新されました

会話キューが更新されました

会話の顧客が更新されました

会話フォームが更新されました

会話の概要が更新されました

会話のトピックが更新されました

会話タグが追加されました

会話タグの削除

会話メモが追加されました

会話メモが更新されました

会話メモが削除されました

送信された会話送信メッセージ (システム)

送信された会話アウトバウンドメッセージ(エージェント)

受信した会話の受信メッセージ

作成された会話

会話メッセージが更新されました

会話メッセージが削除されました

会話フォームのフィールドが更新されました

会話の SLA ポリシーが変更されました

エージェントのステータスが変更されました

呼び出し元