一部のフィールド値の説明

従業員タイプ(profile)の対応値

値 日本語名称
all 全チャネル従業員
im インスタントメッセージ従業員
call コールセンター従業員
ticket チケット従業員
dial 発信従業員

ucpapp_subaccount

属性名 タイプ 説明
number 文字列 SIPアカウント
password 文字列 SIPパスワード

lang 取り得る値

値 意味
zh-cn 簡体字中国語
en-us アメリカ英語

カスタマーサポートリストの取得

このインターフェースは、複数のカスタマーサポート情報を一度に取得するために使用されます。

リクエストメソッド

GET /agents

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

パラメータ名 必須 タイプ 説明 制限
page いいえ 整数型 ページ番号、1から開始、デフォルトは1
per_page いいえ 整数型 1ページあたりの件数、デフォルト20、最大100
with_disabled いいえ 文字列 無効化されたカスタマーサポートを含めるかどうか、デフォルトはfalse（無効化されたカスタマーサポートを含まない） true または false

レスポンスデータ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
meta オブジェクト ページネーション情報、詳細は共通データを参照
agents 配列 カスタマーサポートリスト、各カスタマーサポートの説明はカスタマーサポートデータを参照

カスタマーサポートデータ

属性名 タイプ 説明
id 整数型 一意の識別子
email 文字列 メールアドレス
nick_name 文字列 氏名
profile 文字列 従業員タイプ
aliase 文字列 表示名
cellphone 文字列 携帯電話番号
role_name 文字列 役割
duty 文字列 従業員職務
im_ability_value 整数型 チャットスキル値
user_group_ids 配列 所属カスタマーサポートグループIDリスト
password 文字列 コールセンターSIPアカウント情報
number 文字列 コールセンターSIPアカウント情報
avatar 文字列 アバター
work_id 文字列 従業員番号
departments オブジェクト 所属部門、id（部門ID）、name（部門名）を含む、詳細は例を参照
agent_callout_display_number 文字列 発信者番号表示
disable_status 文字列 状態
availability 文字列 チケット自動割り当てを受信するかどうか
im_welcomes 文字列 ウェルカムメッセージ
lang 文字列 言語設定
### サンプル 
curl https://demo.udesk.cn/open_api_v1/agents?page=1&per_page=10&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

レスポンス

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "agents": [
        {
            "id": 1,
            "email": "agent1@sample.com",
            "nick_name": "テストサポート1",
            "profile": "im",
            "aliase": null,
            "cellphone": "13300000001",
            "role_name": "agent",
            "duty": null,
            "im_ability_value": 10,
            "user_group_ids": [1,2],
            "number": "100000000",
            "password": "xxxxxxxx",
            "avatar": null,
            "work_id": "",
            "departments": [
            {
            "id": 1,
            "name": "demo"
            }
            ],
            "agent_callout_display_number": "10000000000",
            "disable_status": "enable",
            "availability": true,
            "im_welcomes": null
            "lang": null
        }
    ]
}

サポート担当者詳細を取得

このAPIは、指定された条件に一致するサポート担当者の情報を取得するために使用されます。

リクエストメソッド

GET /agents/get_agent

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

パラメータ名 タイプ 必須 説明 制限
type 文字列 はい 条件タイプ。詳細は以下を参照してください。
content 文字列 はい 条件内容
#### 条件タイプ
値 対応するcontentの意味
id エージェントID
email エージェントメールアドレス

レスポンスデータ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
agent オブジェクト エージェント情報

エージェントデータ

属性名 タイプ 説明
id 整数型 一意の識別子
email 文字列 メールアドレス
nick_name 文字列 氏名
profile 文字列 従業員タイプ
aliase 文字列 表示名
cellphone 文字列 携帯電話番号
role_name 文字列 ロール
duty 文字列 従業員職務
user_group_ids 配列 所属エージェントグループIDリスト
im_ability_value 整数型 チャットスキル値
work_id 文字列 社員番号
disable_status 文字列 有効または無効の状態 enable
availability ブール値 自動チケット割り当てを受け入れるかどうか
password 文字列 コールセンターSIPアカウント情報
number 文字列 コールセンターSIPアカウント情報
avatar 文字列 アバター
departments オブジェクト 所属部門
agent_callout_display_number 文字列 発信者番号表示
im_welcomes 文字列 ウェルカムメッセージ
lang 文字列 言語設定
tags 文字列 エージェントタグ、複数はカンマ区切り
user_groups 配列 所属エージェントグループ情報、詳細は例を参照
agent_roles 配列 所属ロール情報、詳細は例を参照
### サンプル 
curl https://demo.udesk.cn/open_api_v1/agents/get_agent?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&type=id&content=1

レスポンス

{
    "code": 1000,
    "agent": {
        "id": 1,
        "email": "agent1@sample.com",
        "nick_name": "テストサポート1",
        "profile": "im",
        "aliase": null,
        "cellphone": "13300000001",
        "role_name": "agent",
        "duty": null,
        "user_group_ids": [1,2],
        "im_ability_value": 10,
        "work_id": "123",
        "disable_status": "enable",
        "availability": true,
        "number": "100000000",
        "password": "xxxxxxxx",
        "avatar": null,
        "lang": "zh-cn",
        "tags": "タグ1,タグ2",
        "im_welcomes": null,
        "user_groups": [
        {
        "id": 1,
        "name": "テストグループ"
        }
        ],
        "agent_roles": [
        {
        "id": 11,
        "name": "サポート"
        }
        ],
        "departments": [
        {
        "id": 1,
        "name": "サポートグループ1"
        }
        ],
        "agent_callout_display_number": "100000000"
    }
}

サポート担当者の作成

このAPIはサポート担当者を作成するために使用されます。

リクエストメソッド

POST /agents

リクエストパラメータ(request body)

パラメータ名 タイプ 必須 説明 制限
agent オブジェクト はい サポート担当者情報、詳細は以下を参照

agentの構造

パラメータ名 タイプ 必須 説明 制限 デフォルト値
email 文字列 はい メールアドレス（アカウントとして使用） 255文字以内
password 文字列 はい パスワード 255文字以内
agent_role_ids 配列 はい ロールID（カンマ区切りの数字）、配列の最大長は10
user_group_ids 配列 はい 従業員グループID（カンマ区切りの数字）、配列の最大長は10
department_ids 配列 はい 部門ID（カンマ区切りの数字）、配列の最大長は10
im_ability_value 整数 はい チャットスキル値
nick_name 文字列 いいえ 氏名 255文字以内 null
aliase 文字列 いいえ ニックネーム 255文字以内 null
cellphone 文字列 いいえ 電話番号 255文字以内 null
profile 文字列 いいえ 従業員タイプ 255文字以内 im
duty 文字列 いいえ 役職 255文字以内 null
im_welcomes 文字列 いいえ ウェルカムメッセージ null
availability ブール値 いいえ 自動チケット割り当てを受け入れるかどうか true
avatar 文字列 いいえ アバターURL null
work_id 文字列 いいえ 従業員番号 null
callout_number_id 整数 いいえ 発信者番号表示ID null
lang 文字列 いいえ 言語設定 null

注意：

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します
agent_id 整数 新規作成されたカスタマーサポートID

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/agents?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 '
{
    "agent":{
        "email": "agent_001@udesk.cn",
        "password": "agent12345",
        "nick_name": "agent_001",
        "aliase": "agent_001",
        "cellphone": "13123456789",
        "profile": "all",
        "agent_role_ids": [1,2],
        "user_group_ids": [2],
        "im_ability_value": 1,
        "department_ids": [1,3],
        "duty": "部門マネージャー",
        "im_welcomes": "こんにちは",
        "availability": false,
        "avatar": "http://attachments.gfan.com/forum/attachments2/201302/03/11281446n2st1its4152n5.jpg",
        "lang": "en-us"
    }
}'

レスポンス

{
    "code": 1000,
    "agent_id": 1
}

カスタマーサポート情報の更新

このAPIは、既存のカスタマーサポートの基本情報を更新するために使用されます。

リクエスト

PUT agents/:id

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

パラメータ名 タイプ 必須 説明 制限
id 整数 はい カスタマーサポートID
with_disabled 文字列 いいえ 無効化されたカスタマーサポートを含めるかどうか

リクエストパラメータ(リクエストボディ)

パラメータ名 タイプ 必須 説明 制限
agent オブジェクト はい カスタマーサポート情報、詳細は以下を参照

agentの構造

パラメータ名 タイプ 必須 説明 制限
email 文字列 いいえ アカウント 255文字以内
password 文字列 いいえ パスワード 255文字以内
nick_name 文字列 いいえ 氏名 255文字以内
aliase 文字列 いいえ ニックネーム 255文字以内
cellphone 文字列 いいえ 電話番号 255文字以内
profile 文字列 いいえ 従業員タイプ、詳細は以下を参照 255文字以内
agent_role_ids 配列 いいえ ロールID
user_group_ids 配列 いいえ 従業員グループID
im_ability_value 整数 いいえ チャットスキル値
department_ids 配列 いいえ 部門ID
duty 文字列 いいえ 役職 255文字以内
im_welcomes 文字列 いいえ ウェルカムメッセージ
availability ブール値 いいえ 自動チケット割り当てを受け入れるかどうか
avatar 文字列 いいえ アバターURL
work_id 文字列 いいえ 従業員番号
disable_status 文字列 いいえ 有効または無効の状態 enable または disable
callout_number_id 整数 いいえ 発信者番号ID
lang 文字列 いいえ 言語設定

注意：リクエストパラメータにあるものだけを更新し、ないものは変更しません。

返却データ

属性名 タイプ 説明
code 整数型 実行結果コード、1000は成功を表します
agent オブジェクト 詳細は以下を参照

agentの構造

属性名 タイプ 説明
id 整数型 カスタマーサポートID
email 文字列 アカウント
nick_name 文字列 氏名
aliase 文字列 ニックネーム
cellphone 文字列 電話番号
profile 文字列 従業員タイプ
agent_roles 配列 ロール
user_groups 配列 従業員グループ
im_ability_value 整数型 チャットスキル値
departments 配列 部門
duty 文字列 役職
im_welcomes 文字列 ウェルカムメッセージ
availability ブール値 自動チケット割り当てを受け入れるかどうか
avatar 文字列 アバターURL
lang 文字列 言語設定
agent_callout_display_number 文字列 発信者番号表示
disable_status 文字列 有効または無効の状態
work_id 文字列 従業員番号
number 文字列 IP電話番号
password 文字列 IPデスク電話パスワード

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/agents/1?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 '{
    "agent":{
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "all",
        "work_id": null,
        "disable_status": "enable",
        "number": "97425540622337",
        "password": "6ab7d5b8d8472241
        "agent_role_ids" :[1,4],
        "user_group_ids" :[2],
        "im_ability_value" : 1,
        "department_ids" :[1,3],
        "duty": "業務マネージャー",
        "im_welcomes": "",
        "availability": true,
        "avatar": ""
    }
}'

レスポンス

{
    "code": 1000,
    "agent":{
        "id": 1,
        "email": "agent_0010@udesk.cn",
        "nick_name": "agent_0010",
        "aliase": "agent_0010",
        "cellphone": "15834234893",
        "profile": "all",
        "agent_roles": [{"id":1,"name":"ロール1"}, {"id":4,"name":"ロール4"}],
        "user_groups": [{"id":2,"name":"カスタマーサポートグループ1"}],
        "im_ability_value": 1,
        "departments": [{"id":1,"name":"部門1"}, {"id":3,"name":"部門3"}],
        "duty": "業務マネージャー",
        "im_welcomes": "",
        "availability": true,
        "lang": "zh-cn",
        "avatar": "",
        "work_id": "1231",
        "disable_status": "enable",
        "number": "98151643491111",
        "password": "23fece86b5841f17"
    }
}

エージェント削除

このAPIは、指定されたエージェントを削除するために使用されます。

リクエスト

DELETE agents/:id

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

パラメータ名 タイプ 必須 説明 制限
id 整数 はい エージェントID

リクエストパラメータ(request body)

パラメータ名 タイプ 必須 説明 制限
owner_group_id 整数 はい エージェントグループID
owner_id 整数 いいえ エージェントID

注意: エージェントを削除すると、このエージェントが担当していた顧客は他のエージェントグループ/エージェントに移管されます。リクエストで渡されるowner_idはowner_group_id内に存在する必要があります。 リクエストにowner_group_idとowner_idのパラメータがない場合、削除されるエージェントが担当していた顧客の担当者/担当グループは空になります。 リクエストのowner_group_idパラメータが空の場合、削除されるエージェントが担当していた顧客の担当者/担当グループは空になります。

レスポンスデータ

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

例

リクエスト

curl https://demo.udesk.cn/open_api_v1/agents/1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X DELETE \
-H 'content-type: application/json' \

レスポンス

{
    "code": 1000,
    "message": "IDが1のエージェントの削除に成功しました"
}

ロールリストの取得

このAPIは、現在の企業のロールリスト情報を取得するために使用されます。

リクエストメソッド

GET /agent_roles

リクエストパラメータ

なし

レスポンスデータ

属性名 タイプ 説明
code 整数 実行結果コード、1000は成功を表します
agent_roles 配列 詳細は以下を参照

agent_rolesの構造

パラメータ名 タイプ 説明
id 整数 ロールID
name 文字列 ロール名
description 文字列 ロールの説明
### サンプル

リクエスト

curl https://demo.udesk.cn/open_api_v1/agent_roles?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X GET \
-H 'content-type: appliacation/json' \

レスポンス

{
    "code": 1000,
    "agent_roles": [
        {"id": 1, "name": "ロール1", "description": ""},
        {"id": 2, "name": "ロール2", "description": ""},
        {"id": 3, "name": "ロール3", "description": ""}
    ]
}

codeエラーコード説明

エラーコード message情報 exception:message情報 説明
2000 このリソースは存在しません。入力パラメータを確認してください 無 カスタムフィールドを必須に設定した場合、パラメータ{custom_fields}が未入力または要件を満たしていません
XXXは必須項目です,XXXは必須項目です 無 必須パラメータ{XXX}が未入力です
この権限を従業員タイプに付与できません 無 パラメータ{profile}が未入力です
メールアドレスは既に使用されています 無 パラメータ{email}は既に使用されています
callout_number_idの値が無効です 無 パラメータ{callout_number_id}が有効範囲内にありません
現在のタイプの従業員が上限に達しました 無 パラメータ{profile}に対応するカスタマーサポートの数が、現在の会社で設定可能な上限に達しました
検証失敗: パスワードはメールアドレスと異なる必要があります 無 パラメータ{password}とパラメータ{email}が同じです
このカスタマーサポートは担当する顧客がいるため、削除できません 無 パラメータ{id}に対応するカスタマーサポートに担当するチケット及び顧客が存在します
不明なエラー param is missing or the value is empty: agent 必須パラメータ{agent}が未入力です
comparison of Fixnum with nil failed 入力されたパラメータが有効範囲内にないか、データが見つかりません
2005 このリソースは存在しません。入力パラメータを確認してください 無 パラメータ{type}及び{content}に一致するデータが見つかりません
このリソースが見つかりません 無 リクエストパラメータ{id}が誤っており、一致するデータが見つかりません
11006 無 無 この従業員はIMがオンラインのため、更新できません
11007 無 無 この従業員には閉じていないIMセッションがあるため、更新できません