概要
イベントコールバック、別名 Webhook とは、特定のイベントが発生した際に、Udesk が特定のデータを固定のフォーマットで指定されたコールバック URL に送信することを指します。
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 | チャット満足度が保存された時 |
Udesk のイベントコールバック機能を使用するには、以下の手順を実行する必要があります：
- コードを記述し、イベントコールバック処理インターフェースを実装し、イベントコールバック URL を提供します。
- イベントコールバック URL 設定インターフェースを呼び出し、実装したイベントコールバック処理インターフェースの URL を設定します。
- イベントコールバックタイプ設定インターフェースを呼び出し、必要に応じて受信するイベントコールバックの種類を設定します。
- イベントコールバックの content_type 設定インターフェースを呼び出し、必要に応じて content_type の値を設定します。
イベントコールバック処理インターフェースの作成
このインターフェースはお客様によって実装され、特定の要件を満たす必要があります。
Udesk は POST メソッドを使用して提供されたコールバック URL にリクエストを送信し、データをリクエストボディ（Request Body）として送信します。
リクエストボディのデータ構造は以下の通りです：
| 属性 | 型 | 説明 |
|---|---|---|
| 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": "WeChat",
"source": "WeChat-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": {},
"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": "WeChat",
"belong_queue": "queue_company_6_group_271",
"agent_msg_num": 1,
"customer_msg_num": 1,
"source": "WeChat-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": "xx"
}
}
],
"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\":\"こんにちはWeChat\",\"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": "備考"
}
}
イベントコールバックURL設定インターフェース
このインターフェースは、イベントコールバックURLを設定するために使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /set_url
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| push_url | はい | 文字列 | イベントコールバックURL |
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| push_url | 文字列 | 変更後のイベントコールバックURL |
例
curl https://demo.udesk.cn/open_api_v1/set_url?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,
"push_url": "https://www.demo.com/push_url"
}
イベントコールバックの content_type 設定インターフェース
このインターフェースは、イベントコールバックURLを設定するために使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /set_push_content_type
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| push_content_type | はい | 文字列 | イベントコールバックリクエストの content_type |
- 注意：push_content_type には JSON を渡すことができ、対応する戻り値は json 文字列です。デフォルトは "application/x-www-form-urlencoded" です。
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
| webhook_push_type | 文字列 | コールバック返却値の構造 |
例
curl https://demo.udesk.cn/open_api_v1/set_push_content_type?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_content_type": "JSON"
}'
返却
{
"code": 1000,
"webhook_push_type": "JSON"
}
イベントコールバックタイプ設定インターフェース
このインターフェースは、どのイベントコールバックを受信するかを設定するために使用されます。 認証：認証方法を参照してください。
リクエストメソッド
POST /set_permissions
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| permissions | はい | オブジェクト | 設定集合 |
permissions のデータ構造
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| customer_create | いいえ | ブール | 顧客作成イベントを受信するかどうか |
| customer_update | いいえ | ブール | 顧客更新イベントを受信するかどうか |
| customer_destroy | いいえ | ブール | 顧客削除イベントを受信するかどうか |
| organization_create | いいえ | ブール | 組織作成イベントを受信するかどうか |
| organization_update | いいえ | ブール | 組織更新イベントを受信するかどうか |
| organization_destroy | いいえ | ブール | 組織削除イベントを受信するかどうか |
| im_sub_session_close | いいえ | ブール | サブセッション終了イベントを受信するかどうか |
| shut_queue_create | いいえ | ブール | キュー放棄イベントを受信するかどうか |
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000 は成功を表します |
| permissions | オブジェクト | 変更後の設定集合、構造はパラメータと同じです |
| ### サンプル |
curl https://demo.udesk.cn/open_api_v1/set_permissions?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 '
{
"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,
"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
}
}
エラーコード説明
| エラーコード | message情報 | exception:message情報 | 説明 |
|---|---|---|---|
| 2000 | 不明なエラー | 申し訳ございません、入力された値が正しくありません | 必須パラメータ{content_type}が未入力または値が不正です |
| param is missing or the value is empty: permissions | 必須パラメータ{permissions}が未入力または空値です |