概要
イベントコールバック、別名 Webhook とは、特定のイベントが発生した際に、Udesk が特定のデータを固定のフォーマットで指定されたコールバックアドレスに送信することを指します。
Udesk のイベントコールバックは以下のイベントをサポートしています：
| イベント名 | 説明 |
|---|---|
| Customer_create | 顧客が新規作成された時 |
| Customer_update | 顧客情報が更新された時 |
| Customer_destroy | 顧客が削除された時 |
| Organization_create | 顧客企業が新規作成された時 |
| Organization_update | 顧客企業情報が更新された時 |
| Organization_destroy | 顧客企業が削除された時 |
| ImSubSession_create | IM セッションが新規作成された時 |
| ImSubSession_close | IM セッションが終了した時 |
| ShutQueue_create | IM でキューイングが放棄された時 |
| AgentNote_update | IM セッション終了時/CC 通話終了後の業務記録が更新された時 |
| ImSurveyVote_create | チャット満足度が初回保存された時 |
| UserGroup_create | カスタマーサポートグループが作成された時 |
| UserGroup_update | カスタマーサポートグループ名が変更された時、またはグループメンバーが変更された時 |
| UserGroup_destroy | カスタマーサポートグループが削除された時 |
Udesk のイベントコールバック機能を使用するには、以下の手順を実行する必要があります：
- Udesk インターフェースアドレスを呼び出し、コールバックインターフェースのアドレス登録を実装し、異なるタイプのイベントを購読します（http/https アドレス両方をサポート）。
- 登録時のインターフェースアドレスを提供すると、Udesk は購読されたタイプに応じて異なるイベントメッセージフォーマットで通知します。
イベントコールバック処理インターフェースの作成
このインターフェースはお客様によって実装され、特定の要件を満たす必要があります。
Udesk は POST メソッドを使用して提供されたコールバックアドレスにリクエストを送信し、データをリクエストボディ（Request Body）として送信します。
Content-Type: application/json
リクエストボディのデータ構造は以下の通りです：
| 属性 | 型 | 説明 |
|---|---|---|
| action | 文字列 | イベントタイプ |
| message | オブジェクト | イベントデータ |
イベントによって message の内容は異なります。
Customer_create イベント
"message" のデータ構造は顧客データを参照してください。
例：
{
"action": "Customer_create",
"message": {
"id": 1,
"nick_name": "テストユーザー",
"level": "normal",
"description": null,
"owner_id": 1,
"owner_group_id": 1,
"custom_fields": {
"SelectField_1": ["0"],
"SelectField_2": ["0"]
},
"open_api_token": null,
"organization_id": null,
"is_blocked": false,
"tags": [],
"email": "customer@sample.com",
"other_emails": [],
"cellphones": [
{
"id": 1,
"content": "13000000001"
}
],
"platform": "手動入力"
}
}
Customer_update イベント
「message」のデータ構造は以下の通りです：
{
"id": 顧客ID,
"changes": {
"属性名": [変更前の値, 変更後の値]
}
}
「属性名」については顧客データを参照してください。
例：
{
"action": "Customer_update",
"message": {
"id": 1,
"changes": {
"nick_name": ["テスト顧客1", "テスト顧客2"],
"owner_id": [1, 2]
}
}
}
Customer_destroy イベント
「message」のデータ構造は以下の通りです：
{
"id": 削除された顧客ID
}
例
{
"action": "Customer_destroy",
"message": {
"id": 1
}
}
Organization_create イベント
「message」のデータ構造は顧客会社データを参照してください。
例：
{
"action": "Organization_create",
"message": {
"id": 1,
"name": "テスト会社1",
"domains": "https://www.test1.com",
"custom_fields": {
"TextField_1": "テストテキスト",
"SelectField_1": ["0"]
},
"description": "この会社は例示のみに使用されます"
}
}
Organization_update イベント
「message」のデータ構造は以下の通りです：
{
"id": 顧客会社ID,
"changes": {
"属性名": [変更前の値, 変更後の値]
}
}
「属性名」については顧客会社データを参照してください。
例：
{
"action": "Organization_update",
"message": {
"id": 1,
"changes": {
"name": ["テスト会社1", "テスト会社2"]
}
}
}
Organization_destroy イベント
「message」のデータ構造は以下の通りです：
{
"id": 削除された顧客会社ID
}
例
{
"action": "Organization_destroy",
"message": {
"id": 1
}
}
ImSubSession_create イベント
「message」のデータ構造は以下の通りです。
{
"id": 新規作成されたセッションID,
"im_sub_session_log": 会話記録の詳細
}
例
{
"action": "ImSubSession_create",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"agent_id": 862,
"customer_id": 117092,
"platform": "微信",
"source": "微信-xx",
"weifeng": "weifeng_params",
"created_at": "2017-10-27 21:23:45"
}
]
}
}
ImSubSession_close イベント
「message」のデータ構造は以下の通りです。
{
"id": クローズされたセッションID,
"im_sub_session_log": 会話記録の詳細,
"im_log_infos": チャット記録
}
例
{
"action": "ImSubSession_close",
"message": {
"id": 14980761,
"im_sub_session_log": [
{
"session_id": 8761,
"sub_session_id": 14980761,
"note_id": 6541,
"note_content": "業務記録の件名",
"note_custom_fields": {
"TextField_1":"sdfaf",
"TextField_2":"2016-09-01",
"TextField_3":"00:00:02",
"TextField_4":"23",
"TextField_5":"24",
"SelectField_1":"0",
"TextField_7":"cessf沙阿发二娃分",
"SelectField_2":"0,0",
"SelectField_3":"2",
"SelectField_4":"0,1,2,3,4"
},
"note_template_id": "業務記録テンプレートID",
"note_template_name": "業務記録テンプレート名",
"customer_id": 117092,
"customer_name": "xx",
"customer_custom_fields":{
"TextField_1":"顧客カスタムフィールド",
"TextField_2":"2018-07-01",
"TextField_3":"00:02:02",
"TextField_4":"21",
"TextField_5":"25",
"SelectField_1":"0",
"TextField_7":"テスト内容",
"SelectField_2":"0,0",
"SelectField_3":"2",
"SelectField_4":"0,1,2,3,4"
},
"agent_id": 862,
"agent_nick_name": "xx_カスタマーサポート",
"agent_email": "agent@udesk.cn",
"created_at": "2017-10-27 21:23:45",
"closed_at": "2017-10-27 21:23:59",
"resp_seconds": null,
"queue_seconds": "未キューイング",
"sustain_seconds": 14,
"survey_vote_id": null,
"platform": "微信",
"belong_queue": "queue_company_6_group_271",
"agent_msg_num": 1,
"customer_msg_num": 1,
"source": "微信-xx",
"source_url": null,
"queue_start_time": "2017-10-27 21:23:45",
"conversations_num_today": 3,
"agent_invite_vote_count": null,
"search_keyword": null,
"custom_channel": null,
"last_response": "agent",
"alert_num": 1,
"alert_desc": "センシティブワード1回,応答タイムアウト,セッションタイムアウト",
"ticket_num": 2,
"ticket_nos": "#140,#141",
"ticket_ids": [342342,24234],
"im_web_plugin_id": 1,
"sender": "customer",
"active_guest": "agent",
"weifeng": "weifeng_params",
"close_method": "agent_close",
"robot_session_id": 4303299,
"resolved_state": "0",
"curl_url": "https://demo.udesk.cn/im_client/?web_plugin_id=1",
"customer_tags": ["顧客タグ1", "顧客タグ2", "顧客タグ3"],
"weixin_info": {
"name": "微信チャネル名"
}
],
"im_log_infos": [
{
"id": 70161,
"created_at": "2017-10-27 21:23:54",
"sender": "customer",
"user_id": 117092,
"content": "{"type":"image","platform":"wechat","data":{"content":"https://dn-udeskim.qbox.me/022c4a12-4f83-492d-8e4d-5f04191e0058.jpg","duration":null,"origin_url":"https://api.weixin.qq.com/cgi-bin/media/get?access_token=Z7kg69qvIqh_5-jZmzmKVgbt3mXP4pvmiNpqt_risTXuF1tOGw2bax9YaSVVQM4PR0HH_q7Fpou3PlYJhujH09xJxQyNmIhGYank_vmMxnEPTJfAHAWAQ&media_id=ObkKKAP5qS8wtFgXi1C2VMHKCZxQxxSvg1YVH2uHuDB_1HfORtcRf_3L2FmCUvO6"}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70158,
"created_at": "2017-10-27 21:23:45",
"sender": "agent",
"user_id": 862,
"content": "{"type":"rich","platform":"wechat","data":{"content":"<p>カスタマーサポートxx_カスタマーサポート_ニックネームがご対応します</p><p>ラララララ-英語</p>","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70157,
"created_at": "2017-10-27 21:23:45",
"sender": "customer",
"user_id": 117092,
"content": "{"type":"message","platform":"wechat","data":{"content":"新しいお問い合わせが入りました。","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": ""
},
{
"id": 70159,
"created_at": "2017-10-27 21:23:48",
"sender": "agent",
"user_id": 862,
"content": "{"type":"message","platform":"wechat","data":{"content":"こんにちは微信","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
},
{
"id": 70160,
"created_at": "2017-10-27 21:23:52",
"sender": "agent",
"user_id": 862,
"content": "{"type":"message","platform":"wechat","data":{"content":"普通","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
},
{
"id": 70161,
"created_at": "2017-10-27 21:23:59",
"sender": "agent",
"user_id": 862,
"content": "{"type":"close","platform":"wechat","data":{"content":"xx_カスタマーサポートが会話をクローズ","duration":null}}",
"session_id": 8761,
"sub_session_id": 14980761,
"survey_option_id": null,
"send_status": "arrive"
}
]
}
}
備考：
1、会話終了方法-close_method:
"agent_close" | カスタマーサポートによるクローズ
"redirect_close" | 転送によるクローズ
"sys_close" | システムによるクローズ
"customer_close" | 顧客によるクローズ
2、メッセージ送信状態-send_status:
"sending" | 送信中
"arrive" | 配信済み
"fail" | 送信失敗
"off_sending" | オフライン送信
"off_arrive" | オフライン配信済み
"rollback" | 取り消し済み
3、ロボットセッションID-robot_session_id:
カスタマーサポートシステム側のロボットセッションID
4、満足度-解決済みかどうか-resolved_state:
"0" | 解決済み
"1" | 未解決
ShutQueue_create イベント
「message」のデータ構造は以下の通りです：
{
"id": "レコードID",
"customer_id": "顧客ID",
"nick_name": "顧客名",
"queue_name": "待ち行列名",
"queue_type": "待ち行列タイプ",
"queue_id": "待ち行列スタッフグループID、スタッフID",
"queue_start_time": "待ち行列開始時間",
"queue_end_time": "待ち行列終了時間",
"queue_seconds": "待ち時間",
"chanel": "チャネル",
"im_web_plugin_id": "ソースプラグインID",
"menu_names": "ナビゲーションメニュー名"
}
例
{
"action": "ShutQueue_create",
"message": {
"id": "1",
"customer_id": "46",
"nick_name": "北京cloud-ark.cn联通(1535800080)",
"queue_name": "待ち行列カスタマーサポート名",
"queue_type": "agent",
"queue_id": "33",
"queue_start_time": "2018-09-01 19:08:00 +0800",
"queue_end_time": "2018-09-01 19:08:30 +0800",
"queue_seconds": "30秒",
"chanel": "web",
"im_web_plugin_id": 1,
"menu_names": "ナビゲーションメニュー名"
}
}
備考：
待ち行列がカスタマーサポートの場合、queue_nameはカスタマーサポート名、queue_typeは「agent」、queue_idはカスタマーサポートIDです。
待ち行列がカスタマーサポートグループの場合、queue_nameはカスタマーサポートグループ名、queue_typeは「group」、queue_idはカスタマーサポートグループIDです。
待ち行列が会社の場合、queue_nameは「会社」、queue_typeは「company」、queue_idは「会社」です。
AgentNote_update イベント
「message」のデータ構造は以下の通りです：
IM ダイアログの業務記録変更の場合、データ構造は以下の通りです：
{
"updated_at": "変更時間、秒単位まで",
"sub_session_id": "ダイアログID",
"note_id": "業務記録ID",
"note_content": "業務記録主題",
"field_id": "フィールドID",
"field_title": "フィールド名",
"filed_value": "変更後のフィールド値"
}
CC 通話の業務記録変更の場合、データ構造は以下の通りです：
{
"updated_at": "変更時間、秒単位まで",
"conversation_id": "通話記録ID",
"note_id": "業務記録ID",
"note_content": "業務記録主題",
"field_id": "フィールドID",
"field_title": "フィールド名",
"filed_value": "変更後のフィールド値"
}
例(IM)
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"sub_session_id": 4947,
"note_id": 292,
"note_content": "業務記録主題",
"field_id": "SelectField_98",
"field_title": "苦情タイプ",
"filed_value": "0"
}
}
例(CC)
{
"action": "AgentNote_update",
"message": {
"updated_at": "2019-12-06 10:02:40",
"conversation_id": 4947,
"note_id": 292,
"note_content": "業務記録主題",
"field_id": "SelectField_98",
"field_title": "苦情タイプ",
"filed_value": "0"
}
}
備考:
1. ダイアログ終了後の業務記録変更のみ、保存後にその業務記録の変更情報がプッシュされます。
2. API方式による業務記録変更では、イベントコールバックはトリガーされません。
ImSurveyVote_create イベント
「message」のデータ構造は以下の通りです：
{
"created_at": 保存時間、秒単位まで正確,
"sub_session_id": セッションID,
"option_id": 満足度オプションID,
"option_name": 満足度オプション名,
"tags": 満足度タグ名,
"remark": 備考の値
}
例
{
"action": "ImSurveyVote_create",
"message": {
"created_at": "2019-12-06 10:13:04",
"sub_session_id": 4947,
"option_id": 1234,
"option_name": "非常に満足",
"tags": "タグ1,タグ2",
"remark": "備考"
}
}
UserGroup_create イベント
「message」のデータ構造は以下の通りです：
{
"id": エージェントグループID,
"name": エージェントグループ名
}
例
{
"action": "UserGroup_create",
"message": {
"id": 1,
"name": "デフォルトグループ"
}
}
UserGroup_update イベント
注: 返される結果は変更されたフィールドのみで、他のフィールドは返されません。
「message」のデータ構造は以下の通りです：
{
"id": エージェントグループID,
"changes": {
"name": [エージェントグループ名の元の値, エージェントグループ名の変更後の値],
"add_agent_id": 追加されたエージェントID,
"del_agent_id": 削除されたエージェントID
}
}
例
{
"action": "UserGroup_update",
"message": {
"id": 1,
"name": ["エージェントグループ1", "エージェントグループ2"],
"add_agent_id": 1,
"del_agent_id": 2
}
}
UserGroup_destroy イベント
「message」のデータ構造は以下の通りです：
{
"id": 削除されたエージェントグループID
}
例
{
"action": "UserGroup_destroy",
"message": {
"id": 1
}
}
イベントコールバックインターフェースの追加
このインターフェースは、イベントコールバックURLを設定するために使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /webhook_create
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| push_url | はい | 文字列 | イベントコールバックURL |
| permissions | はい | JSONオブジェクト | イベントセット |
permissions のデータ構造
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| customer_create | いいえ | ブール値 | 顧客作成イベントを受信するかどうか |
| customer_update | いいえ | ブール値 | 顧客更新イベントを受信するかどうか |
| customer_destroy | いいえ | ブール値 | 顧客削除イベントを受信するかどうか |
| organization_create | いいえ | ブール値 | 組織作成イベントを受信するかどうか |
| organization_update | いいえ | ブール値 | 組織更新イベントを受信するかどうか |
| organization_destroy | いいえ | ブール値 | 組織削除イベントを受信するかどうか |
| im_sub_session_close | いいえ | ブール値 | セッション終了イベントを受信するかどうか |
| shut_queue_create | いいえ | ブール値 | キュー放棄イベントを受信するかどうか |
| im_survey_vote_create | いいえ | ブール値 | 満足度評価イベントを受信するかどうか |
| agent_note_update | いいえ | ブール値 | 業務記録更新イベントを受信するかどうか |
| user_group_create | いいえ | ブール値 | エージェントグループ作成イベントを受信するかどうか |
| user_group_update | いいえ | ブール値 | エージェントグループ更新イベントを受信するかどうか |
| user_group_destroy | いいえ | ブール値 | エージェントグループ削除イベントを受信するかどうか |
| ### サンプル |
curl https://demo.udesk.cn/open_api_v1/webhook_create?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"push_url": "https://www.demo.com/push_url",
"permissions": {
"organization_create":true,
"organization_update": true,
"organization_destroy": true,
"customer_create": true,
"customer_update": true,
"customer_destroy": true,
"im_sub_session_close": true,
"shut_queue_create": true
}
}'
レスポンス
{
"code": 1000,
"webhook":
{
"push_url": "https://www.demo.com/push_url",
"permissions": {
"organization_create":true,
"organization_update":true,
"organization_destroy":true,
"customer_create":true,
"customer_destroy":true,
"customer_update":true,
"im_sub_session_close":true,
"shut_queue_create":true
}
}
}
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
| webhook | オブジェクト | 変更後の設定集合、構造はパラメータと同じです |
イベントコールバックの編集
このインターフェースは、イベントコールバックアドレスの設定に使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /webhook_update
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| push_url | はい | 文字列 | イベントコールバックアドレス |
| permissions | はい | JSONオブジェクト | イベント集合、作成を参照してください |
| ### サンプル |
curl https://demo.udesk.cn/open_api_v1/webhook_update?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X POST \
-H 'content-type: application/json' \
-d '
{
"push_url": "https://www.demo.com/push_url",
"permissions": {
"organization_create": true,
"organization_update": true,
"organization_destroy": true,
"customer_create": true,
"customer_update": true,
"customer_destroy": true,
"im_sub_session_close": true,
"shut_queue_create": true
}
}'
レスポンス
{
"code": 1000,
"webhook":
{
"push_url": "https://www.demo.com/push_url",
"permissions": {
"organization_create":true,
"organization_update":true,
"organization_destroy":true,
"customer_create":true,
"customer_destroy":true,
"customer_update":true,
"im_sub_session_close":true,
"shut_queue_create":true
}
}
}
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
| webhook | オブジェクト | 変更後の設定集合、構造はパラメータと同じです |
イベントコールバックの削除
このAPIはイベントコールバックアドレスの設定に使用されます 認証：認証方法を参照してください
リクエストメソッド
POST /webhook_destroy
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| push_url | はい | 文字列 | イベントコールバックアドレス |
| ### サンプル |
curl https://demo.udesk.cn/open_api_v1/webhook_destroy?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: application/json' \
-d '
{
"push_url": "https://www.demo.com/push_url"
}'
レスポンス
{
"code": 1000
}
レスポンスデータ
| 属性名 | 型 | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
すべてのイベントコールバックURLを取得するインターフェース
このインターフェースは、イベントコールバックURLを設定するために使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /webhook_list
リクエストパラメータ（Request Body）
なし
レスポンスデータ
| 属性名 | 型 | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
| webhooks | JSONオブジェクト | 配列リスト |
サンプル
curl -X POST \
'https://demo.udesk.cn/open_api_v1/webhook_list?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
--header 'Content-Type: application/json' \
--data '{}'
レスポンス
{
"code": 1000,
"webhooks": [
{
"push_url": "http://localhost:3002",
"permissions": {
"organization_create":true,
"organization_update":true,
"organization_destroy":true,
"customer_create":true,
"customer_destroy":true,
"customer_update":true,
"im_sub_session_close":true,
"shut_queue_create":true
}
}
]
}
コードエラーコード説明
| エラーコード | message情報 | exception:message情報 | 説明 |
|---|---|---|---|
| 2000 | 不明なエラー | 申し訳ございませんが、入力された値が正しくありません | 必須パラメータ{content_type}が未入力または値が不正です |
| param is missing or the value is empty: permissions | 必須パラメータ{permissions}が未入力または空値です |