查看历史版本

鉴权方法

除了获取api_token接口之外，其他接口皆需鉴权。

• 1、获取open_api_token 详见“登录接口”文档

• 2、计算签名，需要三个参数查看历史版本

  • email 管理员的email地址
  • timestamp 从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数，即UNIX时间戳
  • open_api_token 公司api_token 待签名字符串 sign_str = email&open_api_token&timestamp 签名 sign = Digest::SHA1.hexdigest(sign_str)

• 3、鉴权 请求时在URL的参数中加上email、timestamp和sign

签名及请求示例

#以udeskdemo作为签名示例
email = "udeskdemo@udesk.cn"
open_api_token = "6208398e-4838-425a-b6c3-45c0aa3a4d4d"
timestamp = "1488337316"
sign_str = email + "&" + open_api_token + "&" + timestamp
#sign_str = "udeskdemo@udesk.cn&ff6c83a2-78ce-4944-b0a8-c064d89af1e6&1488337316"
sign = Digest::SHA1.hexdigest(sign_str)
#sign = "6b18e26ae0176a1b281b62d0a4fc568913d6f059"

#请求示例
curl -X GET https://udeskdemo0405.udesk.cn/open_api_v1/agents?email=udeskdemo@udesk.cn&timestamp=1488337316&sign=6b18e26ae0176a1b281b62d0a4fc568913d6f059

//返回结果示例
{"code":1000,"agents":[{"id":3,"email":"agent2@udesk.cn","nick_name":"Jerry","profile":"im","aliase":null,"cellphone":null,"role_name":"agent","duty":null,"user_group_ids":[],"im_ability_value":1},{"id":2,"email":"agent@udesk.cn","nick_name":"Tom","profile":"im","aliase":null,"cellphone":null,"role_name":"agent","duty":null,"user_group_ids":[],"im_ability_value":3}],"meta":{"current_page":1,"total_pages":1,"count":2}}

配置通知地址

查看详情

开放api说明文档

• 接口调用频次限制 皆为1次/秒
• 调用要求 只能在服务端调用，禁止在客户端调用
• 关于自定义字段的说明和使用方式请参见 自定义字段说明
• 所有的接口调用之前请鉴权，鉴权方式参考“鉴权说明.md”

新建客户

请求地址

URL: 'https://yourdomain.udesk.cn/open_api_v1/customers/' METHOD: POST

请求参数说明

customer:
  email: 邮箱，String
  nick_name: 昵称，String
  description: 描述，String
  organization_id:  公司ID，Integer
  owner_id: 负责客户id，Integer
  owner_group_id: 负责组id，Integer
  level: 等级，传"normal"或者"vip"
  cellphones: |
    手机号，格式如下：
    [
      [ null, "13651190000" ],
      [ null, "13651191111" ],
      [ null, "13651192222" ]
    ]
  custom_fields: {
    SelectField_1: ["0", "1"],
    TextField_2: "string"
  }
tags: 标签，String,多个标签以逗号分隔
other_emails: |
  其他邮箱，格式如下：
  [
    [null, "111@email.com"],
    [null, "222@email.com"],
    [null, "333@email.com"]
  ]

返回字段说明

code: 编码-返回结果状态
customer: 新建的客户信息
  id: 客户id
  nick_name: 客户名字
  email: 客户主邮箱
  other_emails: 客户其它邮箱
    id: 邮箱id
    content: 邮箱地址
  level: 等级
  description: 描述
  tags: 标签
    id: tag id
    name: tag名字
    company_id: 公司id
  owner_id: 负责人id
  owner_group_id: 负责组id
  custom_fields: 自定义字段
  open_api_token: 开放api_token
  organization: 公司
    id: 公司id
    name: 公司名字
    domains: 公司域名
    created_at: 创建时间
    custom_fields: 自定义字段
    description: 描述
    customer_count: 客户数量
  cellphones: 客户电话数组
    id: 电话号码id
    content: 电话号码
  wechat:
    id: 微信open_id
    name: 微信公众号名字
  weibo:
    id: weibo open_id
    name: weibo公众号名字

请求示例:

{
    "customer": {
        "email": "23432@wre.com",
        "nick_name": "试试",
        "cellphones": [
            [
                null, "13466666655"
            ],
            [
                null, "13567891234"
            ]
        ],
        "organization_id": 1,
        "description": "米哦啊",
        "owner_id": 8,
        "owner_group_id": 15,
        "level": "vip"
    },
    "tags": "575675675, 张三,李四",
    "other_emails": [
        [
            null,
            "22343r@werr.com"
        ],
        [
            null,
            "23423553fg@fvgt.com"
        ]
    ],
    "email": "libai@udesk.cn",
    "timestamp": "1484647675",
    "sign": "2b8234815281755d4c92455a270530647dda7757"
}

返回结果示例

{
    "customer": {
        "id": 953803726,
        "nick_name": "试试",
        "emails": [
            "22343r@werr.com",
            "23423553fg@fvgt.com",
            "23432@wre.com"
        ],
        "level": "vip",
        "description": "米哦啊",
        "tags": [
            {
                "id": 1018350800,
                "name": "575675675",
                "company_id": 322593755,
                "taggings_count": 1
            }
        ],
        "owner_id": 8,
        "owner_group_id": 15,
        "custom_fields": {},
        "open_api_token": null,
        "organization": {
            "id": 1,
            "name": "two_org",
            "domains": "udesk.cn",
            "created_at": "2017-01-18T10:14:41.000+08:00",
            "custom_fields": {},
            "description": "the second one",
            "customer_count": 1
        },
        "cellphones": [
            {
                "id": 123,
                "content": "13466666655"
            },
            {
                "id": 1234,
                "content": "13567891234"
            }
        ],
        "wechat": [
            {
                "id": "wx477a73a96df0fa6e",
                "name": "miller"
            },
            {
                "id": "wxefd8044562c8661b",
                "name": "wz"
            }
        ],
        "weibo": []
    }
}

删除客户

• URL https://yourdomain.udesk.cn/open_api_v1/customers/destroy_customer
• METHOD DELETE

请求参数

type: 类型
content: 类型id

返回字段说明

code: 编码，返回结果状态
customer_id: 删除的客户id

请求示例

{
  "content":1,
  "type":"id",
  "email":"libai@udesk.cn",
  "timestamp":"1484647675",
  "sign":"2b8234815281755d4c92455a270530647dda7757"
}

返回结果示例

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

更新客户

请求地址

• URL https://yourdomain.udesk.cn/open_api_v1/customers/update_customer
• METHOD PUT

请求参数说明

type: "id", "email", "cellphone", "token", "weixin_open_id", "weibo_id",六种选一个，用来查找客户
content: type的数值
customer:
  email: 邮箱，String
  nick_name: 昵称，String
  description: 描述，String
  organization_id:  公司ID，Integer
  is_blocked: 是否在黑名单里
  owner_id: 负责客户id，Integer
  owner_group_id: 负责组id，Integer
  level: 等级，普通或者VIP
  custom_fields: 自定义字段
  {
    SelectField_1: ["0", "1"],
    TextField_2: "string"
  }
  tags: 标签，String,多个标签以逗号分隔
other_emails:
  其他邮箱，格式如下：
  [
    [1, "111@email.com"],
    [234, "222@email.com"],
    [null, "333@email.com"]
  ]
cellphones:
  手机号，格式如下：
  [
    [ 12: "13651190000" ],
    [ null, "13651191111" ],
    [ 23: null ]
  ]

返回字段说明

code: 编码-返回结果状态
customer: 新建的客户信息
  id: 客户id
  nick_name: 客户名字
  emails: 客户邮箱
  other_emails: 客户其它邮箱
    content: 内容
    id: 内容的id
  level: 等级
  description: 描述
  tags:
    id: tag id
    name: tag名字
    company_id: 公司id
  owner_id: 负责人id
  owner_group_id: 负责组id
  custom_fields: 自定义字段
  open_api_token: 开放api_token
  organization:
    id: 公司id
    name: 公司名字
    domains: 公司域名
    created_at: 创建时间
    custom_fields: 自定义字段
    description: 描述
    customer_count: 客户数量
  cellphones: 客户电话数组
    id: 电话id
    content: 电话号码
  wechat:
    id: 微信open_id
    name: 微信公众号名字
  weibo:
    id: weibo open_id
    name: weibo公众号名字

请求示例:

{"customer":
  {"email":"23432@wre.com",
   "nick_name":"试试",
   "cellphones":
     [[846, 13311114555],
     [847, 13455667789],
     [848, ""]],
   "organization_id":1,
   "description":"米哦啊",
   "owner_id":8,
   "owner_group_id":15,
   "level":"vip"},
   "tags":"575675675, 张三,李四",
   "other_emails":[[34, "22343r@werr.com"], [233, "23423553fg@fvgt.com"]],
   "content":1,
   "type":"id",
   "email":"libai@udesk.cn",
   "timestamp":"1484647675",
   "sign":"2b8234815281755d4c92455a270530647dda7757"}

手机号参数格式: [[id, content], [null, content], ...]
处理方法:
id 对应的手机号存在时, 如果其content于参数中content不一致, 则更新;
id 为空时, 为当前客户创建新的手机号;
如果id存在而content为null，则删除这个id所代表的手机号

邮箱参数格式: [[id, content], [null, content], ...]
处理方法:
id 对应的email存在时, 如果其content与参数中content不一致, 则更新;
id 为空时,为当前客户创建新的 ContactEmail;
当前客户emails中某个email的id在参数中不存在时,删除该email.

返回结果示例

"customer":
  {"id":953803726,
   "nick_name":"试试",
   "email":"22343r@werr.com",
   "other_emails":[233, "23423553fg@fvgt.com", 34, "23432@wre.com"],
   "level":"vip",
   "description":"米哦啊",
   "tags": [{"id":1018350800,"name":"575675675","company_id":322593755,"taggings_count":1}],
   "owner_id":8,
   "owner_group_id":15,
   "custom_fields":{},
   "open_api_token":null,
   "organization":{
     "id":1,
     "name":"two_org",
     "domains":"udesk.cn",
     "created_at":"2017-01-18T10:14:41.000+08:00",
     "custom_fields":{},
     "description":"the second one",
     "customer_count":1},
   "cellphones":[{"id":"123", "content":"13466666655"},{"id":323, "content":"13567891234"],
   "wechat":[{"id":"wx477a73a96df0fa6e", "name":"miller"}, {"id":"wxefd8044562c8661b", "name":"wz"}],
   "weibo":[]}}

获取客户说明

获取客户有六种渠道：ID，邮箱，电话，token，微信openID，微博openID，其中token是该客户在外部系统的唯一身份标识符。 获取客户传参方式： 1. type, 标识符的类别，传字符串，有以下下面6种 1. "id": 客户id 2. "email": 客户邮箱 3. "cellphone": 手机号 4. "token": 外部系统的身份标识符 5. "weixin_open_id": 微信openID 6. "weibo_id": weibo_id 2. content, 标识符的内容

获取客户列表

• URL https://yourdomain.udesk.cn/open_api_v1/customers
• METHOD GET

请求参数

filter_id: 过滤器id，整数，可选
query: 查询字符串，用于筛选客户，可选，详细说明见下文
page: 页数，可选
page_size: 每页多少条，可选

参数说明： filter_id是过滤器id，传过滤器id后，接口会返回符合过滤器条件的客户集，按照创建时间倒序排序。 query是查询字符串，传query之后，邮箱，手机号，公司，标签是query的客户集会被返回，在昵称中包含query的客户集会被返回，按照创建时间倒序排序。 如果传了过滤器id，则查询字符串会被忽略

请求示例

https://yourdomain.udesk.cn/open_api_v1/customers?filter_id=1&timestamp=12345678&sign=2235aeb34&email=123@sina.com&open_api_token=24353&page=1&page_size=20

返回结果

code: 结果状态码
meta: 数据信息
  current_page: 当前页数
  total_pages: 总页数
  total_count: 记录总数量
customers: 数组，返回每个客户的详情，其字段与“客户详情”文档中描述一致

返回结果示例

{
  "code":1000,
  "meta":{
    "current_page":1,
    "total_pages":1,
    "total_count":6
  },
  "wechat":[{"id":"wx477a73a96df0fa6e", "name":"miller"}, {"id":"wxefd8044562c8661b", "name":"wz"}],
  "weibo":[],
  "customers":[
   {
   "id":953803726,
   "nick_name":"试试",
   "emails":"22343r@werr.com",
   "other_emails":[{"id":123, "content": "23423553fg@fvgt.com"},{"id":234,"content": "23432@wre.com"}],
   "level":"vip",
   "description":"米哦啊",
   "tags": [{"id":1018350800,"name":"575675675","company_id":322593755}],
   "owner_id":8,
   "owner_group_id":15,
   "custom_fields":{},
   "open_api_token":null,
   "organization_id":1,
   "cellphones":[{"id":343, "content":"13466666655","id":234,"content": "13567891234"}]},
  {"id":123,
   "nick_name":"加试试",
   "emails":["22343r@werr.com", "23423553fg@fvgt.com", "23432@wre.com"],
   "level":"vip",
   "description":"米哦啊",
   "tags": [{"id":1018350800,"name":"575675675","company_id":322593755}],
   "owner_id":8,
   "owner_group_id":15,
   "custom_fields":{},
   "open_api_token":null,
   "organization_id":1,
   "weixin_id": 123,
   "weibo_id": 435,
   "cellphones":["13466666655", "13567891234"]
   }
   ]
   }

获取客户详情

请求地址

• URL https://yourdomain.udesk.cn/open_api_v1/customers/get_customer
• METHOD GET

请求参数说明

type: "id", "email", "cellphone", "token", "weixin_open_id", "weibo_id",六种选一个，用来查找客户
content: type的数值

返回字段说明

code: 结果状态码
customer: 新建的客户信息
  id: 客户id
  nick_name: 昵称
  emails: 客户主邮箱
  other_emails: 客户其它邮箱
    content: email内容
    id: email的id
  level: 等级
  is_blocked: 是否在黑名单里
  description: 描述
  tags:
    id: tag id
    name: tag名字
    company_id: 公司id
  owner_id: 负责人id
  owner_group_id: 负责组id
  custom_fields: 自定义字段
  open_api_token: 开放api_token
  organization:
    id: 公司id
    name: 公司名字
    domains: 公司域名
    created_at: 创建时间
    custom_fields: 自定义字段
    description: 描述
    customer_count: 客户数量
  cellphones: 客户电话数组
    id: 电话id
    content: 电话号码
  wechat_id: 微信open_id
  weibo_id: 微博open_id
  platform: 客户来源

请求示例

{
  "type":"id",
  "content":"234",
  "email":"libai@udesk.cn",
  "timestamp":"1484647675",
  "sign":"2b8234815281755d4c92455a270530647dda7757"
}

返回结果示例

"customer":
  {"id":953803726,
   "nick_name":"试试",
   "email":"22343r@werr.com",
   "other_emails":[233, "23423553fg@fvgt.com", 34, "23432@wre.com"],
   "level":"vip",
   "description":"米哦啊",
   "tags": [{"id":1018350800,"name":"575675675","company_id":322593755,"taggings_count":1}],
   "owner_id":8,
   "owner_group_id":15,
   "custom_fields":{},
   "open_api_token":null,
   "organization":{
     "id":1,
     "name":"two_org",
     "domains":"udesk.cn",
     "created_at":"2017-01-18T10:14:41.000+08:00",
     "custom_fields":{},
     "description":"the second one",
     "customer_count":1},
   "cellphones":[{"id":"123", "content":"13466666655"},{"id":323, "content":"13567891234"],
   "wechat_id": 123],
   "weibo_id":456}}

获取客户自定义字段

• URL https://yourdomain.udesk.cn/open_api_v1/customers/custom_fields
• METHOD GET
• 自定义字段说明

请求参数

• 无

请求示例

{
  "email":"libai@udesk.cn",
  "timestamp":"1484647675",
  "sign":"2b8234815281755d4c92455a270530647dda7757"
}

返回字段说明

code: 结果状态码
custom_fields: 客户自定义字段
  id: 自定义字段id
  agent_permission: 客服权限
  customer_permission: 客户权限
  custom_field_name: 字段名称
  title: 字段标题
  comment: 字段说明
  content_type: 字段类型
  options: （仅选择型自定义字段有此值）选项
  requirement: 是否必填

获取客户过滤器

• URL https://yourdomain.udesk.cn/open_api_v1/customers/filters
• METHOD GET

请求参数

• 无

请求示例

{
  "email":"libai@udesk.cn",
  "timestamp":"1484647675",
  "sign":"2b8234815281755d4c92455a270530647dda7757"
}

返回字段

code: 结果状态码
customer_filters:
  id: 过滤器id
  name: 过滤器名字
  active: true 为可用，false为不可用

返回结果示例

{"code":1000,
  "customer_filters":
  [{"id":202512130, "name":"ForWanglun", "active":true},
  {"id":628208182, "name":"test1", "active":true},
  {"id":1014555538, "name":"test", "active":true}]
  }

获取客户历史记录

• URL https://yourdomain.udesk.cn/open_api_v1/customers/feeds
• METHOD GET

请求参数说明:

字段	类型	必填	默认值	描述
content	string	是	无	唯一标识符内容
type	string	是	无	唯一标识符类型
page_size	integer	否	20	每页记录数量
page	integer	否	1	页数

返回结果说明：

code: 结果状态码
feeds: 客户json数组
  #工单
  id: id
  feed_type: 类型（Ticket）
  user_id: 负责人id
  user_group_id: 负责组id
  content: 描述
  subject: 主题
  status_zh_name: 状态
  #通话记录
  id: id
  feed_type: 类型（CallLog）
  call_type: 通话类型
  call_result: 通话结果
  duration: 通话时长
  #对话记录
  id: id
  from_type: 类型（ImSubSession）
  platform: 来源
  customer_msg_num: 客户消息数量
  agent_msg_num: 客服消息数量
  #变更记录
  id: id
  from_type: 类型（Alternation)
  time: 创建时间
  author: 作者
    id: 作者id
    nick_name: 作者名字
  summary: 变更摘要
  #客户跟进记录
  id: id
  from_type: 类型（CustomerFollowUp)
  user_id: 顾客id
  content: 内容
  agent_name: 客服名字

meta: 分页信息
  current_page: 当前页
  total_pages: 总页数
  total_count: 数据记录总数

请求示例：

http://yourdomain.udesk.cn/open_api_v1/customers/feeds?content=2&page_size=2&type=id&email=admin@udesk.cn&password=password&timestamp=2b8234815281755d4c92455a270530647dda7757&sign=2ddd83971d5c2f032e2ba22f0cfa079836b972e5&page=1

返回示例：

{
  "code": 1000,
  "feeds": [
    {
      "feed_type": "Alteration",
      "id": 35,
      "time": "2017-02-08T09:38:33.000+08:00",
      "author": {
        "id": 1,
        "nick_name": "Alex"
      },
      "summary": "将负责组设置为“默认组”"
    },
    {
      "feed_type": "Alteration",
      "id": 32,
      "time": "2017-01-24T11:18:11.000+08:00",
      "author": {
        "id": 1,
        "nick_name": "Alex"
      },
      "summary": "将负责人从“Tom”设置为 <空>"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 13,
    "total_count": 26
  }
}

批量新建客户

• URL: 'https://yourdomain.udesk.cn/open_api_v1/customers/batch_import_async'

• METHOD: POST

• 注意：这个功能是异步的，每次最多导入100个客户，将公司信息导入后，会返回结果状态码，如果为1000，则表示正在处理中。在处理完毕后，如果你配置了通知地址，则我们的后台会执行一个回调，给你配置的地址发送通知。配置通知地址详见“配置通知地址.md”；如果没有配置通知地址，那么你将得不到返回信息。

请求参数说明

customers:
  emails: 邮箱，String类型数组
  cellphones: 手机号，String类型数组
  nick_name: 昵称，String
  description: 描述，String
  organization_id:  公司ID，Integer
  owner_id: 负责客户id，Integer
  owner_group_id: 负责组id，Integer
  level: 等级，传"normal"或者"vip"
  custom_fields: Hash，{
    SelectField_1: ["0", "1"],
    TextField_2: "string"
  }
  tags: 标签，String,多个标签以逗号分隔

请求参数示例

{
    "customers": [
    {
        "emails": ["23432@wre.com","http@baidu.com"],
        "nick_name": "和路雪",
        "cellphones": ["13466666655","13567891234"],
        "organization_id": 1,
        "description": "东北大板",
        "owner_id": 8,
        "owner_group_id": 15,
        "level": "vip",
        "tags": "575675675, 张三,李四"
    },
    {
        "emails": ["23432@w.com","http@caidu.com"],
        "nick_name": "试试",
        "cellphones": ["1346666644","13507891234"],
        "organization_id": 1,
        "description": "蓝宝石",
        "owner_id": 8,
        "owner_group_id": 15,
        "level": "vip",
        "tags": "王老师，张老师，李老师"
    }
    ],
    "email": "libai@udesk.cn",
    "timestamp": "1484647675",
    "sign": "2b8234815281755d4c92455a270530647dda7757"
}

返回参数说明

code: 结果状态码

返回结果示例

{ "code": 1000 }

推送错误消息数据格式

errors: 错误信息,数组，格式为[[index, message], [index, message]]，其中index是导入客户的在数组中的索引，message为错误信息。例如[[0,"标签格式不对！"], [15, "未知错误"]]
success_count: 成功数量
failed_count: 失败数量