インタラクションフロー

インタラクション図

Udesk API 共通説明

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

用語説明：

urobot、robot：同じ意味で、Udeskボットを表します。

顧客の作成

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

セッションの作成(オペレーター割り当てリクエスト)

POST /im/sessions

リクエストパラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい アプリケーション側の顧客一意識別子
assign_type 文字列 いいえ 希望する割り当てタイプ, 'robot', 'urobot', 'agent', デフォルトは 'robot'
agent_id 整数 いいえ 指定割り当てオペレーターID。指定された場合、assign_type と group_id は無視されます
group_id 整数 いいえ 指定割り当てオペレーターグループID。指定された場合、assign_type は無視されます
channel 文字列 いいえ カスタムチャネル
robot_role_id 文字列 いいえ 顧客ロール
robot_id 整数 いいえ UdeskボットID
scene_id 整数 いいえ Udeskボット対応シーンID
session_custom_fields オブジェクト いいえ セッションカスタムフィールド。keyはカスタムフィールドID（セッションカスタムフィールド設定で確認）、valueはカスタムフィールド値

customer_token は、顧客作成時の open_api_token と一致します。 agent_id と group_id の両方が指定されておらず、かつ assign_type が 'agent' の場合、システムの割り当てルールに従って割り当てられます。 robot_role_id は、事前にクラウド質問側で設定しておく必要があります。 assign_typeが'urobot'の場合、robot_idとscene_idは必須であり、robot_idはUdeskで定義されたボットIDです。取得方法はurobotリストの取得を参照してください。

このcustomer_tokenを使用するユーザーがシステムに存在しない場合、 Udeskは自動的に「API匿名ユーザー（customer_token）」という名前のユーザーを作成します。 括弧内のcustomer_tokenは、パラメータで渡された値です。

例

curl  'https://demo.udesk.cn/open_api_v1/im/sessions?email=admin@udesk.cn&sign_version=v2&timestamp=1648432914&sign=8a6wfe5dfd404d11a1e7fd5b7410b05ebdd561a4&nonce=1648632914&customer_token=828cw3d9-6a61-4afe-9efe-2c071d0e7cb3&assign_type=robot&agent_id=397' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
   "agent_id":"397",
   "customer_token":"827wd5r9-7a61-4afe-9efe-2c071d0e9cb2",
   "assign_type":"agent",
   "session_custom_fields":{
    "SessionField_1": "1234567890"
   }
}'

返却データ

属性名 型 説明
code 整数 実行結果コード、1000は成功を表す
message 文字列 割り当て成功時はウェルカムメッセージ、失敗時はエラーメッセージ
assign_type 文字列 割り当てタイプ, 'robot', 'agent', 'urobot'
assign_info オブジェクト 割り当て結果情報

assign_type によって assign_info の構造が異なります。

ロボット返却

assign_type が robot の場合、assign_info の構造は以下の通りです:

属性名 型 説明
robot_name 文字列 ロボット名
robot_avatar 文字列 ロボットのアバター
welcome_message 文字列 ウェルカムメッセージ
unknow_message 文字列 不明回答メッセージ

例

{
  "code": 1000,
  "message": "リクエスト成功",
  "assign_type": "robot",
  "assign_info": {
    "robot_name": "Udeskカスタマーサポートロボット",
    "robot_avatar": "https://rd-dota.udesk.cn/entry/images/agent-avatar-3e6a68e1e1fcb4db653d9e93263f7946.png",
    "welcome_message": "<p>こんにちは、私はインテリジェントカスタマーサポートロボットです。関連する業務に関する質問にお答えできます。何か質問があればお聞かせください！ ご利用いただきありがとうございます！</p><p><br/></p>",
    "unknow_message": "<p>申し訳ございません。現在は一般的な業務関連の質問にしかお答えできません！この質問は現在私の知識範囲外です。引き続き努力して学習します！別の簡単な言い方で質問していただければ、お答えできるかもしれません...</p>"
  }
}

assign_type が 'urobot' の場合、assign_info の構造は以下の通りです:

属性名 型 説明
sessionId 整数 セッションID
logId 整数 このログのID
leadingWord 文字列 リード文
helloWord 文字列 ウェルカムメッセージ
robotName 文字列 ロボット名
logoUrl 文字列 ロボットのアバター
topAsk オブジェクト よくある質問リスト

例

リクエスト

curl  'https://test.udesk.cn/open_api_v1/im/sessions?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "customer_token":"test20191018224601",
  "assign_type":"urobot",
  "scene_id":39,
  "robot_id":12362
}'

返却

{
  "code": 1000,
  "message": "リクエスト成功",
  "assign_type": "urobot",
  "assign_info": {
    "sessionId": 23702,
    "logId": 55392,
    "robotName": "テスト",
    "logoUrl": null,
    "leadingWord": "こんにちは、ご利用いただきありがとうございます！",
    "helloWord": "こんにちは、ご利用いただきありがとうございます！",
    "topAsk": [
      {
        "quesitionType": "質問タイプ１",
        "quesitionTypeId": 2,
        "optionsList":[
          {
            "quesition":"質問１",
            "quesitionId": 2122
          },
          {
            "quesition": "質問２",
            "quesitionId": 3222
          }
        ]
      }
    ]
  }
}

カスタマーサポートへのリクエスト返信

assign_type が agent の場合、assign_info の構造は以下の通りです：

属性名 型 説明
im_sub_session_id 整数 セッションID
count 整数 待ち順位
queue 文字列 待ち行列
agent_id 整数 割り当てられたサポート担当者のID
agent_name 文字列 割り当てられたサポート担当者の名前
agent_avatar 文字列 サポート担当者のアバター画像アドレス
survey_options オブジェクト 満足度評価の設定

例

リクエスト
curl  'https://test.udesk.cn/open_api_v1/im/sessions?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  {
  "customer_token":"test20191018224601",
  "assign_type":"agent"
}
}'
正常な返信
{
  "code": 1000,
  "message": "リクエスト成功",
  "assign_type": "agent",
  "assign_info": {
    "im_sub_session_id": 1234,
    "count": 0,
    "agent_id": 3,
    "agent_name": "Tom",
    "agent_avatar": "",
    "survey_options": "survey_optionsの節を参照",
  }
}
待ち行列の返信
{
  "code": 2001,
  "message": "現在サポート担当者が多忙です。お客様は3番目に並んでいます。",
  "assign_type": "agent",
  "assign_info": {
    "count": 3,
    "queue": "queue:company:1:agent:486"
  }
}
割り当て境界
{
  "code": 2001,
  "message": "サポート担当者を割り当て中です！",
  "assign_type": "agent",
  "assign_info": {
    "count": 0,
  }
}
サポート担当者がオンラインでない
{
  "code": 2002,
  "message": "現在オンラインのサポート担当者はいません",
  "assign_type": "agent",
  "assign_info": {
    "count": 0,
  }
}
survey_options 
"survey_options":
    "enabled": true,   # 有効かどうか
    "name": "満足度評価",
    "title": "本サービスの評価はいかがでしたか?",  # 顧客に表示するプロンプト
    "desc": "ご利用いただきありがとうございます。より良いサービスを提供するために、今回のサービスについて評価をお願いいたします（文字で返信してください）",  # 微信/微博API満足度評価ガイダンス
    "remark_enabled": true,  # 評価コメントを記入可能かどうか
    "remark": "評価コメントを記入できます", # 評価コメントのヒント
    "show_type": String text|expression|star  // 満足度の種類
    text: {  // オプション、show_typeがtextの場合に表示
        default_option_id:
        options: [{
          id:
          text: 非常に満足|満足|普通|不満|非常に不満 (変更可能、BIに表示)
          desc: 変更不可
          tags: "tag1,tag2"  // カスタム評価タグ 例: サービスが良い、専門性が高い、対応が良い...
          remark_option: hide|required|optional
          }]
      },
      expression: { // オプション、show_typeがexpressionの場合に表示
        default_option_id:
        options: [{
          id:
          text: 満足|普通|不満
          tags: "tag1,tag2"
          remark_option: hide|required|optional
          }]
      },
      star: {  // オプション、show_typeがstarの場合に表示
        default_option_id:
        options: [{
          id:
          text: 満足|普通|不満
          tags: "tag1,tag2"
          remark_option: hide|required|optional
          }]
      },
    "options": [    #  互換モード、評価オプション/ idは /im_sessions/survey の option_id に対応
      {
        "id": 36,
        "text": "非常に満足2",
        "enabled": true
      },
      {
        "id": 37,
        "text": "満足2",
        "enabled": true
      },
      {
        "id": 38,
        "text": "普通2",
        "enabled": true
      },
      {
        "id": 39,
        "text": "不満",
        "enabled": true
      },
      {
        "id": 40,
        "text": "非常に不満",
        "enabled": true
      }
    ],
    "methods": [  # 満足度評価方法
      {
        "id": 7,
        "flag": "after_session",
        "text": "セッション終了後にポップアップ",
        "enabled": true
      },
      {
        "id": 74,
        "flag": "agent_invite",
        "text": "カスタマーサポートからの招待",
        "enabled": true
      },
      {
        "id": 1485,
        "flag": "customer_invite",
        "text": "顧客からの満足度評価（webおよびAndroid/iOS SDKのみ対応）",
        "enabled": true
      }
    ],
    "resolved_enabled": true,
    "resolved_options": {
      "title": "お問い合わせは解決しましたか?",
      "options": [
      {
        "option_select": true,
        "option_name": "解決済み"
      },{
        "option_select": true,
        "option_name": "未解決"
      }],
      "value": "0" # オプションのデフォルト値
    }

セッションを閉じる

顧客が指定したセッションを自発的に閉じる

DELETE /im/sessions/:session_id

リクエストパラメータ

パラメータ名 タイプ 必須 説明
session_id 整数 はい セッションID, URL内

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表す

例

$ curl -XDELETE 'https://demo.udesk.cn/open_api_v1/im/sessions/123?session_id=123&email=admin@udesk.cn&sign_version=v2&timestamp=1645198019&sign=925f7a1a4ec944f52d59d33a9e35cb6e2478e589&nonce=1648194019'

セッションを削除する

既に閉じられたセッションを削除する

リクエストメソッド

DELETE /im/sessions/destroy_session

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

パラメータ名 必須 タイプ 説明
start_time はい 文字列 例 2022-05-19 19:50:33
end_time はい 文字列 例 2022-05-19 20:50:33
customer_id いいえ 整数 このパラメータを渡す場合、指定した時間範囲内の該当顧客の会話記録のみを削除します。渡さない場合、指定した時間範囲内のすべての会話記録を削除します

start_time と end_time は、セッションの作成時間をクエリします。

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000 は成功を表す

例

リクエスト

curl -X DELETE 'https://test.udesk.cn/open_api_v1/im/sessions/destroy_session?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&start_time=2022-05-19%2019%3A50%3A33&end_time=2022-05-19%2020%3A50%3A33&customer_id=123123'

レスポンス

{
"code": 1000
}

待ち行列の放棄

顧客が指定した待ち行列を自発的に閉じて放棄する

DELETE /im/sessions/close_queue

リクエストパラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい アプリ側の顧客一意識別子
queue 文字列 はい 待ち行列。セッション作成時に選択し、待機時に返された待ち行列データ

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表す

例

$ curl -XDELETE 'https://test.udesk.cn/open_api_v1/im/sessions/close_queue?customer_token=123qwe&queue=queue:company:1:agent:486&email=admin@test.com&sign=61b00dedbc749691232386fed059898af61b92c&timestamp=1526293384'

メッセージプレビューの送信

APIクライアントがメッセージプレビューをカスタマーサポートに送信する（セッションの割り当てタイプassign_typeはagentである必要がある）

PUT /im/sessions/:session_id/message_preview

注意: このインターフェースは個別に有効化する必要があります。 このインターフェースには独立した頻度制限があります: 各 session_id は1秒間に3回まで呼び出せます。

リクエストパラメータ

パラメータ名 タイプ 必須 説明
session_id 整数 はい セッションID, URL内
content 文字列 はい プレビュー内容テキスト、空文字列の場合はプレビューをクリアします, リクエストボディ内

メッセージプレビューをクリアするいくつかの方法: 1. カスタマーサポートが顧客からのメッセージを受信すると、プレビュー内容は自動的にクリアされます; 2. このインターフェースを呼び出し、同時にcontentに空文字列を渡すと、対応するセッションのメッセージプレビューもクリアされます。

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表す

エラーレスポンス

code 値 message 説明
2062 セッションが見つからない、またはセッションが閉じられています
2065 このインターフェースが有効化されていません
### サンプル

リクエスト

curl 'https://test.udesk.cn/open_api_v1/im/sessions/1/message_preview?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
-X PUT \
-H 'Content-Type: application/json' \
-d '{"content": "テストプレビュー"}'

レスポンス

{
"code": 1000
}

メッセージ送信

APIクライアントがカスタマーサポートにメッセージを送信します（セッションの割り当てタイプassign_typeはagentである必要があります）

POST /im/messages

注意: ボットに送信するメッセージの type パラメータは、現在 'message' タイプのみサポートしています

リクエストパラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい アプリケーション側の顧客一意識別子
im_sub_session_id 整数 はい 1. セッションID
2. IDが0または空の場合はボット質問
3. IDが-1の場合はUdeskボット質問
4. -2はIMワークベンチのメッセージ
5. -3は待機中にメッセージを送信
message_id 文字列 はい メッセージID/会社メッセージ一意識別子（Udeskボットは省略可能）
英字、数字、"_"、"-"のみサポート、特殊文字は禁止
type 文字列 いいえ メッセージタイプ, 'message', 'image', 'audio', 'rich', デフォルトは 'message'
data オブジェクト はい メッセージ内容 (詳細は メッセージ内容フォーマット)
quote_message_id 文字列 いいえ 引用メッセージのmessage_id(今回の会話内のメッセージのみ引用可能、ボットメッセージはサポート対象外)
send_status 文字列 いいえ 値の参照 取り消し:'rollback'(2分以内に取り消し可能)
robot_id 整数 いいえ UdeskボットID(Udeskボットの場合は必須)
scene_id 整数 いいえ Udeskボット対応シーンID(Udeskボットの場合は必須)
urobot_session_id 整数 いいえ Udeskボット対応セッションID
agent_id 整数 いいえ 指定割り当てカスタマーサポートID im_sub_session_id=-2と併用
group_id 整数 いいえ 指定割り当てカスタマーサポートグループID im_sub_session_id=-2と併用
### レスポンスデータ
属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します

エラーレスポンス(assign_typeが'robot'の場合)

code 値 message 説明
1 9200 セッションが存在しない/セッションは閉じられています
2 2062 パラメータが不足しています

例

リクエスト

curl 'https://test.udesk.cn/open_api_v1/im/messages?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
  "customer_token":"1234123123",
  "im_sub_session_id":11,
  "message_id":"1",
  "type":"image",
  "data":{
      "content": "本公司促销产品走过路过不要错过 <a href=\"https://xxx.com/1.png\">热销.com</a>"
    }
}'

レスポンス

{
"code": 1000
}

顧客のオフライン未読メッセージを取得

指定された顧客とセッション内のサポートスタッフから顧客に送信されたオフライン未読メッセージの数と詳細を取得します

GET /im/messages/unread_customer_offline

リクエストパラメータ

パラメータ名 タイプ 必須 説明
im_sub_session_id 整数型 はい セッションID
customer_id 整数型 はい 顧客ID
app_id 整数型 いいえ SDK app_id SDKチャネルセッションを読み取る必要がある場合、このパラメータを渡します

レスポンスデータ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
count 整数型 未読メッセージ数
unread_messages 配列 メッセージの集合、集合内の要素は未読メッセージの詳細です。詳細は メッセージ内容フォーマット を参照してください

リクエスト例


curl https://demo.udesk.cn/open_api_v1/im/messages/unread_customer_offline?im_sub_session_id=1419314&customer_id=5855308&email=admin@udesk.cn&sign_version=v2&timestamp=1646827326&sign=06f59041bbbec54bd2a0b15b45672c9f43539135&nonce=1646827326

顧客のオンライン状態を変更

顧客のオンライン状態を変更します。

POST /im/customer_online_state

リクエストパラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい OpenApi 顧客一意識別子
state 整数 はい オフライン：0；オンライン：1

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します

リクエスト例


curl https://demo.udesk.cn/open_api_v1/im/customer_online_state?customer_token=5855308&state=0&email=admin@udesk.cn&sign_version=v2&timestamp=1646827326&sign=06f59041bbbec54bd2a0b15b45672c9f43539135&nonce=1646827326

カスタマーサポートメッセージの既読状態を変更

カスタマーサポートメッセージの既読状態を変更します。

POST /im/messages/read_messages

リクエストパラメータ

パラメータ名 タイプ 必須 説明
session_id 整数 はい セッションID
message_ids 文字列配列 はい ["udesk_211679991890796","udesk_211679991890797"] メッセージID配列

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します

リクエスト例


curl https://demo.udesk.cn/open_api_v1/im/messages/read_messages?session_id=1234&message_ids=['123','123456']&email=admin@udesk.cn&sign_version=v2&timestamp=1646827326&sign=06f59041bbbec54bd2a0b15b45672c9f43539135&nonce=1646827326

エージェントの未読メッセージを取得

エージェントの未読メッセージとは、顧客がエージェントに正常に送信したが、エージェントがまだ読んでいないメッセージです。

指定されたセッションにおけるエージェントの未読メッセージ数と、7日以内に未処理の留守番メッセージ数を取得します。

GET /im/messages/agent_unread_messages

リクエストパラメータ

パラメータ名 タイプ 必須 説明
agent_ids 配列 はい エージェントIDの配列、最大30件まで

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード
results オブジェクト配列 返却結果セット
results.agent_id 整数 エージェントID
results.unread_session_message_num 整数 未読メッセージ数
results.unsolved_leave_message_num 整数 7日以内に未処理の留守番メッセージ数

リクエスト例


curl https://demo.udesk.cn/open_api_v1/im/messages/agent_unread_messages?email=admin@udesk.cn&sign_version=v2&timestamp=1646817998&sign=7ab7fb49d9c32ea246504b3af75a9w65210bca87&nonce=1646827998&agent_ids[]=13

顧客メッセージの既読ステータスを送信

リクエストメソッド

顧客メッセージの既読ステータスを送信します。

POST {接收消息URL}

メッセージ受信URLは、管理者->設定->チャネル管理->インターフェースメッセージで設定してください。

リクエストパラメータ

パラメータ名 タイプ 必須 説明
session_id 整数 はい セッションID
message_ids 文字列配列 はい メッセージIDのリスト

レスポンスデータ

HTTPステータスコード200を返し、レスポンスボディは空で構いません。

注意:

メッセージ返信通知

リクエスト方法

カスタマーサポートがAPIクライアントにメッセージをプッシュします。

POST {接收消息URL}

プッシュ形式は JSON です。 メッセージ受信URLは、管理者 -> 設定 -> チャネル管理 -> インターフェースメッセージ で設定してください。

リクエストパラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい アプリケーション側の顧客を一意に識別するもの
assign_type 文字列 はい 割り当てタイプ, 'robot', 'agent', 'urobot'
messages オブジェクト配列 はい メッセージ

assign_type によって、message の形式が異なります。

assign_type が 'robot' の場合、message の形式は以下の通りです。

messages: オブジェクト配列
  type: メッセージタイプ
  message_id: メッセージID, 文字列
  data: メッセージ内容
    question_id: 0の場合は挨拶ライブラリ、Q&Aではない; 0以外の場合は、Q&Aに対して有用/無用の評価が可能
    question_title: 質問内容, 文字列
    answer: 質問の回答テキスト, 文字列
    gus_list: 質問ガイドリスト
      - question_title: 質問内容, 文字列
    relate_list: 関連質問リスト
      - question_title: 質問内容, 文字列
    third_url: 関連おすすめリンク
      url: リンクアドレス, 文字列

{
  "customer_token": "axb",
  "assign_type": "robot",
  "messages": [{
    "type": "message",
    "message_id": "f862f80d-89aa-4f31-92d9-ccd4fcacffcf",
    "data": {
      "question_id": 210530,
      "question_title": "会社の事業内容は何ですか",
      "answer": "こんにちは、私たちはクラウドカスタマーサポートを提供する会社です！開発なしで、WeChat、Weibo、Web上のユーザーとコミュニケーションや管理ができます。",
      "gus_list": [
        {"question_title": "どのような業務を行っていますか"},
        {"question_title": "御社の事業内容は何ですか"}
      ],
      "relate_list": [
        {"question_title": "会社の所在地はどこですか"},
        {"question_title": "連絡先は何ですか"}
      ],
      "third_url": {
        "url": "https://www.udesk.cn"
      }
    }
  }
  ]
}

assign_type が 'urobot' の場合、message の形式は以下の通りです。

messages: オブジェクト
  sessionId: セッションID, 文字列
  logId: メッセージのID
  aid: 回答ID
  ansContent: 回答内容
  ansType: 回答タイプ (1は通常回答、2は回答と提案リスト、3は提案リスト、4は挨拶返信、6は不明な応答、8はセンシティブワード)
  hitQuestion: 質問内容
  suggestQuestionList: 提案リスト
  flowId: 現在のフローID,
  flowTitle: 現在のフロータイトル,
  flowContent: 現在のフロー回答,

    {
      "sessionId": 1835244,
      "logId": 3574331,
      "aid": 12,
      "ansContent": "申し立てフロー",
      "ansType": 1,
      "hitQuestion": "アカウント申し立て",
      "suggestQuestionList": [
      {
          "id": 434,
          "content": "問題1",
          "type": 1
        }
      ]
    }

assign_type が 'agent' の場合、messages の形式は以下の通りです。

messages:
  type: メッセージタイプ, 'message', 'image', 'audio', 'video', 'file', 'rich(リッチテキストメッセージ)', 'struct(構造化セッション)', 'survey(満足度評価関連イベント)', 'transfer(転送イベント)', 'info_transfer(転送イベント、属性の違いによる)'
  message_id: メッセージID
  agent_id: カスタマーサポートID
  agent_name: カスタマーサポート名
  agent_avatar: カスタマーサポートのアバター
  im_sub_session_id: セッションID
  message_created_at: メッセージ作成時間 "20170711 09:52:11"
  data: 送信メッセージ内容と同じ
    font: フォント, messageのみサポート
    content: 内容

{
  "customer_token": "axb",
  "assign_type": "agent",
  "messages": [
    {
    "type": "start_session",
    "message_id": "xxxxx",
    "agent_id": 1,
    "agent_name": "TOM",
    "agent_avatar": "https://123.com/1.png",
    "im_sub_session_id": 3,
    "message_created_at": "20170711 09:52:11",
    "data": {
      "content": "会話開始"
    }
    },{
    "type": "message",
    "message_id": "xxxxx",
    "agent_id": 1,
    "agent_name": "TOM",
    "agent_avatar": "https://123.com/1.png",
    "im_sub_session_id": 3,
    "message_created_at": "20170711 09:52:12",
    "data": {
      "font": "フォント, messageのみサポート",
      "content": "こんにちは、何かお手伝いできることはありますか？",
    }
  },
  {
    "type": "rich",
    "message_id": "xxxxx",
    "agent_id": 1,
    "agent_name": "TOM",
    "agent_avatar": "https://123.com/1.png",
    "im_sub_session_id": 3,
    "message_created_at": "20170711 09:52:13",
    "data": {
      "content": "当社のプロモーション商品、見逃さないでください <a href=\"https://xxx.com/1.png\">人気商品.com</a>",
    }
  },
  {
    "type": "close",
    "message_id": "xxxxx",
    "agent_id": 1,
    "agent_name": "TOM",
    "agent_avatar": "https://123.com/1.png",
    "im_sub_session_id": 3,
    "message_created_at": "2018-01-01 00:00:00",
    "data": {
        "close_type": "normal(通常)|redirect(転送)|force(強制)"
        "content": "セッションを閉じる",
        "survey_options": "survey_optionsの節を参照",
      }
  }
  ]
}

返却データ

HTTPステータスコード200を返し、レスポンスボディは空で構いません。

注意:

メッセージ内容フォーマット

type タイプ及びサポートリスト

タイプ type 意味 送信 受信 備考
メッセージ message テキストメッセージ ✓ ✓
メッセージ image 画像メッセージ ✓ ✓
メッセージ audio 音声メッセージ ✓ × amrフォーマットをサポート
メッセージ video 動画メッセージ ✓ × mp4フォーマットをサポート
メッセージ file ファイルメッセージ ✓ ×
メッセージ rich リッチテキストメッセージ ✓ ✓ 一般的なHTMLタグをサポート
メッセージ struct 構造化メッセージ × × 現在はサポートされていません
イベント start_session セッション開始 × ✓ セッション開始時に顧客にプッシュ
イベント transfer 転送イベント × ✓ 顧客が転送された時に顧客にプッシュ。顧客はim_sub_session_idを新しいものに変更する必要があります
イベント info_transfer 転送イベント表示内容 × × 顧客が転送された時にカスタマーサポートに表示されるヒント内容
イベント close セッション終了イベント ✓ ✓ 顧客セッションが終了された時に顧客にプッシュ
イベント survey 満足度評価関連イベント × × カスタマーサポートIMワークベンチでのみ表示されます
イベント active_guest カスタマーサポートによるアクティブセッションイベント × × Webビジターのみサポート
イベント info_appoint カスタマーサポートによる顧客割り当てイベント × × 現在はサポートされていません
イベント form フォームメッセージ送信イベント × × 現在はサポートされていません
イベント form_received フォームメッセージ受信イベント × × 現在はサポートされていません
イベント info 事前問い合わせフォーム is_receive: false × × カスタマーサポート表示専用
イベント robot_transfer ロボットから転送されたセッション × × カスタマーサポート表示専用

注: サポートされていない/現在サポートされていない/カスタマーサポート表示専用のメッセージは、クライアント側で表示・処理しないでください。

メッセージ内容詳細

type の種類によって、data の構造も異なります：

# 通常メッセージ
type: 'message'
data:
    font: フォント形式, 任意, 例：
    content: テキスト内容  注: テキスト内容にはリッチテキストHTMLタグを含めることができます

# 画像メッセージ
type: 'image'
data:
    content: url

# 音声メッセージ
type: 'audio'
data:
    content: url
    filename: 'サッカー.mp4' #
    filesize: "4.3M"
    duration: 200       # 音声の長さ、ない場合もあります # 単位は秒

type: 'video'  # mp4のみサポート
data:
    content: url
    filename: 'サッカー.mp4' # ファイル名
    filesize: "4.3M"    # ファイルサイズ

type: 'rich'  # サポート
data:
    content: <p>こんにちは、小雅カスタマーサポートがご案内いたします。何かお手伝いできることはありますか？</p>

# type: struct  構造化メッセージ, 現在は web/sdk のみサポート
# 関連ドキュメント <https://www.udesk.cn/website/doc/apiv1/im/#im_2>

# start_session セッション開始,通常は配列でプッシュされ、後にウェルカムメッセージが続きます
type: "start_session",
data:
  content: "会話開始"

# transfer セッションが転送されました,通常は配列でプッシュされ、後に転送内容のメッセージが続きます 例: 'セッション転送成功、カスタマーサポートxxがご対応いたします'
type: "transfer",
data:
  content: "セッション転送"

type: "info_transfer",
data:
  content: "カスタマーサポートJerry213がセッションを転送しました"

type: "close",
data:
  content: "セッション終了"

ロボットQ&A評価

パラメータ

パラメータ名 タイプ 必須 説明
customer_token 文字列 はい アプリ側の顧客一意識別子
message_id 文字列 はい 評価対象のロボット回答のメッセージID
question_id 整数 はい 質問ID
useful ブール はい 質問が役に立ったかどうか

戻り値

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します

urobotロボットセッション評価（urobot使用時)

POST /im/sessions/robot_survey

パラメータ

属性名 タイプ 必須 説明
customer_token 文字列 はい アプリ側の顧客一意識別子
im_sub_session_id 整数 はい セッションID
option_id 整数 はい 評価オプションID (2：満足 3：普通 4：不満足)
remark 文字列 いいえ 評価備考
robot_id 整数 はい UdeskロボットID（システム内の インスタントメッセージ->IMロボット モジュールで取得）
scene_id 整数 はい Udeskロボット対応シーンID

返却データ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表す
message 文字列 返却メッセージ

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/sessions/robot_survey?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '{
"customer_token":"1234121123123",
"im_sub_session_id":101,
"option_id":2,
"robot_id":1101,
"scene_id":39,
"remark":"非常满意"
}'

レスポンス

{
"code": 1000,
"message": "評価いただきありがとうございます"
}

セッション評価（カスタマーサポート評価）

POST /im/sessions/survey

リクエストパラメータ

パラメータ名 必須 タイプ 説明
im_sub_session_id はい 整数 セッションID
option_id はい 整数 評価オプションID
remark いいえ 文字列 評価備考
resolved_state_v2 いいえ 整数 解決済みかどうかのオプション値 0(オプション1は解決済みを表す)1(オプション2は未解決を表す)

返却データ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/sessions/robot_survey?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '{
  "im_sub_session_id":1001001000,
  "option_id":"111"
}'

返却

{
"code": 1000,
"message": "評価いただきありがとうございます"
}

問題評価(urobot専用)

POST /im/messages/answer_survey

リクエストパラメータ

属性名 タイプ 必須 説明
customer_token 文字列 はい アプリケーション側の顧客一意識別子
messgae_id 整数型 はい 問題の回答が含まれるメッセージID
im_sub_session_id 整数型 はい セッションID
option_id 整数型 はい 評価オプションID(1は満足、2は不満足、デフォルトは満足)
robot_id 整数型 はい UdeskロボットID
scene_id 整数型 はい Udeskロボット対応シーンID

返却データ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
message 文字列型 返却情報

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/messages/answer_survey?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '{
  "customer_token":"123411111",
  "messgae_id":111,
  "im_sub_session_id":11,
  "option_id":1,
  "robot_id":12,
  "scene_id":1
}'

返却

{
"code": 1000,
"message": "評価いただきありがとうございます"
}

フロー問題インターフェース

POST /im/messages/flow

urobot専用

リクエストパラメータ

属性名 タイプ 必須 説明
customer_token 文字列 はい アプリ側顧客の一意識別子
im_sub_session_id 整数 はい セッションID
flow_id 整数 はい 選択されたflow_id
robot_id 整数 はい UdeskロボットID
scene_id 整数 はい Udeskロボット対応シーンID

flow_idの取得方法:

プッシュメッセージに messages.flowContent フィールドがあり、かつタグに data-type="2" が含まれている場合、このインターフェースを呼び出すことができます。

例:

<p><b data-type="2" class="flow-item" data-id="81" data-robotid="54">フロー項目Aサブ項目-1</b></p><p>フロー項目Aサブ項目-2<br></p>
<p><b data-type="1" class="flow-item" data-id="307" data-robotid="54">分類問題A</b></p><p>分類問題B</p>

フロー項目Aサブ項目-1 をクリックした場合、flow_id=81 を使用してこのインターフェースを呼び出すことができます。

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します

プッシュデータについては、urobot返信メッセージ通知インターフェースのレスポンスを参照してください。

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/messages/flow?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '{
  "customer_token":"1234121123123",
  "messgae_id":1001,
  "im_sub_session_id":17001700,
  "option_id":1,
  "robot_id":1,
  "scene_id":1
}'

レスポンス

{
"code": 1000
}

ユーザークリック行動インターフェース

POST /im/messages/hit

リクエストパラメータ

属性名 タイプ 必須 説明
customer_token 文字列 はい アプリ側顧客の一意識別子
im_sub_session_id 整数 はい セッションID
message_id 整数 はい ロボット回答のメッセージID
robot_id 整数 はい ロボットID
question 整数 いいえ 質問内容
query_type 整数 はい クリックタイプ 6：よくある質問クリック 7：提案リストクリック
### レスポンスデータ
属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/messages/hit?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: application/json' \
-d '{
  "customer_token":"111",
  "message_id":1,
  "im_sub_session_id":10,
  "robot_id":1,
  "scene_id":1,
  "question_id":1,
  "query_type":1

}'

レスポンス

{
"code": 1000
}

urobotリストの取得

GET /im/urobots

レスポンスデータ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
message 文字列型 レスポンス結果メッセージ
urobot_list オブジェクト配列 ロボットリストの詳細情報

urobot_list

属性名 タイプ 説明
id 整数型 urobotロボットID
name 文字列型 ロボット名
logo 文字列 ロボットアイコン
scene_list オブジェクト配列 適したシーン情報、id（シーンID）、name（シーン名）を含む
created_at 文字列 ロボットの作成時間

例

リクエスト

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

レスポンス

{
  "code": 1000,
  "message": "リクエスト成功",
  "urobot_list": [
    {
      "id": 2,
      "name": "デフォルトロボット",
      "logo": "",
      "scene_list": [
        {
          "id": 114,
          "name": "デフォルトシーン"
        },
        {
          "id": 116,
          "name": "システムデフォルトシーン"
        }
      ],
      "created_at": "2018-01-23T10:55:20.000+08:00"
    },
    {
      "id": 3,
      "name": "テスト",
      "logo": "",
      "scene_list": [
        {
          "id": 120,
          "name": "システムデフォルトシーン"
        }
      ],
      "created_at": "2018-02-05T11:25:30.000+08:00"
    }
  ]
}

人工転送統計インターフェース(urobot使用)

POST /im/sessions/transfer_survey

リクエストパラメータ

パラメータ名 タイプ 必須 説明
im_sub_session_id 整数 はい セッションID
robot_id 整数 はい ロボットID
scene_id 整数 はい ロボットシーンID

レスポンスデータ

属性名 タイプ 説明
code 整数 ステータス
message 文字列 リクエスト結果

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/sessions/transfer_survey?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '{
  "im_sub_session_id":"111",
  "robot_id":1,
  "scene_id":10
}'

レスポンス

{
    "code": 1000,
    "message": "success"
}

待ち行列ステータス照会

GET /im/queue_status

リクエストパラメータ

パラメータ名 必須 説明
customer_token はい アプリ側顧客の一意識別子

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表す
status 文字列 待ち行列ステータス, '待ち行列中', '未待ち行列', 'セッション中', '割り当て中'
count 整数 待ち行列位置

例

リクエスト

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

レスポンス

{
    "code": 1000,
    "status": "未待ち行列",
    "count": 0
}

顧客ステータス照会

顧客がセッション中かどうかを確認するために使用され、customer_token / web_token / sdk_token による顧客照会をサポートします。

GET /im/customer_status

リクエストパラメータ

パラメータ名 必須 説明
customer_token いいえ OpenApi 顧客一意識別子
web_token いいえ web 顧客一意識別子
sdk_token いいえ sdk 顧客一意識別子
session_key いいえ web_token が存在する場合、複数セッションの異なるセッション状態をサポート

注: customer_token/web_token/sdk_tokenのいずれか1つが必須です。値がある最初のパラメータが順番に使用されます。

レスポンスデータ

属性名 型 説明
code 整数 実行結果コード、1000は成功を表します
status_code 整数 0,1,2,3
status 文字列 'セッションなし','セッション中','待機中','無効な顧客'

例

リクエスト

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

レスポンス

{
    "code": 1000,
    "status_code": 0,
    "status": "セッションなし"
}

エージェントステータス照会

現在のすべてのエージェントのオンラインステータスを確認します。

GET /im/agent_status

リクエストパラメータ

パラメータ名 必須 説明
group_id いいえ 特定のエージェントグループのみを表示する場合

指定がない場合は、すべてを返します。

レスポンスパラメータ

属性名 型 説明
code 整数 実行結果コード、1000は成功、11012は指定されたグループが存在しないことを表します
agents 配列 エージェントデータを返します。詳細はエージェントステータス詳細を参照してください
#### エージェントステータスの詳細
属性名 タイプ 説明
id 整数型
name 文字列 エージェント名
nick 文字列 エージェントのニックネーム。顧客に表示される。空の場合はエージェント名が表示される
avatar 文字列 エージェントのアバター
im_status 文字列 オンラインステータス online/busy/offline (オンライン/取り込み中/オフライン)
im_custom_status 文字列 カスタムステータス。im_statusがbusyの場合のみ有効
im_session_num 整数型 現在の対応人数。im_statusがonline/busyの場合のみ有効。0の場合や数値があっても意味を持たない場合がある
im_max_join_num 整数型 エージェントの最大対応人数。im_statusがonline/busyの場合のみ有効。0の場合や数値があっても意味を持たない場合がある

例

リクエスト

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

レスポンス

{
    "code": 1000,
    "agents": [
        {
            "id": 43230,
            "name": "張雪松",
            "im_nick": "張",
            "avatar": "",
            "profile": "all",
            "im_status": "offline",
            "im_custom_status": "",
            "im_session_num": 1,
            "im_max_join_num": 10
        },
        {
          ...
        },
        ...
    ]
}

放棄待機クエリ

待機を放棄したユーザー情報を取得するために使用されます

リクエスト

GET /im/im_queues

パラメータ

パラメータ名 必須 説明
start_time はい 開始時間
end_time はい 終了時間
page いいえ ページ番号、1から開始、デフォルトは1
per_page いいえ 1ページあたりの件数、デフォルト30、最大100

レスポンスデータ

属性名 型 説明
code 整数型 実行結果コード、1000は成功を表します
shut_queues 配列 顧客リスト

shut_queues要素のデータ構造

属性名 型 説明
customer_id 整数型 id
customer_name 文字列 ユーザー表示名
channel 文字列 チャネル, web wechat ios android weibo api mchat
queue_start_time 文字列 待機開始時間
queue_seconds 文字列 待機時間
queue_name 文字列 待機キュー名
current_page 整数型 現在のページ数
total_pages 整数型 総ページ数
count 整数型 当ページの総件数

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/im/im_queues?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&start_time=2019-02-10&end_time=2019-02-15

レスポンス

{
    "code": 1000,
    "shut_queues": [
        {
            "id": 123,
            "customer_id": 1234,
            "channel": "web",
            "queue_start_time": "2022-03-25T15:55:20.000+08:00",
            "queue_seconds": 27,
            "queue_name": "xxx",
            "customer_name": {
                "id": 12345,
                "email": "123.123.123.123@temp.com",
                "signature": null,
                "notify": null,
                "weibo_name": null,
                "weixin_openid": null,
                "nick_name": "xxx",
                "weibo_id": null,
                "company_id": 1,
                "created_at": "2022-03-25T15:55:03.000+08:00",
                "updated_at": "2022-03-25T15:55:04.000+08:00",
                "organization": null,
                "cellphone": null,
                "telephone": null,
                "weixin_id": null,
                "authentication_token": null,
                "description": "IMユーザー:ip(123.123.123.123)",
                "qq": null,
                "platform_id": 4,
                "ticket_show_filters": {
                    "show_user": "true",
                    "show_assignee": "true",
                    "show_created_at": "true",
                    "show_priority": "true",
                    "show_status": "true",
                    "show_platform": "true"
                },
                "wechat_status": "offline",
                "custom_fields": {
                    "SelectField_3999": [
                        "0"
                    ]
                },
                "leave_msg_expire_at": null,
                "customer_import_record_id": null,
                "web_token": "1f85c1b8-61b9-44f3-3468-9f5w164d099f",
                "sdk_token": null,
                "is_anonym": false,
                "owner_id": null,
                "ip": "123.123.123.123",
                "from": "xxxxx",
                "weibo_status": null,
                "weibo_leave_msg_expire_at": null,
                "deleted": false,
                "weixin_api_status": null,
                "weixin_appid": null,
                "weixin_appsecret": null,
                "owner_group_id": null,
                "source_channel": "web_im",
                "weixin_channel_id": null,
                "province": "xx",
                "city": "xx",
                "phone_service_provider": null,
                "isp": "xxx",
                "last_contact_at": null,
                "first_contact_at": null,
                "contact_count": null,
                "last_contact_at_via_phone": null,
                "first_contact_at_via_phone": null,
                "contact_count_via_phone": null,
                "last_contact_at_via_im": null,
                "first_contact_at_via_im": null,
                "contact_count_via_im": null,
                "latest_device_info": {
                    "os": "Win7",
                    "browser": "Chrome99",
                    "resolution": "1920*1080"
                },
                "organization_id": null,
                "is_blocked": false,
                "generated_channel": null,
                "weibo_channel_id": null,
                "level": "normal",
                "open_api_token": null,
                "current_ticket_id": null,
                "mchat_openid": null
            },
            "im_web_plugin_id": 16,
            "menu_names": "xxx"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "count": 1
    }
}

IM構造化メッセージの送信

このインターフェースは、IMを通じて顧客に構造化メッセージを送信するために使用されます。 頻度制限：1回/2秒

認証

署名方法については、認証方法を参照してください。ただし、以下の2点に注意する必要があります：

リクエスト方法

POST /im/sessions/struct_messages

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

パラメータ名 必須 説明
im_sub_session_id はい セッションID
customer_id はい 顧客ID
agent_id はい サポート担当者ID
timestamp はい タイムスタンプ

注：APIで作成された顧客はこのインターフェースでは使用できません

リクエストパラメータ（Request Body）

パラメータ名 必須 タイプ 説明
jid_resource いいえ 文字列 SDKチャネルソース
data はい オブジェクト 構造化メッセージ

data

パラメータ名 必須 タイプ 説明
title はい 文字列 タイトル
description はい 文字列 説明文
img_url はい 文字列 表示画像のリンク
buttons はい 配列 ボタンリスト

buttons 要素の構造

パラメータ名 必須 タイプ 説明
type はい 文字列 ボタンタイプ
text はい 文字列 ボタンタイトル
value はい 文字列 ボタン値
callback_name いいえ 文字列 コールバック名（typeがsdk_callbackの場合のみ有効）

type の取り得る値

値 意味
link リンクボタン
phone 電話ボタン
sdk_callback コールバックボタン（SDKのみサポート）
### レスポンスデータ
属性名 タイプ 説明
status 整数 実行結果コード、1000 は成功を表します
message 文字列 実行結果の説明

例

curl https://demo.udesk.cn/open_api_v1/im/sessions/struct_messages?im_sub_session_id=1&customer_id=1&agent_id=1&timestamp=1494814031&sign=129da7df812jdfsa9912jfdadf81 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "data": {
        "title": "APIによる構造化メッセージ送信テスト",
        "description": "このメッセージはAPIから送信されました",
        "img_url": "https://www.udesk.cn/images/index/banner01.jpg",
        "buttons": [
            {
                "type": "link",
                "text": "アクセス",
                "value": "https://www.udesk.cn"
            },
            {
                "type": "phone",
                "text": "電話をかける",
                "value": "010-12345678"
            },
            {
                "type": "sdk_callback",
                "callback_name": "sdk_callback",
                "text": "コールバックボタン",
                "value": "v1"
            }
        ]
    }
}'

レスポンス

{
  "status": 1000,
  "message": "送信成功"
}

H5オフラインプッシュ

顧客が自社アプリに当社のH5 IMページを埋め込んでいる場合、顧客が他のページに切り替えたりアプリを終了したりする際に、オフラインメッセージを顧客にプッシュする必要があります

このインターフェースは、IMを通じて顧客に構造化メッセージを送信するために使用されます。 H5 URLが有効化され設定されている場合のみ有効です。H5_PUSH_URLは顧客がカスタマイズするものであり、公衆インターネットからアクセス可能である必要があります。

リクエストメソッド

POST {H5_PUSH_URL}

リクエストパラメータ（Request Body）

パラメータ名 必須 説明
web_token はい 顧客の一意識別子
customer_token はい 顧客の一意識別子
session_key いいえ セッション識別子、顧客の一意識別子+セッション識別子で一意の顧客を表します
messages はい メッセージボディ、配列構造
message はい メッセージ
#### messages 各要素の構造
パラメータ名 必須 タイプ 説明
message_created_at はい 文字列 メッセージ送信時間
agent_avatar いいえ 文字列 カスタマーサポートのアバター、通常は画像のリンク
im_web_plugin_id はい 文字列 ウェブプラグインID
agent_id はい 文字列 カスタマーサポートID
agent_name はい 文字列 カスタマーサポート名
sender はい 文字列 メッセージ送信者 agent:カスタマーサポート customer:顧客 system:システム
message_id はい 文字列 メッセージの一意識別子
im_sub_session_id はい 文字列 セッションID、セッションの一意のマーク
type はい 文字列 メッセージタイプ create:セッション作成 close:セッション終了 off_push:オフラインメッセージ
data はい object メッセージデータ

data

パラメータ名 必須 タイプ 説明
content はい 文字列 メッセージ内容
msg_close いいえ boolean メッセージが閉じられているかどうか

message

パラメータ名 必須 タイプ 説明
message_created_at はい 文字列 メッセージ送信時間
agent_avatar いいえ 文字列 カスタマーサポートのアバター、通常は画像のリンク
im_web_plugin_id はい 文字列 ウェブプラグインID
agent_id はい 文字列 カスタマーサポートID
agent_name はい 文字列 カスタマーサポート名
sender はい 文字列 メッセージ送信者 agent:カスタマーサポート customer:顧客 system:システム
message_id はい 文字列 メッセージの一意識別子
im_sub_session_id はい 文字列 セッションID、セッションの一意のマーク
type はい 文字列 メッセージタイプ create:セッション作成 close:セッション終了 off_push:オフラインメッセージ
content はい object メッセージの内容、リッチテキストなどの情報を含む
#### コンテンツ
パラメータ名 必須 タイプ 説明
type いいえ 文字列 メッセージタイプ、message（テキストメッセージ）、image、video、fileなど
font いいえ 文字列 フォント
platform いいえ 文字列 プラットフォーム、web、wechat、weixin、weixin_mini、qywx、facebook、line、what_app、tiktok、rpa、feishuなど、今後順次追加予定
version number 文字列 バージョン番号
seq_num いいえ 文字列 シーケンス番号
auto いいえ boolean true、false、自動送信メッセージかどうか
data はい object メッセージデータ

返却データ、H5_PUSH_URL 提供者に依存し、Udeskは制限しません

属性名 タイプ 説明

例

curl {H5_PUSH_URL} \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "web_token": "6acbf1ea60ee2635b30eae579b5a7bed",
    "customer_token": "6acbf1ea60ee2635b30eae579b5a7bed",
    "messages": [
        {
            "message_created_at": "2023-11-28 19:46:21",
            "im_web_plugin_id": 119681,
            "agent_id": 1601824,
            "agent_name": "兜小炜",
            "data": {
                "content": "愿平安顺遂！期待下次与您相遇~",
                "msg_close": true
            },
            "sender": "system",
            "message_id": "udesk_12551701171980650",
            "im_sub_session_id": 4594173144,
            "type": "off_push"
        }
    ],
    "message": {
        "message_created_at": "2023-11-28 19:46:21",
        "im_web_plugin_id": 119681,
        "agent_id": 1601824,
        "agent_name": "兜小炜",
        "sender": "system",
        "message_id": "udesk_12551701171980650",
        "im_sub_session_id": 4523173134,
        "type": "off_push",
        "content": {
            "type": "message",
            "font": "",
            "data": {
                "content": "愿平安顺遂！期待下次与您相遇~",
                "msg_close": true
            },
            "platform": "web",
            "version": 1,
            "seq_num": "",
            "auto": true
        }
    }
}'

返却

{
  "xxx": "xxx"
}

カスタム IM 構造化メッセージリストページ

カスタム IM 構造化メッセージリストページは、️ お客様が提供する HTML ページであり、よく使用される構造化メッセージを含んでいます。これにより、カスタマーサポート担当者は Udesk IM コンソールで素早く選択し、顧客に送信することができます。

カスタム IM 構造化メッセージリストページを使用するには、以下の2つの手順が必要です：

  1. まず、HTML ページを作成し、そのページのパブリックネットワークアドレスを提供する必要があります。
  2. Udesk 【管理センター】-【構造化メッセージ】で「埋め込みリンク」を設定します。

HTML ページの作成

Udesk は、カスタマーサポート担当者が構造化メッセージを選択する必要があるときに、お客様が提供した HTML ページを iframe 方式で表示し、以下のパラメータを Query String として HTML ページに渡します：

パラメータ名 説明
im_sub_session_id セッション ID
customer_id 顧客 ID
agent_id カスタマーサポート担当者 ID
jid_resource SDK ソース
timestamp タイムスタンプ

さらに、認証方法に従って計算された署名も、sign パラメータとして一緒に渡されます。

署名を計算する際は、認証方法とは少し異なり、IM 構造化メッセージ送信インターフェースと一致します。 リクエストを受信した後、HTML ページを返すかどうかを決定する前に、sign 値が有効かどうかを検証することをお勧めします。

同時に、HTML ページ内では、上記のパラメータを使用してIM 構造化メッセージ送信インターフェースを呼び出し、構造化メッセージの送信を完了することができます。

設定

  1. 管理者として Udesk システムにログインします。
  2. 【管理センター】-【チャネル管理】-【インスタントメッセージング】-【構造化メッセージ】を開きます。
  3. 「埋め込みリンク」を、お客様が提供する HTML ページのパブリックネットワークアドレスに設定します。

例

【管理センター】での設定が以下のようになっていると仮定します：

カスタマーサポート担当者が IM ワークベンチのチャットインターフェースで「構造化メッセージ」リストアイコンをクリックすると、Udesk は以下のようなアドレスを含む iframe ページを表示します：

https://www.demo.com/struct_message?im_sub_session_id=1&customer_id=1&agent_id=1&jid_resource=12dsafdaslj129das-12fds912-12dsa&timestamp=1484272693&sign=4666293b3dfe91aa97179dc701be7afc

注意：この中の sign の計算方法は以下の通りです：

md5("im_sub_session_id=1&customer_id=1&agent_id=1&timestamp=1484272693&708ff6dc-41d5-4med-9ebc-0388zz9d76f1")
#=> 4666293b3dfe91aa97179dc701be7afc

FAQ

このAPIインターフェースを使用したいのですが、どのような条件が必要ですか？

このAPIインターフェースは高度なインターフェースであり、開発作業が多く、要求が高いです。以下の条件を満たす必要があります：

指定サーバーアドレスへのプッシュリクエストの形式は何ですか？

POSTリクエスト、JSON形式です。

セッションをリクエストした後、「顧客が存在しません」と返ってくるのはなぜですか？

セッションをリクエストする前に、顧客を作成するリクエストが必要です。詳細は以下をご覧ください。

当社のサーバーがサポート担当からの返信メッセージを受信できません。Udeskがプッシュしているかどうかを確認するにはどうすればよいですか？

以下のことをお勧めします。

返信メッセージが複数返ってくることがあるのはなぜですか？