チケット内の一部フィールドの値の意味説明
status_id の取り得る値は、チケットステータス取得インターフェースを通じてサブステータスの値、中国語名、英語名を取得できます
| 値 | 中国語名 | 英語名 |
|---|---|---|
| 1 | オープン | open |
| 2 | 解決済み | resolved |
| 3 | クローズ済み | closed |
| 4 | 解決中 | solving |
priority_id の取り得る値
| 値 | 中国語名 | 英語名 |
|---|---|---|
| 1 | 緊急 | urgency |
| 2 | 高 | high |
| 3 | 標準 | medium |
| 4 | 低 | low |
platform_name の取り得る値
| 値 | 意味 |
|---|---|
| メール | |
| 微博 | |
| 微信 | |
| im | インスタントメッセージ |
| call | 電話 |
| feedback | フィードバックタグ |
| hc | ヘルプセンター |
| manual_input | 手動入力 |
| api | API |
戻り値におけるページネーションに関する説明
- 戻り値にページネーション関連の内容がある場合、オブジェクト
metaで表します。構造は以下の通りです。
metaのデータ構造
| 属性 | 型 | 説明 |
|---|---|---|
| current_page | 整数型 | 現在のページ |
| total_pages | 整数型 | 総ページ数 |
| total_count | 整数型 | データレコード総数 |
チケット作成
このインターフェースはチケットを作成するために使用します。
リクエストメソッド
POST /tickets
リクエストパラメータ（Request Body）
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| ticket | オブジェクト | はい | チケット情報、詳細は以下を参照 |
ticket の構造
| パラメータ名 | 型 | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| subject | 文字列 | はい | タイトル | 最大長255文字 |
| content | 文字列 | はい | 内容 | |
| type | 文字列 | いいえ | 顧客検索時に使用するタイプ | |
| type_content | 文字列 | いいえ | タイプ type に対応する値 |
最大長255文字 |
| priority | 文字列 | いいえ | 優先度の中国語名、デフォルトは標準 | |
| assignee_email | 文字列 | いいえ | 担当カスタマーサポートのメールアドレス | 最大長255文字 |
| agent_group_name | 文字列 | いいえ | 担当カスタマーサポートグループ名 | 最大長255文字 |
| template_id | 整数型 | いいえ | チケットテンプレートID、値が渡されないか誤った値が渡された場合はデフォルトテンプレートを使用 | |
| follower_ids | 配列 | いいえ | チケットフォロワー、例：[1,2,3]、配列内はカスタマーサポートID | |
| tags | 文字列 | いいえ | チケットタグ、例："タグ1,タグ2"、文字列内はタグ名、カンマ区切り | |
| status_id | 整数型 | いいえ | ステータスID | |
| ticket_field | オブジェクト | いいえ | カスタムフィールド、詳細は以下を参照 | |
| creator_email | 文字列 | いいえ | チケット作成者のメールアドレス | 最大長255文字 |
ticket_field
- ticket_fieldの属性はカスタムフィールドの識別名です。
- 選択タイプの値はオプションのインデックス値を使用し、複数選択時はカンマで連結した文字列とします。
- テキストタイプのカスタムフィールドの値は、特定のフォーマットの文字列です。
- カスタマーサポートシステム内の「新規フィールド追加 - フィールドタイプ選択」のタイプ説明を参照してください。
説明：
- チケット作成時、typeまたはtype_contentが空でない場合、typeとtype_contentに基づいて顧客を検索します。顧客が見つからない場合はエラーメッセージを返します。顧客作成APIを呼び出して顧客を作成できます。
- チケット作成時、typeとtype_contentが両方とも空の場合、typeとtype_contentに基づいて顧客を検索しません。この場合、新規作成されるチケットの顧客情報は空になります。
- typeの値には4種類あります：email（顧客メールアドレス）、cellphone（顧客電話番号）、customer_token（顧客外部一意識別子）、customer_id（顧客ID）。1回の呼び出しで、typeの値はこれらのうちの1つだけです。
- type_contentの値はtypeに対応する必要があります。typeがemailの場合、type_contentはemailの値です。
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
| ticket_id | 整数型 | 新規作成されたチケットのID |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets?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 '
{
"ticket": {
"subject":"テストチケット1",
"content":"チケットテスト",
"follower_ids":["1","23","12"],
"template_id":3,
"tags":"タグ2,タグ1",
"type":"customer_id",
"type_content":"2",
"priority":"標準",
"status_id":1,
"agent_group_name":"デフォルトグループ",
"assignee_email":"agent@sample.com",
"ticket_field":{
"TextField_1": "通常テキスト内容",
"TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "私の地理位置情報",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
}'
レスポンス
{
"code":1000,
"message":"チケット作成に成功しました",
"ticket_id":2
}
チケットの一括作成
このインターフェースはチケットを一括作成するために使用されます。
リクエストメソッド
POST /tickets/batch_create
リクエストパラメータ（Request Body）
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| items | 配列 | はい | チケット情報の集合 |
| ticket | オブジェクト | はい | チケット情報、詳細は以下を参照 |
ticket の構造
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| subject | 文字列 | はい | タイトル | 最大長255文字 |
| content | 文字列 | はい | 内容 | |
| unique_id | 文字列 | いいえ | データ識別子 | このフィールドはデータに保存されず、コールバックインターフェースでのみ返され、リクエスト内の対応するデータを識別します |
| type | 文字列 | いいえ | 顧客検索時に使用するタイプ | |
| type_content | 文字列 | いいえ | タイプtypeに対応する値 | 最大長255文字 |
| priority | 文字列 | いいえ | 優先度の日本語名称、デフォルトは「標準」 | |
| assignee_email | 文字列 | いいえ | 担当カスタマーサポートのメールアドレス | 最大長255文字 |
| agent_group_name | 文字列 | いいえ | 担当カスタマーサポートグループ名 | 最大長255文字 |
| template_id | 整数 | いいえ | チケットテンプレートID、値が渡されないか誤った値が渡された場合はデフォルトテンプレートを使用 | |
| follower_ids | 配列 | いいえ | チケットのフォロワー、例：[1,2,3]、配列内はカスタマーサポートID | |
| tags | 文字列 | いいえ | チケットタグ、例："タグ1,タグ2"、文字列内はタグ名、カンマ区切り | |
| status_id | 整数 | いいえ | ステータスID | |
| ticket_field | オブジェクト | いいえ | カスタムフィールド、詳細は以下を参照 | |
| creator_email | 文字列 | いいえ | チケット作成者のメールアドレス | 最大長255文字 |
| organization | 文字列 | いいえ | 会社名 | |
| organization_id | 文字列 | いいえ | 会社ID | 会社IDに値がある場合は、IDを優先します |
ticketパラメータ構造の説明はチケット作成インターフェースと同じです
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/batch_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 '
{
"items": [
{
"ticket": {
"unique_id": "データ識別子1",
"subject": "テストチケット1",
"content": "チケットテスト",
"follower_ids": [
"1",
"23",
"12"
],
"template_id": 3,
"tags": "タグ2,タグ1",
"type": "customer_id",
"type_content": "2",
"priority": "標準",
"status_id": 1,
"agent_group_name": "デフォルトグループ",
"assignee_email": "agent@sample.com",
"ticket_field": {
"TextField_1": "通常テキスト内容",
"TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "私の地理的位置",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
},
{
"ticket": {
"unique_id": "データ識別子2",
"subject": "テストチケット2",
"content": "チケットテスト2",
"follower_ids": [
"1",
"23",
"12"
],
"template_id": 3,
"tags": "タグ2,タグ1",
"type": "customer_id",
"type_content": "2",
"priority": "標準",
"status_id": 1,
"agent_group_name": "デフォルトグループ",
"assignee_email": "agent@sample.com",
"ticket_field": {
"TextField_1": "通常テキスト内容2",
"TextField_2": "複数行テキスト内容2\r\n複数行テキスト内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"TextField_9": "私の地理的位置",
"SelectField_1": "0",
"SelectField_2": "0",
"SelectField_3": "0,3"
}
}
}
]
}
'
レスポンス
{
"code":1000,
"message":"チケットの作成に成功しました"
}
チケット詳細の取得
このAPIは、指定されたチケットの詳細情報を取得するために使用されます。
リクエストメソッド
get /tickets/detail
リクエストパラメータ（Request String）
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| id | 整数 | いいえ | チケットID |
| num | 文字列 | いいえ | チケット番号 (例: num='#848') |
- 注意:
idとnumは同時に渡すことはできませんが、いずれか一方は必ず渡す必要があります。numの値#848は、URLエンコードして%23848にする必要があります。
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード。1000は成功を表します。 |
| message | 文字列 | 実行結果の説明。 |
| ticket | オブジェクト | チケット情報。構造は以下を参照してください。 |
チケットのデータ構造
| 属性 | タイプ | 編集可能 | 説明 |
|---|---|---|---|
| id | 整数 | いいえ | 一意識別子。システムにより自動生成されます。 |
| field_num | 文字列 | いいえ | 一意識別子。システムにより自動生成されます。 |
| subject | 文字列 | はい | タイトル |
| content | 文字列 | はい | 内容 |
| content_type | 文字列 | はい | コンテンツタイプ |
| user_id | 整数 | はい | 顧客ID |
| user_name | 文字列 | いいえ | 顧客名 |
| user_email | 文字列 | いいえ | 顧客メールアドレス |
| user_cellphone | 文字列 | いいえ | 顧客電話番号 |
| organization_id | 整数 | いいえ | 顧客所属会社ID |
| assignee_id | 整数 | はい | 担当カスタマーサポートエージェントID |
| assignee_name | 文字列 | いいえ | 担当カスタマーサポートエージェント名 |
| assignee_avatar | 文字列 | いいえ | 担当カスタマーサポートエージェントのアバター |
| user_group_id | 整数 | はい | 担当カスタマーサポートグループID |
| user_group_name | 文字列 | いいえ | 担当カスタマーサポートグループ名 |
| template_id | 整数 | いいえ | テンプレートID |
| priority | 文字列 | はい | 優先度 (日本語名) |
| status | 文字列 | はい | ステータス (日本語名) |
| status_en | 文字列 | はい | ステータス (英語名) |
| platform | 文字列 | いいえ | チャネル (日本語名) |
| satisfaction | 文字列 | いいえ | 満足度調査結果 |
| custom_fields | オブジェクト | はい | カスタムフィールド。詳細は例を参照してください (注意: ファイルタイプのフィールドは返却形式が異なります。例: TextField_41) |
| tags | 文字列 | はい | タグ |
| followers | 配列 | いいえ | フォロワー。id (フォロワーID)、nick_name (フォロワー名) を含みます。 |
| creator_id | 整数 | いいえ | 作成者ID |
| created_at | 日時 | いいえ | 作成日時。システムにより自動生成されます。 |
| updated_at | 日時 | いいえ | 更新日時。システムにより自動生成されます。 |
| solving_at | 日時 | いいえ | 解決開始日時 |
| resolved_at | 日時 | いいえ | 解決日時 |
| closed_at | 日時 | いいえ | クローズ日時 |
| solved_deadline | 日時 | いいえ | 期限日時 |
| replied_at | 日時 | いいえ | 最終返信日時 |
| first_replied_at | 日時 | いいえ | カスタマーサポートによる初回返信日時 |
| agent_replied_at | 日時 | いいえ | カスタマーサポートによる最終返信日時 |
| customer_replied_at | 日時 | いいえ | 顧客による最終返信日時 |
| replied_by | 文字列 | いいえ | 最終返信者 |
| attachments | 配列 | いいえ | チケットに関連付けられた添付ファイル。file_name (ファイル名)、url (ファイルURL) を含みます。 |
| im_sub_session_id | 整数 | いいえ | チケットのセッションID |
| associated_tickets | 配列 | いいえ | 関連チケットデータ。チケットID、チケット番号、関連タイプ名を含みます。詳細取得時のみ返却されます。 |
サンプル
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/detail?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&id=1
レスポンス
{
"code": 1000,
"message": "success",
"ticket": {
"id": 1,
"field_num": "#1",
"subject": "こんにちは！",
"content": "<p>あの時代の法サタン分</p>",
"content_type": "html",
"user_id": 47,
"user_name": "13000020520",
"user_email": "1234567890@qq.com",
"user_cellphone": "13000020520",
"organization_id": null,
"assignee_id": 12,
"assignee_name": "xxx",
"assignee_avatar": "https://xxxxxxxxxxxxxxxxx/Fk_5aUhOY0U90dHQU6V34N9WuqX9",
"user_group_id": 1,
"user_group_name": "デフォルトグループ",
"template_id": 1,
"priority": "標準",
"status": "オープン",
"status_en": "open",
"platform": "手動入力",
"im_sub_session_id": 1257,
"satisfaction": null,
"custom_fields": {
"TextField_3": "rytffgfgfddddsssｄ長調",
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_38": "私の新しい場所",
"TextField_40": "テキスト",
"TextField_41": [
{
"id": 9334,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
},
{
"id": 9336,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
}
]
},
"tags": "タグ１,タグ２",
"followers": [
{
"id": 2,
"nick_name": "Tom"
},
{
"id": 3,
"nick_name": "Jerry"
},
{
"id": 12,
"nick_name": "Lucy"
}
],
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-08T20:47:49.000+08:00",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-16T20:41:03.000+08:00",
"agent_replied_at": "2017-08-16T20:41:03.000+08:00",
"customer_replied_at": "2017-08-08T20:47:42.000+08:00",
"replied_by": "xxx",
"associated_tickets": [
{
"id": 2,
"field_num": "#002",
"associated_type": "重複チケット"
},
{
"id": 3,
"field_num": "#003",
"associated_type": "子チケット"
}
]
}
}
チケットステータスの取得
このインターフェースは、すべてのチケットステータスを取得するために使用されます。
リクエストメソッド
get /tickets/status
リクエストパラメータ（Request String）
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| enable | boolean | 否 | 有効かどうか。指定しない場合はすべてを検索します。 |
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード。1000は成功を表します。 |
| message | 文字列 | 実行結果の説明 |
| status | オブジェクト | ステータス情報。構造は以下を参照してください。 |
ステータスのデータ構造
| 属性 | タイプ | 編集可能 | 説明 |
|---|---|---|---|
| status_id | 整数 | 不可 | ステータスのID値。システムにより自動生成されます。 |
| name | 文字列 | 可 | ステータスの日本語名。主ステータスが「対応中」のステータスのみ変更可能です。 |
| en_name | 文字列 | 不可 | ステータスの英語名。システムにより自動生成されます。 |
| enable | ブール値 | 可 | 有効かどうか |
| color | 文字列 | 可 | ステータスの色 |
サンプル
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/status?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス
{
"code": 1000,
"message": "success",
"status": [
{
"status_id": 1,
"name": "オープン",
"en_name": "open",
"enable": true,
"color": "#f30000"
},
{
"status_id": 2,
"name": "解決済み",
"en_name": "resolved",
"enable": true,
"color": "#00b38a"
},
{
"status_id": 3,
"name": "クローズ済み",
"en_name": "closed",
"enable": true,
"color": "#858585"
},
{
"status_id": 4,
"name": "解決中",
"en_name": "solving",
"enable": true,
"color": "#7ed321"
},
{
"status_id": 17,
"name": "解決中2",
"en_name": "solving_17",
"enable": false,
"color": "#8b572a"
}
]
}
チケット更新
このインターフェースはチケット情報の変更に使用されます。
リクエストメソッド
PUT /tickets/:id
リクエストパラメータ（URL）
| パラメータ名 | 必須 | 説明 |
|---|---|---|
| id | はい | チケットID |
リクエストパラメータ（Request Body）
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| ticket | オブジェクト | はい | チケット情報 |
| customer_id_type | 文字列 | いいえ | 顧客識別子タイプ |
| customer_id_value | 文字列 | いいえ | 顧客識別子の値 |
- 注意：customer_id_type/customer_id_value は、両方とも空であるか、または両方とも値を持つ必要があります。
- 注意：これらのパラメータを渡す場合、チケット更新時に、検索された顧客をチケットに関連付けることを意味します。情報に基づいて顧客が見つからない場合は、エラーが通知されます。
ticket のデータ構造
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| subject | 文字列 | はい | タイトル | 最大長255文字 |
| content | 文字列 | いいえ | 説明 | |
| agent_id | 整数 | いいえ | 担当カスタマーサポートID | |
| agent_group_id | 整数 | いいえ | 担当カスタマーサポートグループID | |
| template_id | 整数 | いいえ | テンプレートID、デフォルトはデフォルトテンプレート | |
| status_id | 整数 | いいえ | ステータスID | |
| priority_id | 整数 | いいえ | 優先度ID | |
| follower_ids | 配列 | いいえ | フォロワーID配列、各要素はカスタマーサポートID | |
| custom_fields | オブジェクト | いいえ | カスタムフィールド | |
| tags | 文字列 | いいえ | タグ、複数のタグはカンマ区切り |
- 注意：agent_id（カスタマーサポート）とagent_group_id（カスタマーサポートグループ）パラメータには対応関係があり、これらのパラメータを変更した後、カスタマーサポートとカスタマーサポートグループが一致しない場合はエラーが発生します。
custom_fields のデータ構造
- custom_fields の属性はカスタムフィールド識別名です。
- 選択タイプのカスタムフィールドの場合、その値はオプションインデックスの配列です。
- テキストタイプのカスタムフィールドの場合、その値は特定の形式の文字列です。
- ファイルタイプのカスタムフィールドの場合、ファイルを削除します。削除方法は以下の通りです：
- チケット詳細インターフェースから取得したファイルフィールドの内容は以下の通りです：
"TextField_216103": [
{
"id": 9345,
"url": "https://pro-upload-center.kefutoutiao.com/202306251425_1_27d4e5b0_aaaa.xlsx",
"name": "202306251425_1_27d4e5b0_aaaa.xlsx",
"size": 4321047,
"content_type": "image" // ファイルフィールドでファイルをアップロードする際にtypeパラメータを渡した場合のみこの値があります
},
{
"id": 9346,
"url": "https://pro-upload-center.kefutoutiao.com/202306251428_1_5293d8dd_aaaa.xlsx",
"name": "202306251428_1_5293d8dd_aaaa.xlsx",
"size": 4321047
},
{
"id": 9347,
"url": "https://pro-upload-center.kefutoutiao.com/202306251429_1_5293d8dd_aaaa.xlsx",
"name": "202306251429_1_5293d8dd_aaaa.xlsx",
"size": 4321047
}
]
- IDが9345の添付ファイルを削除する場合、チケット更新インターフェースに渡す情報は以下の通りです：
{
"ticket": {
"custom_fields":{
"TextField_216103": "9346,9347" // 最終的な添付ファイルIDを , で連結します
}
}
}
または
{
"ticket": {
"custom_fields": [
{
"id": 9346,
"url": "https://pro-upload-center.kefutoutiao.com/202306251428_1_5293d8dd_aaaa.xlsx",
"name": "202306251428_1_5293d8dd_aaaa.xlsx",
"size": 4321047
},
{
"id": 9347,
"url": "https://pro-upload-center.kefutoutiao.com/202306251429_1_5293d8dd_aaaa.xlsx",
"name": "202306251429_1_5293d8dd_aaaa.xlsx",
"size": 4321047
}
]
}
}
例は以下の通りです：
{
"custom_fields": {
"TextField_1": "通常テキスト内容", // 通常テキスト
"TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2", // 複数行テキスト
"TextField_3": "2016-08-11", // 日付
"TextField_4": "14:44:36", // 時間
"TextField_5": "2017-05-03 14:44", // 日時
"TextField_6": "https://www.sample.com", // リンク
"TextField_7": "13", // 正の整数
"TextField_8": "13.33", // 数値
"SelectField_1": ["0"], // ドロップダウンリスト、ドロップダウンオプション1
"SelectField_2": ["0"], // ラジオボタン、ラジオボタンオプション1
"SelectField_3": ["0","3"] // チェックボックス、チェックボックスオプション1、チェックボックスオプション4
}
}
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| ticket | オブジェクト | チケット情報 |
ticket のデータ構造
| 属性名 | タイプ | 説明 |
|---|---|---|
| id | 整数型 | チケットID |
| field_num | 文字列 | チケット番号 |
| subject | 文字列 | タイトル |
| content | 文字列 | 内容 |
| customer_id | 整数型 | 顧客ID |
| customer_name | 文字列 | 顧客名 |
| agent_id | 整数型 | 担当カスタマーサポートID |
| agent_name | 文字列 | カスタマーサポート名 |
| agent_avatar | 文字列 | カスタマーサポートのアバターリンク |
| agent_group_id | 整数型 | 担当カスタマーサポートグループID |
| agent_group_name | 文字列 | 担当カスタマーサポートグループ名 |
| template_id | 整数型 | テンプレートID |
| priority | 文字列 | 優先度（日本語名） |
| status | 文字列 | ステータス（日本語名） |
| status_en | 文字列 | ステータス（英語名） |
| platform_name | 文字列 | チャネル（英語名） |
| satisfaction | 整数型 | 満足度調査結果 |
| created_at | 日時 | 作成時間 |
| custom_fields | オブジェクト | カスタムフィールド |
| organization_id | 整数型 | 顧客所属会社ID |
| tags | 配列 | タグ |
| followers | 配列 | フォロワー、id（フォロワーID）、 nick_name（フォロワー名）、avatar（別名）を含む |
| solved_deadline | 日時 | 期限時間 |
| attachments | 配列 | チケットに関連付けられた添付ファイル、file_name（ファイル名）、url（ファイルURL）を含む |
| im_sub_session_id | 整数型 | チケットのsub_session_id |
例
curl https://demo.udesk.cn/open_api_v1/tickets/1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
"ticket": {
"subject": "テストチケット",
"content": "このチケットはテストのみに使用されます",
"agent_id": 1,
"agent_group_id": 1,
"template_id": 1,
"status_id": 1,
"priority_id": 1,
"follower_ids": [
{
"id": 1,
"nick_name": "カスタマーサポート1",
"avatar": "青空"
},
{
"id": 2,
"nick_name": "カスタマーサポート2",
"avatar": null
}
],
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"custom_fields": {
"TextField_1": "通常テキスト内容",
"TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"SelectField_1": ["0"],
"SelectField_2": ["0"],
"SelectField_3": ["0","3"]
},
"tags": "タグ1,タグ2,タグ3"
},
"customer_id_type": "customer_id",
"customer_id_value": "1"
}'
返却
{
"code": 1000,
"ticket": {
"id": 1,
"field_num": "#1",
"customer_id": 1,
"customer_name": "テストユーザー",
"agent_id": 1,
"agent_name": "テストカスタマーサポート1",
"agent_avatar": "https://xxx.xxx.xxx/xxxxx1.jpg",
"agent_group_id": 1,
"agent_group_name": "テストカスタマーサポートグループ1",
"template_id": 1,
"priority": "緊急",
"status": "オープン",
"status_id": 1,
"status_en": "open",
"platform_name": "api",
"im_sub_session_id": 12,
"subject": "テストチケット",
"satisfaction": null,
"content": "このチケットはテストのみに使用されます",
"created_at": "2015-01-02T15:04:05.000+08:00",
"custom_fields": {
"TextField_1": "通常テキスト内容",
"TextField_2": "複数行テキスト内容1\r\n複数行テキスト内容2",
"TextField_3": "2016-08-11",
"TextField_4": "14:44:36",
"TextField_5": "2017-05-03 14:44",
"TextField_6": "https://www.sample.com",
"TextField_7": "13",
"TextField_8": "13.33",
"SelectField_1": ["0"],
"SelectField_2": ["0"],
"SelectField_3": ["0","3"]
},
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"tags": [
{"id": 1, "name": "タグ1"},
{"id": 2, "name": "タグ2"},
{"id": 3, "name": "タグ3"}
],
"followers": [
{"id": 1, "nick_name": "テストカスタマーサポート1", "avatar": "https://xxx.xxx.xxx/xxxxx1.jpg"},
{"id": 2, "nick_name": "テストカスタマーサポート2", "avatar": "https://xxx.xxx.xxx/xxxxx2.jpg"}
],
"solved_deadline": null
}
}
チケット削除
このインターフェースは、指定されたチケットを削除するために使用されます。
リクエストメソッド
delete /tickets/destroy_ticket
リクエストパラメータ（Query String）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| id | いいえ | 整数 | チケットID |
| num | いいえ | 文字列 | チケット番号, 例: num='#123' |
- 注意：
- idとnumのどちらか一方を必ず指定する必要があり、値は空であってはなりませんが、両方を同時に指定することはできません。
- numの値 #848 は、URLエンコードして %23848 にする必要があります。
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード, 1000は成功を表します |
| message | 文字列 | 結果の説明 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/destroy_ticket?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&num=%23848 -X DELETE
レスポンス
{
"code": 1000,
"message": "success"
}
チケットリストの取得
このインターフェースは、複数のチケット情報を取得するために使用されます。
リクエストメソッド
get /tickets
リクエストパラメータ（Query String）
| パラメータ名 | 必須 | タイプ | 説明 |
|---|---|---|---|
| sign | はい | 認証署名。特に明記されていない限り、すべてのAPI呼び出しに必要です。計算方法は認証方法を参照してください。 | |
| nonce | はい | リクエストの一意の識別子。呼び出し元が提供する任意の文字列で、この文字列は15分以内に1回しか使用できません。詳細 | |
| sign_version | はい | 署名アルゴリズムのバージョン。値は固定で v2 です。詳細 | |
| はい | スーパー管理者のメールアドレス | ||
| type | いいえ | 特定の顧客のチケットリストを取得する場合は必須です。値の詳細 | |
| content | いいえ | 特定の顧客のチケットリストを取得する場合は必須です。値の詳細 | |
| page | いいえ | 整数 | ページ番号。デフォルト値は1です。 |
| per_page | いいえ | 整数 | 1ページあたりのレコード数。デフォルト値は20、最大値は100です。 |
返却データ
| 属性名 | 型 | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表す |
| message | 文字列 | 実行結果説明 |
| total_pages | 整数 | 総ページ数 |
| contents | 配列 | チケットリスト、各要素の内容はチケット詳細インターフェースのチケットデータ構造を参照 |
| meta | オブジェクト | ページネーション関連の内容 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス
{
"code": 1000,
"message": "success",
"contents": [
{
"ticket": {
"id": 1,
"field_num": "#638",
"subject": "聚美優品は正規品ですか？",
"content": "はい！当社は販売するすべての商品が100%正規品であることを保証します。聚美優品は、中国で現在リーディングであり、ユーザー数が最も多い化粧品ショッピングサイトとして、毎月数百万件の注文を発生させ、売上高は数億元に上り、私たちは自社の商業的信頼を非常に重視しています。詳細情報は「正規品保証」、「当社について」のセクションをご覧ください。",
"content_type": "html",
"user_id": 1,
"user_name": "Lucy",
"user_email": "lucy_customer@qq.com",
"user_cellphone": "14923491300",
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "高",
"status": "オープン",
"status_en": "open",
"platform": "メール",
"satisfaction": null,
"custom_fields": {
"TextField_3": "rytffgfgfddddsssｄ大調",
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_38": "私の新しい場所",
"TextField_40": "テキスト",
"TextField_41": [
{
"id": 9334,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
},
{
"id": 9336,
"url": "https://pro-upload-center.udeskcs.com/aaaa.xlsx?Expires=1718787706&OSSAccessKeyId=bPexlr6MCcadDhfu&Signature=ineI1UotahrTKaD1JHysdz0dQmE%3D",
"name": "aaaa.xlsx",
"size": 18814810
}
]
},
"tags": "",
"followers": [],
"im_sub_session_id": 125,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
}
],
"creator_id": 1,
"created_at": "2017-07-10T15:45:34.000+08:00",
"updated_at": "2017-07-11T15:57:27.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-07-11T15:57:27.000+08:00",
"agent_replied_at": "2017-07-11T15:57:27.000+08:00",
"customer_replied_at": "2017-07-10T15:45:33.000+08:00",
"replied_by": "alalla"
}
},
{
"ticket": {
"id": 2,
"field_num": "#639",
"subject": "支払い方法は？代金引換は対応していますか？購入時に在庫はありますか？",
"content": "聚美优品はアリペイ口座及びクイックペイに対応しており、同時に国内数十社の主流銀行のデビットカード/クレジットカード決済にも対応しています。お客様の資金の安全を確保します。また、北京市内8区のユーザーは代金引換を選択できます。販売中の全商品は直接購入可能で、カスタマーサポートへの連絡は必要ありません。",
"content_type": "html",
"user_id": 2,
"user_name": null,
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "高",
"status": "クローズ済み",
"status_en": "closed",
"platform": "メール",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 125734,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 2,
"created_at": "2017-07-10T15:45:34.000+08:00",
"updated_at": "2017-07-10T15:45:34.000+08:00",
"solving_at": "2017-07-10T15:45:34.000+08:00",
"resolved_at": "2017-07-10T15:45:34.000+08:00",
"closed_at": "2017-07-10T15:45:34.000+08:00",
"solved_deadline": null,
"replied_at": "2017-07-10T15:45:34.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-07-10T15:45:34.000+08:00",
"replied_by": ""
}
},
{
"ticket": {
"id": 3,
"field_num": "#640",
"subject": "キャッシュクーポンの使用方法は？",
"content": "キャッシュクーポンの使用方法は？キャッシュクーポンの使用方法は？キャッシュクーポンの使用方法は？",
"content_type": "html",
"user_id": 2,
"user_name": null,
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 2,
"assignee_name": "Tom",
"assignee_avatar": null,
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "低",
"status": "オープン",
"status_en": "open",
"platform": "メール",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 2357,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 2,
"created_at": "2017-07-10T15:45:35.000+08:00",
"updated_at": "2017-07-10T20:50:48.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-07-10T20:50:48.000+08:00",
"agent_replied_at": "2017-07-10T20:50:48.000+08:00",
"customer_replied_at": "2017-07-10T15:45:35.000+08:00",
"replied_by": "alalla"
}
}
],
"meta": {
"total_count": 3,
"total_pages": 1,
"current_page": 1,
}
}
チケット返信の取得
このインターフェースは、特定のチケットのすべての返信を取得するために使用されます。
リクエストメソッド
get /tickets/:id/replies
リクエストパラメータ(url)
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数型 | チケットID |
リクエストパラメータ(string)
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| page | 整数型 | いいえ | ページ番号、デフォルト値は1 |
| per_page | 整数型 | いいえ | 1ページあたりのレコード数、デフォルト値20、最大値100 |
- 注意：
- per_pageパラメータが20未満の場合も20件表示され、パラメータ値が100を超える場合は100件表示されます。
返却結果
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| replies | 配列 | 返信リスト、構造は以下を参照 |
| meta | オブジェクト | ページネーション関連 |
repliesのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数型 | 返信ID |
| content | 文字列 | 返信内容 |
| content_format | 文字列 | コンテンツのタイプ、"text"/"html" |
| created_at | 日時 | 作成時間 |
| function_type | 文字列 | 返信タイプ,"internal"内部メモ/"external"外部コメント |
| cc | 文字列 | CC対象メールアドレス |
| attachments | 配列 | 添付ファイル関連情報、構造は以下を参照 |
| author | オブジェクト | 返信者情報、構造は以下を参照 |
attachmentsのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| url | 文字列 | 添付ファイルリンク |
| file_name | 文字列 | 添付ファイル名 |
| file_size | 整数型 | 添付ファイルサイズ |
authorのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数型 | 返信者ID |
| user_type | 文字列 | 返信者タイプ |
| 文字列 | 返信者メールアドレス | |
| avatar | 文字列 | 返信者アバターURL |
| nick_name | 文字列 | 返信者ニックネーム |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/1/replies?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返却
{
"code": 1000,
"replies": [
{
"content": "返信しました",
"content_format": "html",
"created_at": "2017-09-25T16:37:30.486+08:00",
"function_type": "internal",
"cc": "1032750611@qq.com,2633233452@qq.com",
"author": {
"id": 13,
"user_type": "agent",
"email": "agent11@udesk.cn",
"avatar": "",
"nick_name": "agent11@udesk.cn"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル2",
"file_size": 1222
}
]
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 1
}
}
チケット変更履歴の取得
このAPIは、特定のチケットのすべての変更履歴を取得するために使用されます。
リクエストメソッド
get /tickets/:id/change_logs
リクエストパラメータ(url)
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数 | チケットID |
リクエストパラメータ(string)
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| page | 整数 | いいえ | ページ番号、デフォルト値は1 |
| per_page | 整数 | いいえ | 1ページあたりのレコード数、デフォルト値は20、最大値は100 |
- 注意：
- per_pageパラメータが20未満の場合でも20件表示され、100を超える場合は100件表示されます。
レスポンス結果
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| meta | オブジェクト | ページネーション関連 |
| change_logs | 配列 | 変更リスト、構造は以下を参照 |
change_logsのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数 | 変更記録ID |
| created_at | 日時 | 作成時間 |
| author | オブジェクト | 変更操作者情報、構造は以下を参照 |
| changes | 配列 | 具体的な変更項目、構造は以下を参照 |
authorのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数 | 変更操作者ID |
| user_type | 文字列 | 変更操作者タイプ |
| 文字列 | 変更操作者メールアドレス | |
| avatar | 文字列 | 変更操作者アバターURL |
| nick_name | 文字列 | 変更操作者ニックネーム |
changesのデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| trigger_name | 文字列 | チケットトリガー名 |
| field | 文字列 | フィールド |
| field_name | 文字列 | フィールド名 |
| field_type | 文字列 | フィールドタイプ |
| old_value | 文字列 | フィールド旧値 |
| new_value | 文字列 | フィールド新値 |
| description | 文字列 | 変更説明 |
例
リクエスト
curl http://demo.udesk.cn/open_api_v1/tickets/1/change_logs?email=admin@udesk.cn&nonce=9e90a68067d965faa2b8&sign=6a8db7918f757887f8e7946df4c40a646c061d3e4f96544092fc551ebb63d043&sign_version=v2×tamp=1597909197
レスポンス
{
"code": 1000,
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 3
},
"change_logs": [
{
"id": 20867,
"created_at": "2020-07-15T16:26:52.000+08:00",
"author": {
"id": 1,
"user_type": "agent",
"email": "admin@udesk.cn",
"avatar": "https://demo.udesk.cn/test_1571111491_788.jpg",
"nick_name": "admin"
},
"changes": [
{
"trigger_name": null,
"field": "subject",
"field_name": "タイトル",
"field_type": "static",
"old_value": "xx",
"new_value": "xxhaha",
"description": "タイトル: xx---->xxhaha"
},
{
"trigger_name": "test",
"field": "priority_id",
"field_name": "優先度",
"field_type": "static",
"old_value": "緊急",
"new_value": "低",
"description": "優先度: 緊急---->低(トリガー「test」経由)"
}
]
}
]
}
チケットカスタムフィールドの取得（非推奨）
このAPIは、作成済みのすべてのチケットカスタムフィールドを取得するために使用されます。
リクエストメソッド
get /tickets/custom_fields
リクエストパラメータ
なし
レスポンスデータ
| 属性名 | 型 | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
| ticket_custom_field | 配列 | カスタムフィールドのリスト |
このAPIはカスケードフィールドをサポートしていません。カスケードフィールドの情報は取得できますが、その options の形式は正しくありません。
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/custom_fields?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス
{
"code": 1000,
"message": "success",
"ticket_custom_fields": [
{
"field_name": "TextField_1",
"field_label": "単一行テキストフィールド",
"content_type": "text",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_2",
"field_label": "複数行テキストフィールド",
"content_type": "area_text",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_3",
"field_label": "日付フィールド",
"content_type": "date",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_4",
"field_label": "日時フィールド",
"content_type": "datetime",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_5",
"field_label": "リンクフィールド",
"content_type": "link",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_6",
"field_label": "地理位置フィールド",
"content_type": "location",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_7",
"field_label": "時間フィールド",
"content_type": "time",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_8",
"field_label": "正の整数フィールド",
"content_type": "number",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "TextField_9",
"field_label": "数値フィールド",
"content_type": "numeric",
"comment": null,
"options": null,
"permission": 2,
"requirment": false
},
{
"field_name": "SelectField_1",
"field_label": "ドロップダウンリストフィールド",
"content_type": "droplist",
"comment": null,
"options": [
{
"0": "ドロップダウンオプション１"
},
{
"1": "ドロップダウンオプション２"
}
],
"permission": 2,
"requirment": true
},
{
"field_name": "SelectField_2",
"field_label": "ラジオボタンフィールド",
"content_type": "radio",
"comment": null,
"options": [
{
"0": "ラジオボタンオプション１"
},
{
"1": "ラジオボタンオプション２"
}
],
"permission": 2,
"requirment": true
},
{
"field_name": "SelectField_3",
"field_label": "チェックボックスフィールド",
"content_type": "checkbox",
"comment": null,
"options": [
{
"0": "チェックボックスオプション１"
},
{
"1": "チェックボックスオプション２"
},
{
"2": "チェックボックスオプション３"
},
{
"3": "チェックボックスオプション４"
}
],
"permission": 2,
"requirment": true
}
]
}
チケットテンプレートリストの取得
このインターフェースは、作成済みのすべてのチケットテンプレートのリスト情報を取得するために使用されます。
リクエストメソッド
get /tickets/ticket_templates
リクエストパラメータ
なし
レスポンスデータ
| 属性名 | 型 | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
| templates | 配列 | チケットテンプレートリストの詳細、構造は以下を参照 |
templates内の要素の構造
| 属性名 | 型 | 説明 |
|---|---|---|
| id | 整数 | テンプレートID |
| name | 文字列 | テンプレート名 |
| description | 文字列 | テンプレートの説明 |
| custom_fields | 配列 | テンプレートに含まれるカスタムフィールド、以下を参照 |
| updated_at | 日時 | テンプレートの最終更新日時 |
custom_fields内の要素の構造
| 属性名 | 型 | 説明 |
|---|---|---|
| field_id | 文字列 | テンプレート内の特定フィールドのID |
| field_name | 文字列 | テンプレート内の特定フィールドの名前 |
| field_title | 文字列 | テンプレート内の特定フィールドのタイトル |
| field_type | 文字列 | テンプレート内の特定フィールドのタイプ |
| field_detail | 文字列 | テンプレート内の特定フィールドの詳細説明 |
サンプル
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/ticket_templates?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス
{
"code": 1000,
"message": "success",
"templates": [
{
"id": 1,
"name": "デフォルト",
"description": "",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"custom_fields": [
{
"field_id": 1,
"field_type": "TextField",
"field_name": "TextField_1",
"field_title": "単行テキスト",
"field_detail": null
},
{
"field_id": 2,
"field_type": "TextField",
"field_name": "TextField_2",
"field_title": "複数行テキスト",
"field_detail": null
},
{
"field_id": 3,
"field_type": "TextField",
"field_name": "TextField_3",
"field_title": "日付",
"field_detail": null
},
{
"field_id": 4,
"field_type": "TextField",
"field_name": "TextField_4",
"field_title": "日時",
"field_detail": null
},
{
"field_id": 5,
"field_type": "TextField",
"field_name": "TextField_5",
"field_title": "地理位置",
"field_detail": null
},
{
"field_id": 6,
"field_type": "TextField",
"field_name": "TextField_6",
"field_title": "時間",
"field_detail": null
},
{
"field_id": 7,
"field_type": "TextField",
"field_name": "TextField_7",
"field_title": "リンク",
"field_detail": null
},
{
"field_id": 8,
"field_type": "TextField",
"field_name": "TextField_8",
"field_title": "正の整数",
"field_detail": null
},
{
"field_id": 1,
"field_type": "SelectField",
"field_name": "SelectField_1",
"field_title": "ドロップダウンリスト",
"field_detail": null
},
{
"field_id": 2,
"field_type": "SelectField",
"field_name": "SelectField_2",
"field_title": "ラジオボタン",
"field_detail": null
},
{
"field_id": 3,
"field_type": "SelectField",
"field_name": "SelectField_3",
"field_title": "チェックボックス",
"field_detail": null
},
{
"field_id": 4,
"field_type": "SelectField",
"field_name": "SelectField_4",
"field_title": "カスケード",
"field_detail": null
}
]
},
{
"id": 30002,
"name": "テンプレート1",
"description": "",
"updated_at": "2017-08-18T12:06:02.000+08:00",
"custom_fields": [
{
"field_id": 11,
"field_type": "TextField",
"field_name": "TextField_11",
"field_title": "単行テキスト２",
"field_detail": null
},
{
"field_id": 14,
"field_type": "TextField",
"field_name": "TextField_14",
"field_title": "複数行テキスト２",
"field_detail": "テキスト２"
},
{
"field_id": 18,
"field_type": "TextField",
"field_name": "TextField_18",
"field_title": "リンク２",
"field_detail": null
},
{
"field_id": 41,
"field_type": "TextField",
"field_name": "TextField_41",
"field_title": "地理位置２",
"field_detail": null
},
{
"field_id": 3,
"field_type": "SelectField",
"field_name": "SelectField_3",
"field_title": "ドロップダウン",
"field_detail": null
},
{
"field_id": 5,
"field_type": "SelectField",
"field_name": "SelectField_5",
"field_title": "複数選択",
"field_detail": null
},
{
"field_id": 6,
"field_type": "SelectField",
"field_name": "SelectField_6",
"field_title": "カスケード",
"field_detail": null
}
]
}
]
}
チケットフィルターリストの取得
このインターフェースは、作成済みの一部またはすべてのフィルターを取得するために使用されます。
リクエストメソッド
get /tickets/filters
リクエストパラメータ（Request Body）
| パラメータ名 | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| type | いいえ | 文字列 | 値は3種類あります: agent, agent_group, all | |
| id | いいえ | 整数 | 対応するtypeの具体的なid。typeがallの場合は、idは不要です。 | |
| page | いいえ | 整数 | ページ番号、デフォルトは1 | |
| per_page | いいえ | 整数 | 1ページあたりのレコード数、デフォルトは20、最大値は50 |
- typeがallの場合、すべてのカスタマーサポート担当者が閲覧可能なフィルターを取得します。
- typeがagentの場合、id（カスタマーサポート担当者ID）を渡すと指定したカスタマーサポート担当者が閲覧可能なフィルターを取得し、idを渡さない場合はカスタマーサポート担当者が閲覧可能なフィルターを取得します。
- typeがagent_groupの場合、id（カスタマーサポートグループID）を渡すと指定したカスタマーサポートグループが閲覧可能なフィルターを取得し、idを渡さない場合はカスタマーサポートグループが閲覧可能なフィルターを取得します。
- typeのデフォルト値は空で、会社下のすべてのフィルターを取得します。
レスポンスデータ
| 属性 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
| filters | 配列 | フィルター情報、詳細は以下を参照 |
| meta | オブジェクト | ページネーション関連の内容 |
filtersのデータ構造
| 属性 | タイプ | 説明 |
|---|---|---|
| id | 整数 | フィルターID |
| name | 文字列 | フィルター名 |
| description | 文字列 | フィルターの説明 |
| active | ブール値 | フィルターの状態、オンまたはオフ |
| permission | 文字列 | 権限範囲 |
| permission_id | 整数 | 権限を持つカスタマーサポート担当者またはグループのID |
| display_position | 文字列 | フィルターの表示位置 |
| created_at | 日時 | 作成日時 |
| updated_at | 日時 | 最終更新日時 |
- 注意：
- 取得したチケットフィルターレコードのうち、permissionの値がallである場合、permission_idは空になり、すべてのカスタマーサポート担当者を表します。
サンプル
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/filters?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス
{
"code": 1000,
"message": "success",
"filters": [
{
"id": 2,
"name": "私の未解決チケット",
"description": null,
"active": true,
"permission": "All",
"permission_id": null,
"display_position": "im_workbench",
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T09:42:10.000+08:00"
},
{
"id": 4,
"name": "すべての未解決チケット",
"description": null,
"active": true,
"permission": "agent",
"permission_id": 1,
"display_position": "cc_workbench",
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T12:45:40.000+08:00"
},
{
"id": 7,
"name": "すべての緊急チケット",
"description": null,
"active": false,
"permission": "agent_group",
"permission_id": 12,
"display_position": "ticket_workbench",
"created_at": "2017-07-10T15:45:32.000+08:00",
"updated_at": "2017-08-22T12:46:10.000+08:00"
}
],
"meta": {
"current_page": 1,
"total_pages": 1,
"total_count": 3
}
}
特定チケットフィルター下のチケットを取得
指定されたチケットフィルター下のチケットを取得するためのインターフェースです。
リクエストメソッド
get /tickets/tickets_in_filter
リクエストパラメータ（クエリストリング）
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| filter_id | 整数 | はい | チケットフィルターID | |
| page | 整数 | いいえ | ページ番号、デフォルトは1 | |
| per_page | 整数 | いいえ | 1ページあたりのレコード数、デフォルトは20、最大100 |
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| message | 文字列 | 実行結果の説明 |
| contents | 配列 | チケットリスト、各要素の内容はチケットデータ構造を参照してください |
| meta | オブジェクト | ページネーション関連の内容 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/tickets_in_filter?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=2
レスポンス
{
"code": 1000,
"message": "success",
"contents": [
{
"ticket": {
"id": 11,
"field_num": "#13",
"subject": "娃哈哈",
"content": "",
"content_type": "html",
"user_id": 175,
"user_name": "哈哈",
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "標準",
"status": "オープン",
"status_en": "open",
"platform": "手動入力",
"satisfaction": null,
"custom_fields": {},
"tags": "",
"followers": [],
"im_sub_session_id": 3891,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-18T16:59:56.000+08:00",
"updated_at": "2017-08-18T16:59:56.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-18T16:59:56.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-18T16:59:56.000+08:00",
"replied_by": "哈哈"
}
},
{
"ticket": {
"id": 12,
"field_num": "#30",
"subject": "你好 \"lskjdflkjsak \\asdf ",
"content": "",
"content_type": "html",
"user_id": 174,
"user_name": "lalllala",
"user_email": "",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "標準",
"status": "オープン",
"status_en": "open",
"platform": "手動入力",
"satisfaction": null,
"custom_fields": {
"SelectField_3": "0",
"SelectField_4": "0",
"TextField_40": "asdfasdf dddd",
"TextField_3": "asdfsad "
},
"tags": "",
"followers": [],
"im_sub_session_id": 38,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-18T16:55:05.000+08:00",
"updated_at": "2017-08-18T18:45:23.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-18T16:55:05.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-18T16:55:05.000+08:00",
"replied_by": "lalllala"
}
},
{
"ticket": {
"id": 131,
"field_num": "#768",
"subject": "weurouew",
"content": "<p>asdfasdf</p>",
"content_type": "html",
"user_id": 143,
"user_name": "姓名１０２",
"user_email": "3468567@qq.com",
"user_cellphone": null,
"organization_id": null,
"assignee_id": 1,
"assignee_name": "alalla",
"assignee_avatar": "",
"user_group_id": null,
"user_group_name": null,
"template_id": 1,
"priority": "標準",
"status": "オープン",
"status_en": "open",
"platform": "手動入力",
"satisfaction": null,
"custom_fields": {
"TextField_13": {
"keyword": "ああ、そうです、発生しました"
},
"TextField_18": {
"keyword": "ああ、拡大サタン法アストン送信asdf"
}
},
"tags": "",
"followers": [],
"im_sub_session_id": 278,
"attachments": [
{
"name": "添付ファイル1",
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6-1511169203.txt"
},
],
"creator_id": 1,
"created_at": "2017-08-07T23:23:37.000+08:00",
"updated_at": "2017-08-07T23:23:37.000+08:00",
"solving_at": null,
"resolved_at": null,
"closed_at": null,
"solved_deadline": null,
"replied_at": "2017-08-07T23:23:37.000+08:00",
"agent_replied_at": null,
"customer_replied_at": "2017-08-07T23:23:37.000+08:00",
"replied_by": "姓名１０２"
}
}
],
"meta":{
"total_count": 3,
"total_pages": 1,
"current_page": 1
}
}
チケットエクスポート
このインターフェースは、大量のチケット情報をエクスポートするために使用されます。 指定されたフィルターでチケットを絞り込むことをサポートしています。
リクエスト方法
GET /tickets/export
このインターフェースの使用方法:
filter_idを使用してこのインターフェースを呼び出します。結果には最初のバッチのデータとscroll_idが含まれます。- データ処理が完了したら、前回の呼び出しで返された
scroll_idを使用して再度このインターフェースを呼び出します（この時はfilter_idを渡す必要はありません）。結果には2番目のバッチのデータと新しいscroll_idが含まれます。 - 返される結果の
contentsが空になるまで、ステップ2を繰り返します。
注意: 以降の各呼び出しでは、前回の呼び出しで返された新しい scroll_id を使用する必要があります。scroll_id は1分後に期限切れになります。
リクエストパラメータ（Query String）
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| filter_id | 整数型 | はい | チケットフィルターID。このフィルターの絞り込み結果をエクスポートします。 | |
| scroll_id | 文字列型 | いいえ | 次のバッチのデータを取得するためのID。前回の本インターフェース呼び出しの結果から取得します。 | |
| export_timers | 整数型 | いいえ | チケット処理時間をエクスポートするかどうか (1: はい 0: いいえ デフォルト: 0) |
返却データ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード、1000は成功を表します |
| scroll_id | 文字列 | 次のデータバッチを取得するためのID |
| total | 整数 | データ総数 |
| contents | 配列 | チケットリスト、内容は特定のチケットフィルター下のチケットを取得のcontentsと一致します |
チケット処理時間フィールド説明
| 属性名 | タイプ | 説明 |
|---|---|---|
| timers | 配列 | チケット処理時間情報 |
| rule_id | 整数 | チケット処理時間ルールID |
| name | 文字列 | ルール名 |
| status | 配列 | チケット処理時間ステータス(not_start 未開始, running 実行中, pause 一時停止, finish 終了) |
| duration | 整数 | チケット処理時間、単位は秒 |
| time_type | 整数 | 単回トリガー、複数回トリガー (0 単回トリガー, 1 複数回トリガー) |
| start_at | 文字列 | 開始時間 |
| end_at | 文字列 | 終了時間 |
| timer_steps | 配列 | 複数回トリガーセグメント時間 |
| id | 整数 | 複数回トリガーセグメント時間ID |
| duration | 整数 | 複数回トリガーセグメント時間長 |
| start_at | 文字列 | 複数回トリガーセグメント開始時間 |
| end_at | 文字列 | 複数回トリガーセグメント終了時間 |
注意: 一度に取得できる contents の最大数は1000件です。返却結果の contents の数が0の場合、エクスポートが終了したことを示します。
サンプル
# 初回呼び出し
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&filter_id=1
# 後続の呼び出し
curl https://demo.udesk.cn/open_api_v1/tickets/export?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&scroll_id=DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n
レスポンス
{
"code": 1000,
"scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n",
"total": 10000,
"contents": [ {
"ticket": {
/*チケットの他のフィールドは、特定のチケットフィルター下のチケットのcontentsと一致します*/
"timers": [
{
"name": "チケット処理時間",
"duration": 6470,
"status": "finish",
"rule_id": 440,
"time_type": 0,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00"
},
{
"name": "複数回トリガー",
"duration": 6453,
"status": "finish",
"rule_id": 443,
"time_type": 1,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00",
"timer_steps": [
{
"id": 137,
"duration": 6453,
"start_at": "2024-04-11T09:18:13.000+08:00",
"end_at": "2024-04-11T11:06:03.000+08:00"
}
]
}
]
}
}]
}
添付ファイルのアップロード
このインターフェースは、指定されたチケットに添付ファイルをアップロードするために使用されます。
リクエストメソッド
post /tickets/upload_file
リクエストパラメータ（クエリストリング）
| パラメータ名 | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| ticket_id | はい | 整数 | チケットID | |
| file_name | はい | 文字列 | ファイル名（例：screenshot.gif） | 最大長255文字 |
| type | いいえ | 文字列 | ファイルタイプ（例：image/gif） | 最大長255文字 |
リクエストパラメータ（リクエストボディ）
- 注意：
- リクエストで
Content-type:application/octet-streamを指定し、アップロードするファイルをストリームファイルに変換してリクエストボディに配置してください。 - 必ず
file_nameでファイルの拡張子を指定してください。指定しないとファイルを認識できません。
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード（1000は成功を表します） |
| message | 文字列 | 結果の説明（以下の表を参照） |
messageの説明
| 属性名 | タイプ | 説明 |
|---|---|---|
| msg | 文字列 | 実行結果の説明 |
| url | 文字列 | 添付ファイルのURLアドレス |
| attachment_id | 整数 | 添付ファイルID |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/upload_file?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&ticket_id=1&file_name=my_picture.gif&type=image/gif -H 'Content-type:application/octet-stream' --data-binary @my_picture.gif
レスポンス
{
"code": 1000,
"message": {
"msg": "アップロード成功",
"url": "https://qn-public.udesk.cn/my_picture.gif",
"attachment_id": 1001
}
}
サポートスタッフの返信
このインターフェースは、サポートスタッフが顧客に返信するために使用されます。
POST /tickets/agent_reply
リクエストパラメータ（リクエストボディ）
| パラメータ名 | タイプ | 必須 | 説明 | 制限事項 |
|---|---|---|---|---|
| id | 整数型 | いいえ | チケットID | |
| num | 文字列 | いいえ | チケット番号 | |
| agent_id | 整数型 | はい | カスタマーサポートID | |
| function_type | 文字列 | はい | 返信タイプ,"internal"内部メモ／"external"外部コメント | |
| new_reply | 文字列 | はい | 返信内容 | |
| cc | 配列 | いいえ | CCされるカスタマーサポートのメールアドレス | |
| cc_customer | 配列 | いいえ | CCされる顧客のメールアドレス | |
| attachment_ids | 配列 | いいえ | アップロードされた添付ファイルのID |
- 注意：idとnumは同時に渡すことはできませんが、いずれか一方は必ず渡す必要があります。
- 各返信において、CCされるカスタマーサポートのメールアドレスと顧客のメールアドレスのそれぞれの数は10個を超えてはいけません。
- 返信に添付ファイルが必要な場合は、まず「チケット返信添付ファイルアップロード」インターフェースを呼び出してください。複数回呼び出して複数の戻り値を取得し、パラメータattachment_idの値として使用できます。
- 本インターフェースの呼び出し時刻が最後の添付ファイルアップロード時刻から2時間を超える場合、それ以前にアップロードされたすべての添付ファイルは無効となり、今回の返信には添付ファイルがないものとみなされます。
- new_replyはリッチテキストをサポートしています。new_replyに画像リソースが含まれる場合は、画像リンクアドレス（例：https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg）を渡してください。画像をエンコードしてsrcの後に配置することはできません。
レスポンスデータ
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| type | 文字列 | 返信タイプ |
| id | 整数型 | 返信ID |
| content | 文字列 | 返信内容 |
| content_format | 文字列 | コンテンツのタイプ、textプレーンテキスト／htmlリッチテキスト |
| created_at | 日付型 | 作成日時 |
| function_type | 文字列 | 返信タイプ,"internal"内部メモ／"external"外部コメント |
| author | オブジェクト | 返信者情報 |
| cc | 文字列 | CCされた者（カスタマーサポートおよび顧客）のニックネームとメールアドレス、詳細は例を参照 |
| attachments | 配列 | 添付ファイルの情報 |
author のデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| id | 整数型 | 返信者ID |
| user_type | 文字列 | 返信者の身分 |
| 文字列 | 返信者のメールアドレス | |
| avatar | 文字列 | 返信者のアバター |
| nick_name | 文字列 | 返信者のニックネーム |
attachments のデータ構造
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| url | 文字列 | 添付ファイルのリンク |
| file_name | 文字列 | 添付ファイルの名前 |
| file_size | 整数型 | 添付ファイルのサイズ |
サンプル
リクエスト：
curl https://demo.udesk.cn/open_api_v1/tickets/agent_reply?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 '{
"id": 159,
"agent_id": 13,
"function_type": "internal",
"attachment_ids": [209],
"new_reply": "これは新しい返信内容です",
"cc": ["1032750611@qq.com","2633233452@qq.com"]
}'
レスポンス：
{
"code": 1000,
"data": {
"type": "reply",
"data": {
"id":10011,
"content": "返信しました",
"content_format": "html",
"created_at": "2017-09-25T16:37:30.486+08:00",
"function_type": "internal",
"cc": "テストサポート01 <alus@1265.com>, テスト顧客44 <lmy123003@sina1.com>",
"author": {
"id": 13,
"user_type": "agent",
"email": "agent11@udesk.cn",
"avatar": null,
"nick_name": "agent11@udesk.cn"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル2",
"file_size": 1222
}
]
}
}
}
顧客返信
このインターフェースは、顧客がサポートスタッフに返信するために使用されます。
POST /tickets/customer_reply
リクエストパラメータ (request body)
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| id | 整数型 | いいえ | チケットID | |
| num | 文字列 | いいえ | チケット番号 | |
| new_reply | 文字列 | はい | 返信内容 | |
| content_type | 文字列 | はい | 返信内容タイプ, html/text | |
| attachment_ids | 配列 | いいえ | アップロードした添付ファイルID |
- 注意：idとnumは同時に渡すことはできませんが、いずれか一方は渡す必要があります。
- 各返信において、CCされるサポートスタッフのメールアドレスとCCされる顧客のメールアドレスのそれぞれの数は10個を超えてはいけません。
- 返信に添付ファイルが必要な場合は、まず「チケット返信添付ファイルアップロード」インターフェースを呼び出してください。複数回呼び出して複数の戻り値を取得し、パラメータattachment_idの値として使用できます。
- このインターフェースの呼び出し時刻が最後の添付ファイルアップロード時刻から2時間以上経過している場合、それ以前にアップロードされたすべての添付ファイルは無効となり、今回の返信には添付ファイルがないものとみなされます。
- new_replyはリッチテキストをサポートしています。new_replyに画像リソースが含まれる場合は、画像のリンクURL（例：https://mpic.tiankong.com/077/708/0777089ad18a688eee7c756a506e5f4a/640.jpg）を渡してください。画像をエンコードしてsrcの後に配置することはできません。
返却データ
返却結果については、サポートスタッフ返信の返却データを参照してください。
例
リクエスト：
curl https://demo.udesk.cn/open_api_v1/tickets/customer_reply?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 '{
"id": 159,
"content_type": "html",
"new_reply": "<p>これは新しい返信内容です</p>",
"attachment_ids": [201,202]
}'
返信：
{
"code": 1000,
"data": {
"type": "reply",
"data": {
"id": 10011,
"content": "<p>これは新しい返信内容です</p>",
"content_format": "html",
"created_at": "2017-09-25T17:51:44.124+08:00",
"function_type": "external", // 返信タイプ: "internal"内部メモ／"external"外部コメント
"author": {
"id": 48,
"user_type": "customer",
"email": null,
"avatar": null,
"nick_name": "13000022457"
},
"attachments": [
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル1",
"file_size": 1222
},
{
"url": "https://qn-public.udesk.cn/%E7%94%A8%E4%BA%8E%E4%B8%8A%E4%BC%A0%E7%9A%84%E6%96%87%E4%BB%B6",
"file_name": "アップロード用ファイル2",
"file_size": 1222
}
]
}
}
}
チケット返信でのファイル添付
このインターフェースは、チケット返信時にファイルを添付する場合のみに使用します。
リクエストメソッド
post /tickets/upload_file_for_reply
リクエストパラメータ(Query String)
| パラメータ名 | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| ticket_id | 必須 | 整数 | チケットID | |
| file_name | 必須 | 文字列 | ファイル名（例：screenshot.gif） | 最大長255文字 |
| type | 任意 | 文字列 | ファイルタイプ（例：image/gif） | 最大長255文字 |
リクエストパラメータ (Request Body)
- 注意点：
- リクエストで
Content-type: application/octet-streamを指定し、アップロードするファイルをストリームファイルに変換してリクエストボディに配置してください。 - 1回のアップロードで1つのファイルを添付します。添付ファイルのサイズは20MBを超えないようにしてください。複数回アップロードが可能です。同じチケットへの1回の返信に対して複数のファイルを添付する場合、それらのファイルの合計サイズは20MBを超えないようにしてください。
- ファイルの拡張子を
file_nameで必ず指定してください。指定がない場合、ファイルを識別できません。
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード。1000は成功を表します。 |
| message | 文字列 | 結果の説明。詳細はメッセージ情報を参照してください。 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/upload_file_for_reply?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2&ticket_id=1&file_name=test.png&type=image/png -H 'Content-type:application/octet-stream' --data-binary @/home/udesk/Pictures/test.png
レスポンス
{
"code": 1000,
"message": {
"msg": "アップロード成功",
"url": "https://qn-public.udesk.cn/截my_picture.gif",
"attachment_id": 1,
"attachable_type": "Reply"
}
}
チケットファイルフィールドへのファイル添付
このインターフェースは、チケットのファイルタイプのカスタムフィールドにファイルを添付する場合のみに使用します。添付ファイルを削除する場合は、チケット更新インターフェースを参照してください。
リクエストメソッド
post /tickets/upload_file_for_file_field
リクエストパラメータ(Query String)
| パラメータ名 | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| ticket_id | 必須 | 整数 | チケットID | |
| file_name | 必須 | 文字列 | ファイル名（例：screenshot.gif） | 最大長255文字 |
| type | 任意 | 文字列 | ファイルタイプ（例：image/gif） | 最大長255文字 |
| field_name | 必須 | 文字列 | フィールド識別子（例：TextField_12） |
リクエストパラメータ (Request Body)
- 注意：
- リクエストに Content-type:application/octet-stream を指定し、アップロードするファイルをストリームファイルに変換して request body に配置してください。
- 一度に1つのファイルをアップロードします。ファイルはファイルカスタムフィールドの設定制限を受けます。
file_nameでファイルの拡張子を必ず指定してください。指定がない場合、ファイルを認識できません。
レスポンスデータ
| 属性名 | 型 | 説明
会社のチケット満足度調査を取得
GET /tickets/surveys
リクエストパラメータ
なし
返却結果
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 返却結果, 1000 は成功 |
| ticket_survey | オブジェクト | 満足度調査情報 |
ticket_survey の構造は以下の通りです:
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| title | 文字列 | タイトル |
| enable | ブール値 | 満足度調査が有効かどうか |
| note | ブール値 | 評価説明が有効かどうか |
| options | オブジェクト配列 | 評価オプション |
options の要素構造は以下の通りです
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| vote_number | 整数型 | オプション番号 |
| name | 文字列 | オプション説明 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/surveys?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
返却
{
"code": 1000,
"ticket_servey": {
"title": "チケット満足度調査",
"enable": true,
"note": false,
"options": [
{"vote_number": 1, "name": "非常に満足"},
{"vote_number": 2, "name": "満足"},
{"vote_number": 3, "name": "普通"}
]
}
}
チケット満足度を設定
PUT /tickets/take_survey
リクエストパラメータ
| パラメータ名 | タイプ | 必須 | 説明 | 制限 |
|---|---|---|---|---|
| ticket_id | 整数型 | はい | チケット番号 | |
| vote_number | 整数型 | はい | 評価オプション番号 | |
| vote_desc | 文字列 | いいえ | チケット満足度の備考情報 |
返却結果
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 返却結果, 1000 は成功 |
| message | 文字列 | 結果説明 |
例
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/take_survey?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type:application/json' \
-d '{
"ticket_id":1,
"vote_number":10,
"vote_desc":"本次服务体验非常完美"
}'
返却
{
"code": 1000,
"message": "success"
}
チケットの転送記録を取得
GET /tickets/work_records
リクエストパラメータ
| パラメータ名 | タイプ | 必須 | 説明 | 制約 |
|---|---|---|---|---|
| ticket_id | 整数型 | いいえ | チケットID | ticket_idとstart_time/end_timeが同時にパラメータとして渡された場合、ticket_idが優先されます |
| start_time | 文字列 | いいえ | チケット転送開始時間-開始 | start_time/end_timeは同時に渡すか、または渡さないかのどちらかです。形式（yyyy-MM-dd HH:mm:ss） |
| end_time | 文字列 | いいえ | チケット転送開始時間-終了 | start_time/end_timeは同時に渡すか、または渡さないかのどちらかです。形式（yyyy-MM-dd HH:mm:ss） |
| last_id | 整数型 | いいえ | 最後のチケットID | 初回検索時は渡さなくても構いません |
返却結果
| パラメータ名 | タイプ | 説明 |
|---|---|---|
| records | 配列 | チケット転送記録 |
| has_more | ブール型 | さらにデータがあるかどうか、true-はい、false-いいえ |
| last_id | 整数型 | 現在の検索における最後のデータのid。さらにデータがある場合、次回検索の入力パラメータlastIdとして使用できます |
recordsのデータ構造
| 属性 | タイプ | 説明 |
|---|---|---|
| ticket_id | 整数型 | チケットID |
| assignee_id | 整数型 | 担当者ID |
| assignee_name | 文字列 | 担当者名 |
| assignee_group_id | 整数型 | 担当者カスタマーサポートグループID |
| assignee_group_name | 文字列 | 担当者カスタマーサポートグループ名 |
| start_time | 日時 | 開始時間 |
| start_status | 整数型 | 開始時のチケット状態 |
| end_time | 日時 | 終了時間 |
| end_status | 整数型 | 終了時のチケット状態 |
| duration | 整数型 | 処理時間 |
| reply_num | 整数型 | 担当者の返信回数 |
サンプル
リクエスト
curl https://demo.udesk.cn/open_api_v1/tickets/work_records?ticket_id=&start_time=2024-11-10 00:00:00&end_time=2024-11-20 00:00:00&email=admin@udesk.cn×tamp=1732498203&sign=1b185dbeda2a4afc11da1e6fe6c14b43207356a4&nonce=82682003-b50c-422c-9e58-2dfd65ab0ddf&sign_version=v2
レスポンス
{
"records": [
{
"duration": null,
"ticket_id": 27172,
"assignee_id": null,
"assignee_name": null,
"assignee_group_id": null,
"assignee_group_name": null,
"start_time": "2024-11-19 21:39:07",
"start_status": "開く",
"end_time": null,
"end_status": null,
"reply_num": 0
}
],
"has_more": true,
"last_id": 55675,
"trace_id": "1b5c5a6dd1c34bcf8cf885f744e39101"
}
コードエラーコード説明
| エラーコード | message情報 | exception:message情報 | 説明 |
|---|---|---|---|
| 2000 | 申し訳ございません、お客様が入力されたオブジェクトticketは空にできません | なし | パラメータ{ticket}が入力されていないか、空値です |
| 申し訳ございません、チケットの説明は空にできません | なし | パラメータ{content}は空にできません | |
| 申し訳ございません、チケットの件名は空にできません | なし | パラメータ{subject}は空にできません | |
| 申し訳ございません、該当する顧客が見つかりません。先に顧客を作成してください | なし | パラメータ{type}、{content_type}に基づいて顧客が見つかりませんでした | |
| 優先度エラー | なし | パラメータ{priority_id}が許容範囲内の値ではありません | |
| 該当するカスタマーサポートが見つかりません | なし | パラメータ{assignee_email}に一致するカスタマーサポートが見つかりませんでした | |
| ステータスエラー | なし | パラメータ{status}の値が許容範囲を超えています | |
| 作成者カスタマーサポートが見つかりません | なし | パラメータ{creator_email}に一致するカスタマーサポートが見つかりませんでした | |
| 申し訳ございません、このカスタマーサポートはこのカスタマーサポートグループに所属していません | なし | パラメータ{assignee_email}がパラメータ{agent_group_name}に対応するカスタマーサポートグループに存在しません | |
| カスタマーサポートメールアドレスエラー | なし | パラメータ{assignee_email}の形式が誤っています | |
| カスタマーサポートグループエラー、該当するカスタマーサポートグループが見つかりません | なし | パラメータ{agent_group_name}が誤っています | |
| 作成者カスタマーサポートメールアドレスエラー | なし | パラメータ{creator_email}の形式が誤っています | |
| 作成者カスタマーサポートが見つかりません | なし | パラメータ{creator_email}に一致するデータが見つかりませんでした | |
| 日時の形式が正しくありません | なし | カスタムフィールド内の時間パラメータの形式が誤っています | |
| 申し訳ございません、idとnumのいずれか一方を入力する必要があり、空にすることはできません | なし | パラメータ{id}と{num}が入力されていません | |
| 申し訳ございません、このリソースは存在しません | なし | パラメータ{id}または{num}に一致するデータが見つかりませんでした | |
| 申し訳ございません、idとnumを同時に入力することはできません | なし | パラメータ{id}または{num}が同時に入力されています | |
| このカスタマーサポートは存在しません | なし | パラメータ{type}がagentで、パラメータ{id}に一致するカスタマーサポートが見つかりませんでした | |
| このカスタマーサポートグループは存在しません | なし | パラメータ{type}がagent_groupで、パラメータ{id}に一致するカスタマーサポートグループが見つかりませんでした | |
| 指定されたフィルターが見つかりません | なし | パラメータ{filter_id}に一致するフィルターが見つかりませんでした | |
| ticket_idは必須項目であり、空にすることはできません | なし | パラメータ{ticket_id}が空値であるか、入力されていません | |
| file_nameは必須項目であり、空にすることはできません | なし | パラメータ{file_name}が空値であるか、入力されていません | |
| field_nameは必須項目であり、空にすることはできません | なし | パラメータ{field_name}が空値であるか、入力されていません | |
| field_nameは正しいファイルフィールドではありません | なし | パラメータ{field_name}がファイルフィールドではありません | |
| ファイル数はx個を超えることはできません | なし | ファイルフィールドのファイル数が制限を超えています | |
| 単一ファイルのサイズはxxMBを超えることはできません | なし | ファイルフィールドの単一ファイルサイズが制限を超えています | |
| ファイルタイプエラー | なし | ファイルフィールドで許可されていないファイルタイプです | |
| 合計ファイルサイズはxxMBを超えることはできません | なし | ファイルフィールドの全ファイルの合計サイズが制限を超えています | |
| 申し訳ございません、このチケットは存在しません | なし | パラメータ{ticket_id}に一致するチケットデータが見つかりませんでした | |
| 1つのチケットには最大10個の添付ファイルをアップロードできます | なし | 添付ファイルの数が10個を超えています | |
| 申し訳ございません、まだ添付ファイルをアップロードしていません | なし | ストリームファイルがアップロードされていません | |
| 1つのチケットに関連付けられる添付ファイルの合計サイズは20mbを超えることはできません | なし | 1つのチケットに関連付けられた添付ファイルの合計サイズが20mbを超えています | |
| 申し訳ございません、アップロードされたファイルが20mbを超えています | なし | アップロードされた単一のストリームファイルのサイズが20mを超えています | |
| 申し訳ございません、返信内容new_replyは必須であり、空にすることはできません | なし | パラメータ{new_reply}が入力されていないか、空です | |
| 申し訳ございません、返信タイプfunction_typeは必須であり、空にすることはできません | なし | パラメータ{content_type}が入力されていないか、空です | |
| 申し訳ございません、カスタマーサポートidは必須であり、空にすることはできません | なし | パラメータ{agent_id}が空値であるか、入力されていません | |
| 申し訳ございません、カスタマーサポートidの値は整数型である必要があります | なし | パラメータ{agent_id}の形式が誤っています | |
| 申し訳ございません、チケットの顧客が存在しません | なし | パラメータ{id}に対応するチケットに関連付けられた顧客がいません | |
| 申し訳ございません、チケット |
なし | パラメータ{attachment_ids}が空値でない場合、このチケットは"チケット返信アップロード添付ファイル"に関連付けられていません | |
| 申し訳ございません、idが |
なし | パラメータ{attachment_ids}に一致するチケット返信アップロード添付ファイルが見つかりませんでした | |
| ccは配列形式ではありません | なし | {cc}パラメータの形式が誤っています | |
| cc_customerは配列形式ではありません | なし | パラメータ{cc_customer}の形式が誤っています | |
| 無料会社はCC（カーボンコピー）できません | なし | このカスタマーサポートが所属する会社は有料契約しておらず、この機能を使用できません | |
| CCする顧客の数は10を超えることはできません | なし | パラメータ{cc_customer}の配列の長さが10を超えています | |
| CCするカスタマーサポートの数は10を超えることはできません | なし | パラメータ{cc}の配列の長さが10を超えています | |
| チケット満足度調査が設定されていないか、チケット満足度調査が閉じられています | なし | この機能が設定されていないか、無効化されています。Web端末で設定する必要があります | |
| 不明なエラー | param is missing or the value is empty: ticket | {ticket}パラメータが入力されていないか、空です | |
| カスタマーサポートが見つかりません | パラメータ{agent_id}に一致するカスタマーサポートが見つかりませんでした | ||
| チケット担当者の担当グループが一致しません | パラメータ{agent_id}に対応するカスタマーサポートとパラメータ{agent_group_id}に対応するカスタマーサポートグループが一致しません | ||
| 検証失敗: Templateチケットテンプレートが存在しません | {emplate_id}パラメータに一致するデータが見つかりませんでした | ||
| 優先度が正しくありません | 入力された{priority_id}パラメータが許容範囲を超えています | ||
| ステータスが正しくありません | 入力された{status_id}パラメータが許容範囲を超えています | ||
| no implicit conversion of Array into Hash | {custom_fields}パラメータの入力形式が正しくありません | ||
| 件名は必須です | パラメータ{subject}が空値です | ||
| 2005 | このリソースが見つかりません | ユーザーxxxが見つかりません | パラメータ{follower_ids}に一致するデータが見つかりませんでした |
Couldn't find Ticket with id=XXX [WHERE tickets.company_id = ?] |
パラメータ{id}に一致する値が見つかりませんでした | ||
| 指定されたファイルフィールドが見つかりません | パラメータ{field_name}に一致する値が見つかりませんでした | ||
| 2062 | チケット情報の取得に失敗しました | なし | パラメータ{filter_id}と{scroll_id}が同時に存在します |
| 20573 | vote_numberが正の整数ではありません | なし | パラメータ{vote_number}が入力されていないか、形式が誤っています |
| 20576 | このチケットは既に評価されています | なし | {ticket_id}パラメータに対応するチケットは既に評価済みで、重複評価はできません |
| 40001 | 識別子タイプと値は両方同時に存在するか、または両方同時に空である必要があります | なし | なし |
| 40002 | サポートされていないcustomer_id_type | なし | なし |
| 40003 | customer_id_typeとcustomer_id_valueに基づいて顧客が見つかりません | なし | なし |