Udesk API 共通説明

ドキュメント参照 https://www.udesk.cn/website/doc/apiv2/intro/

IM 会話記録リストの取得

このAPIは、複数のIM会話記録情報を一度に取得するために使用されます。 頻度制限 1回/2秒

リクエストメソッド

GET /im/sessions/search

リクエストパラメータ（Query String）

パラメータ名 必須 説明
start_time 否 記録開始時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値が渡されない場合、デフォルトで当日の0時がクエリされます。
end_time 否 記録終了時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値が渡されない場合、デフォルトで当日の24時がクエリされます。
status 否 セッション状態(close)
page 否 ページ番号、1から開始、デフォルトは1
page_size 否 1ページあたりの件数、デフォルト 30、最大 1000

注意:

開始時間から終了時間までの最大期間は30日です。

start_time と end_time はデフォルトで会話の開始時間をクエリします。status=close の場合は会話の終了時間に基づいてクエリされます。

start_time と end_time のフォーマットは "YYYY-MM-DD hh:mm:ss" です。時間部分を省略して "YYYY-MM-DD" とすることもできます。

レスポンスデータ

属性名 タイプ 説明
status 整数 実行結果コード、0 は成功を表します
message 文字列 実行結果の説明
size 整数 今回返されたデータの件数
total 整数 データの総数
total_pages 整数 総ページ数
item 配列 会話記録リスト、各要素の内容はIM データを参照してください

例

curl https://demo.udesk.cn/open_api_v1/im/sessions/search?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

レスポンス

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "session_id": 1,
      "sub_session_id": 1,
      "note_id": null,
      "customer_id": 1,
      "customer_name": "テストユーザー",
      "customer_custom_fields": {},
      "agent_id": 1,
      "agent_nick_name": "テストカスタマーサポート",
      "created_at": "2015-01-01 12:00:00",
      "closed_at": "2015-01-01 12:30:00",
      "resp_seconds": 7,
      "queue_seconds": "未待機",
      "sustain_seconds": 128,
      "survey_vote_id": 1357334,
      "belong_queue": "queue_company_6_group_331",
      "agent_msg_num": 0,
      "customer_msg_num": 0,
      "source": "reocar.udesk.com",
      "source_url": "https://demo.udeskt.cn/im_client/",
      "queue_start_time": "2015-01-01 11:14:49",
      "conversations_num_today": 4,
      "platform": "web",
      "organization_id": null,
      "last_response": "customer",
      "alert_num": 1,
      "alert_desc": "センシティブワード1回,応答タイムアウト,セッションタイムアウト",
      "ticket_num": 2,
      "ticket_nos": "#140,#141",
      "im_web_plugin_id": 1,
      "sender": "customer",
      "active_guest": "agent",
      "menu_names": "ナビゲーションメニュー",
      "transfer_to_agent": "ボットから人間への転送",
      "robot_id": "ボットID",
      "robot_name": "ボット名",
      "close_method": "sys_close",
      "robot_session_id": 1,
      "resolved_state": "0",
      "web_info": {
        "login_url": null,
        "session_url": "https://demo.udesk.cn/im_client/",
        "keyword": null,
        "src": "demo.udesk.cn",
        "src_url": "https://demo.udesk.cn/im_client/",
        "sys": "Win7",
        "bowser": "Chrome56",
        "generated_channel": null,
        "ip": "123.123.123.123"
      },
      "ticket_ids": []
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

IM セッション記録の詳細を取得

このAPIは、特定のIMセッションの詳細情報を取得するために使用されます。

リクエストメソッド

GET /im/sessions/im_sub_session

リクエストパラメータ（クエリストリング）

パラメータ名 必須 説明
im_sub_session_id はい 1回のセッションのID

レスポンスデータ

属性名 タイプ 説明
status 整数 実行結果コード。0は成功を表します。
message 文字列 実行結果の説明
im_sub_session_log 配列 セッション記録の詳細。各要素の内容はIM データを参照してください。
im_log_infos 配列 チャット記録。詳細はim_log_infosパラメータ説明を参照してください。

例

curl http://demo.udesk.cn/open_api_v1/im/sessions/im_sub_session?im_sub_session_id=1234567&email=admin@udesk.cn&sign_version=v2&nonce=1646221853&timestamp=1646221853&sign=ca821bef91abcd6057ff04024282edbae0856281

レスポンス

{
    "status": 0,
    "message": "成功",
    "im_sub_session_log": [
        {
            "session_id": 1234567,
            "sub_session_id": 123456,
            "note_id": null,
            "customer_id": 123456,
            "customer_name": "xxx",
            "customer_custom_fields": {
                "SelectField_32412442": [
                    "123"
                ]
            },
            "agent_id": 123,
            "agent_nick_name": "xx",
            "created_at": "2022-03-02 15:12:31",
            "closed_at": "2022-03-02 15:13:20",
            "resp_seconds": 28,
            "queue_seconds": "未キューイング",
            "sustain_seconds": 49,
            "survey_vote_id": 123,
            "resolved_state_title": "問題は解決しましたか？1111111",
            "resolved_state_name": "解決済み解決済み解決済み解決済み",
            "resolved_state_value": "0",
            "platform": "web",
            "belong_queue": "queue_company_28480_agent_148002",
            "agent_msg_num": 3,
            "customer_msg_num": 2,
            "source": "demo.udesk.cn",
            "source_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
            "queue_start_time": "2022-03-02 15:12:31",
            "conversations_num_today": 1,
            "agent_invite_vote_count": null,
            "search_keyword": null,
            "custom_channel": null,
            "organization_id": null,
            "last_response": "agent",
            "alert_num": 1,
            "alert_desc": "センシティブワード",
            "ticket_num": 0,
            "ticket_nos": null,
            "im_web_plugin_id": 100042,
            "sender": "customer",
            "active_guest": "blank",
            "menu_names": null,
            "transfer_to_agent": false,
            "robot_id": null,
            "robot_name": null,
            "close_method": "agent_close",
            "robot_session_id": null,
            "resolved_state": "0",
            "web_info": {
                "login_url": null,
                "session_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "keyword": null,
                "src": "udesk-rd-bj-01.udesk.cn",
                "src_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "sys": "Win7",
                "bowser": "Chrome75",
                "generated_channel": null,
                "ip": "123.123.123.123"
            }
        }
    ],
    "im_log_infos": [
        {
            "id": 4359638049,
            "created_at": "2022-03-02 15:12:31",
            "sender": "customer",
            "user_id": 2618228342,
            "content": "{\"type\":\"message\",\"data\":{\"content\":\"有新的咨询进来了。\"},\"im_sub_session_id\":632362082,\"is_welcome\":true}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "message_id": "udesk_msg1742278813",
            "survey_option_id": 1
        },
        {
            "id": 4359638058,
            "created_at": "2022-03-02 15:12:32",
            "sender": "agent",
            "user_id": 148002,
            "content": "{\"type\":\"rich\",\"data\":{\"content\":\"<p><img src=\\\"https://pro-cs-freq.oss-cn-hangzhou.aliyuncs.com/config/imtid28480/1111_1639730293210_js9ng.jpg\\\" /><br />这是全局欢迎语，富文本我去问群</p>\"},\"push_type\":\"sys_welcome_msg\"}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "message_id": "udesk_msg1742278814",
            "survey_option_id": 1
        }
    ]
}

特定顧客のチャット記録リストを取得する

このAPIは、あるユーザーのチャット記録を一度に取得するために使用されます。レート制限：50回/60秒

リクエストメソッド

GET /im/sessions/customer_im_logs

リクエストパラメータ(Query String)

パラメータ名 タイプ 必須 説明 制限
type 文字列 はい 顧客を検索する条件タイプ 255文字以内
content 文字列 はい 顧客を検索する条件内容 255文字以内
start_time 日時 いいえ 記録開始時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値が渡されない場合、デフォルトで当日の0時となります。
end_time 日時 いいえ 記録終了時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値が渡されない場合、デフォルトで当日の24時となります。
page 整数 いいえ ページ番号、1から開始、デフォルトは1

条件タイプと内容の説明

値 対応する content の意味
id 顧客 id
email 顧客メールアドレス
cellphone 顧客電話番号
token 顧客外部一意識別子、対応する値は open_api_token
weixin_open_id 顧客WeChat openid
weibo_id 顧客Weibo openid

注意；

記録開始時間から終了時間までの最大期間は90日です;

start_time と end_time は im_sub_session の作成時間を検索します;

start_time と end_time のフォーマットは："YYYY-MM-DD hh:mm:ss"、または時間部分を省略した "YYYY-MM-DD" も可能です。

レスポンスデータ

属性名 タイプ 説明
status 整数 実行結果コード、0は成功を表します
message 文字列 実行結果の説明
size 整数 今回返されるデータの数量
total 整数 データ総数
total_pages 整数 総ページ数
item 配列 チャット記録リスト、各要素の内容は以下の通りです

item の内容

属性名 タイプ 説明
im_sub_session_id 整数 im_sub_session の id
im_log_infos 配列 im_sub_session 内のチャット記録、詳細は以下を参照

im_log_infos の内容

属性名 タイプ 説明
id 整数 im_log の id
created_at 日時 im_log の作成時間
sender 文字列 メッセージ送信者
user_id 整数 メッセージ送信者の id
nick_name 文字列 メッセージ送信者のニックネーム
message_id 文字列 メッセージid
content 配列 チャット内容、content内のtypeの詳細はこちら
### サンプル 
curl https://demo.udesk.cn/open_api_v1/im/sessions/customer_im_logs?email=admin@udesk.cn&sign_version=v2&nonce=1646278574&sign=b361abcdb6a8a2a42cc137498515cb4054bf32f2&timestamp=1646278574&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&type=id&content=43038556

レスポンスデータ

{
    "status": 0,
    "message": "成功",
    "item": [
        {
            "im_sub_session_id": 123,
            "im_log_infos": [
                {
                    "id": 1234,
                    "created_at": "2022-03-03 11:32:59",
                    "sender": "customer",
                    "user_id": 123456,
                    "message_id": "udesk_msg1742278814",
                    "nick_name": "低调",
                    "content": "{\"type\":\"message\",\"platform\":\"wechat\",\"data\":{\"content\":\"低调低调\",\"duration\":null,\"translation\":null}}"
                }
            ]
        }
    ],
    "size": 1,
    "total": 1,
    "total_pages": 1
}

チャット履歴リストの取得

このAPIは、指定されたIMセッションのチャット履歴情報を取得するために使用されます。 レート制限: 1回/2秒

リクエストメソッド

GET /im/sessions/log

リクエストパラメータ（クエリストリング）

パラメータ名 必須 説明
session_id はい IM セッション ID
start_time いいえ レコード開始時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値を渡さない場合、デフォルトで当日の0時が設定されます。
end_time いいえ レコード終了時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒となります。値を渡さない場合、デフォルトで当日の24時が設定されます。
page いいえ ページ番号、1から開始、デフォルトは1
page_size いいえ 1ページあたりの件数、デフォルト30、最大1000

start_time と end_time は、チャット履歴の作成時間を検索します。 start_time と end_time のフォーマットは "YYYY-MM-DD hh:mm:ss" です。時間部分を省略して "YYYY-MM-DD" とすることもできます。

返却データ

属性名 タイプ 説明
status 整数 実行結果コード、0 は成功を表します
message 文字列 実行結果の説明
size 整数 今回返却されたデータの数量
total 整数 データの総数
total_pages 整数 総ページ数
item 配列 チャット記録リスト、各要素の内容は下表を参照

item

属性名 タイプ 説明
id 整数 チャット記録ID
created_at 文字列 チャット作成時間
sender 文字列 対話の開始側 取り得る値："customer、agent、sys" 説明："顧客、サポート担当者、システム"
user_id 整数 送信者ID
content 文字列 メッセージ内容
message_id 文字列 メッセージID
session_id 整数 所属するセッション ID
sub_session_id 整数 所属するサブセッション ID
survey_option_id 整数 選択されたオプション ID

例

curl https://demo.udesk.cn/open_api_v1/im/sessions/log?email=admin@udesk.cn&sign_version=v2&nonce=1646275242&sign=f72ee9e4f1ef9c925e677538465a76b1be27cd74&timestamp=1646275242&session_id=4324143214&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&page_size=20

返却

{
    "status": 0,
    "message": "成功",
    "item": [
        {
            "id": 1234,
            "created_at": "2022-03-03 10:39:02",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"start_session\",\"data\":{\"content\":\"サポート担当者が手動で対話を作成\"}}",
            "message_id": "udesk_msg1742278814",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        },
        {
            "id": 1235,
            "created_at": "2022-03-03 10:39:05",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"message\",\"font\":\"font-size:13px;font-weight:normal;font-style:normal;text-decoration:none;color:#1f1f1f;line-height:1.4;\",\"data\":{\"content\":\"アストンサ\",\"richContent\":\"アストンサ\"},\"platform\":\"web\",\"version\":2,\"seq_num\":\"\"}",
            "message_id": "udesk_msg1742278815",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        }
    ],
    "size": 2,
    "total": 2,
    "total_pages": 1
}

満足度調査結果の取得

このAPIは、指定された複数の期間の満足度調査結果を一度に取得するために使用されます。 レート制限：1回/2秒

リクエストメソッド

GET /im/sessions/vote

リクエストパラメータ（クエリストリング）

パラメータ名 必須 説明
start_time いいえ レコード開始時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒になります。値が渡されない場合、デフォルトで当日の0時になります。
end_time いいえ レコード終了時間：値を渡す際に時分秒がない場合、デフォルトで0時0分0秒になります。値が渡されない場合、デフォルトで当日の24時になります。
page いいえ ページ番号、1から開始、デフォルトは1
page_size いいえ 1ページあたりの件数、デフォルト30、最大1000

start_time と end_time は、満足度調査結果の作成時間を検索します。 start_time と end_time の形式は "YYYY-MM-DD hh:mm:ss" です。時間部分を省略して "YYYY-MM-DD" とすることもできます。

レスポンスデータ

属性名 タイプ 説明
status 整数 実行結果コード、0は成功を表します
message 文字列 実行結果の説明
size 整数 今回返されたデータの件数
total 整数 データの総数
total_pages 整数 総ページ数
item 配列 満足度調査結果のリスト、各要素の内容は以下を参照してください

満足度調査結果

属性名 タイプ 説明
id 整数 一意の識別子
created_at 日時 作成時間
session_id 整数 所属するセッションID
sub_session_id 整数 所属するサブセッションID
survey_option_id 整数 選択されたオプションID

例

curl https://demo.udesk.cn/open_api_v1/im/sessions/vote?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

レスポンス

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "id": 1,
      "created_at": "2015-01-01 12:00:00",
      "session_id": 1,
      "sub_session_id": 1,
      "survey_option_id": 1,
      "resolved_state": "0",
      "survey_remark": "評価の備考",
      "tags": "評価タグ"
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

データ構造-IM

IM 会話記録

属性名 タイプ 説明
sub_session_id 整数 id （im_sub_session_idと同じ）
session_id 整数 セッション id
robot_session_id 整数 カスタマーサポートシステム側のロボットセッション id
note_id 整数 業務記録 id
customer_id 整数 顧客 id
customer_name 文字列 顧客名
customer_custom_fields オブジェクト 顧客カスタムフィールド、詳細は後述
agent_id 整数 エージェント id
agent_nick_name 文字列 エージェント名
resp_seconds 整数 応答時間、単位は秒
queue_seconds 文字列 待ち時間、単位は秒
sustain_seconds 整数 持続時間
survey_vote_id 整数 満足度調査結果 id
resolved_state 文字列 満足度-解決済みかどうか, 値:"0"、"1" 説明：解決済み、未解決
platform 文字列 チャネル、値：web、微信、微博、android、ios、api
web_info オブジェクト ブラウザアクセス情報、詳細は後述
weixin_info オブジェクト 微信アクセス情報、詳細は後述
weibo_info オブジェクト 微博アクセス情報、詳細は後述
api_info オブジェクト API アクセス情報
ios_info オブジェクト iOS SDK アクセス情報
android_info オブジェクト Android SDK アクセス情報
created_at 日時 作成時間
closed_at 日時 閉鎖時間
close_method 文字列 会話終了方法 値："agent_close"、"redirect_close"、"sys_close"、"customer_close" 説明：エージェント閉鎖、転送閉鎖、システム閉鎖、顧客閉鎖
belong_queue 文字列 待ち行列
agent_msg_num 整数 エージェントメッセージ数
customer_msg_num 整数 顧客メッセージ数
source 文字列 ソース
source_url 文字列 ソース url
queue_start_time 日時 待ち行列開始時間
conversations_num_today 整数 当日の会話回数
search_keyword 文字列 検索キーワード
custom_channel 文字列 カスタムチャネル情報
agent_invite_vote_count 整数 エージェントによる評価依頼回数
last_response 文字列 最後のメッセージ送信者 値： customer、agent、blank
alert_num 整数 アラート回数
alert_desc 文字列 アラート項目
ticket_num 整数 チケット数
ticket_nos 文字列 チケット番号、カンマ","で区切る
im_web_plugin_id 整数 ソースプラグイン ID
sender 文字列 会話開始者 値："customer、agent、sys" 説明："顧客、エージェント、システム"
active_guest 文字列 ビジター招待 値："agent、sys、blank" 説明："エージェント、自動、なし"
ticket_ids 配列 この会話記録に対応するチケット
organization_id 整数 会社id
menu_names 文字列 ナビゲーションメニュー名
#### 顧客ブラウザアクセス情報
属性名 型 説明
login_url 文字列
session_url 文字列
keyword 文字列
src 文字列
src_url 文字列 source_urlと同じ
sys 文字列
bowser 文字列
generated_channel 文字列
ip 文字列

微信アクセス情報

属性名 型 説明
name 文字列 顧客の微信ニックネーム

微博アクセス情報

属性名 型 説明
name 文字列 顧客の微博ニックネーム

API アクセス情報

属性名 型 説明
from 文字列 固定で"API"

iOS SDK アクセス情報

属性名 型 説明
phone_modal 文字列
phone_version 文字列
app_name 文字列
network_status 文字列
carrier 文字列
scale_screen 文字列

Android SDK アクセス情報

属性名 型 説明
phone_modal 文字列
phone_version 文字列
app_name 文字列
network_status 文字列
carrier 文字列
scale_screen 文字列

IM チャット履歴

属性名 型 説明
id 整数 一意の識別子
created_at 日付時刻 作成日時
sender 文字列 送信者の身分、agent または customer
user_id 整数 送信者 id
content 文字列 メッセージ内容
session_id 整数 所属するセッション id
sub_session_id 整数 所属するサブセッション id
survey_option_id 整数 満足度調査結果 id
## エラーコード説明
エラーコード message情報 exception:message情報 説明
2000 現在オンラインのサポート担当者がいません なし オンライン状態のサポート担当者がおらず、セッションを作成できません
2065 貴社はこのインターフェースを呼び出せません、Udesk技術サポートまでご連絡ください なし 現在の会社で「メッセージ送信プレビュー」機能が有効になっていません
9200 null なし 必須パラメータが入力されていません
ロボットパラメータエラー なし パラメータ{robot_id}または{scene_id}の値が誤っているか、データが見つかりません
パラメータ XXX、XXX が不足しています なし 必須パラメータ{XXX}が入力されていません
存在しない、または削除済みのセッションを評価しています XXX なし 必須パラメータ{im_sub_session_id}が入力されていないか、一致する値が見つかりません
不正な評価 なし 必須パラメータ{option_id}が入力されていません
重複評価はできません なし パラメータ{im_sub_session_id}に対応するセッションは既に評価済みです