Desk API 文档

简介

Zoho Desk API 遵循 RESTful 原则,从而便于与其他 Zoho 应用和第三方工具集成。这些 API 使您能够以编程方式在 Zoho Desk 的不同模块(例如“工单”、“联系人”、“客户”等)中提取和编辑数据。所有 API 都遵循 HTTP 规则和错误码。为了使您了解我们 API 的最新更改,请关注 Zoho Desk Developer APIs 论坛。


API 根端点

https://desk.zoho.com/api/v1

开始使用

所有 Zoho Desk API 都需要标头中的以下两个必填字段。

  1. Authorization - 验证请求令牌
  2. orgId - 要访问的机构的 ID。所有 API 端点(/organizations 除外)都强制需要机构 ID。

示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

HTTP 方法

Zoho Desk API 通过各种 HTTP 方法来启用数据处理和检索。



方法目的
GET检索资源
POST创建资源并执行资源操作
PUT更新资源
PATCH部分更新资源
DELETE删除资源




通过使用 GET 方法,您可获取资源列表或某个资源的特定实例的详细信息。
要获取工单列表:

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

要获取指定的 ticket_id 所表示的工单的详细信息:

$ curl -X GET https://desk.zoho.com/api/v1/tickets/903000000000099
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

错误

Zoho Desk 使用 HTTP 状态码来指示 API 调用是成功还是失败。2xx 范围内的状态码指示成功,4xx 范围指示所提供的信息错误,而 5xx 范围指示服务器端错误。下表列出了一些常用的 HTTP 状态码。

HTTP 状态码

状态码描述
200 正常
201 已创建
204 无内容
400 错误请求
401 未授权
403 已禁止(未授权的访问)
404 URL 未找到
405 不允许使用此方法(所调用的 API 不支持所调用的方法)
413 有效负载太大
415 媒体类型不受支持
422 无法处理的实体
429 太多请求
500 内部错误


OAuth 错误

如果访问令牌已到期,您将会看到以下示例中显示的错误消息。

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/700000007942
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60"


响应示例

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8


OAuth 错误响应

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8


Include

Zoho Desk 使您能够通过单个 API 请求来检索不同的相关资源,这是通过 include 查询参数变为可能的。此查询参数接受与 API 对应的值列表(各个值以逗号分隔)。

约定

  1. 请始终忽略 API 响应中出现的未记录的字段或枚举值。这些字段可能是试验或不推荐使用的字段。
  2. 工单、联系人、客户、任务等中的数据字段是动态的。这是由于对用户简档应用了安全字段过滤。因此,在使用来自这些 API 的数据进行编码时,请始终将它们视为动态的。

兼容性

始终维护 API 更改的向后兼容性。较小的 API 更改(比如字段、URL、查询参数不推荐使用)将通过论坛进行通知,并且有一个过渡期。过渡期结束后,将会撤销支持。只有重大的 API 界面更改才会涉及 URL 中的版本号更改。

验证

可通过下列其中一种方法来验证 Zoho Desk 的 API:

  • 验证令牌(已不推荐使用)
  • OAuth 令牌

验证令牌(已不推荐使用)

您可通过下列其中一种方式获取验证令牌:

  1. 浏览器方法
  2. API 方法

浏览器方法

使用浏览器来获取验证令牌是一项简单的任务。您只需登录到您的 Zoho 账户并访问以下 URL。


https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSupport/supportapi,ZohoSearch/SearchAPI

API 方法

要使用 API 来获取验证令牌,请执行下列步骤:

将 HTTP POST 请求提交到以下 URL。


https://accounts.zoho.com/apiauthtoken/nb/create


在该 POST 请求的主体中,请包括以下格式的字符串。


?SCOPE=ZohoSupport/supportapi,ZohoSearch/SearchAPI&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]


下面是要在 URL 中传递的必填字段(区分大小写)。


参数要传递的值
SCOPEZohoSupport/supportapi
EMAIL_ID您的 Zoho ID 或电子邮件 ID
PASSWORD您的 Zoho 密码

使用验证令牌的请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-authtoken 67013ab3960787bcf3affae67e649fc0a789"


OAuth 令牌

Zoho Desk 的 API 使用行业标准 OAuth 2.0 协议进行验证和授权。此协议将用户验证委派给托管用户账户的服务,并授权第三方应用访问用户账户。每个 API 请求都必须包括 OAuth 令牌才能从 Zoho Desk 门户中检索任何资源。
要查看基于 Java 的 OAuth 库示例,请点击此处

获取 OAuth 令牌

要为您的应用获取 OAuth 令牌,请执行下列步骤:

1.注册应用

首先,在 Zoho 的开发者控制台(您可在此处访问)中注册您的应用。
成功注册后,您将会获得一个客户 ID 和一个客户密码。这些就是您的 OAuth 凭证。


2.获取授权

接下来,通过调用包含下表中列出的参数的授权 URI 来获取授权。请参阅示例以了解如何构造此授权 URI。


参数描述
client_id注册客户后生成的客户 ID。
response_type"code"
redirect_uri注册客户时提及的重定向 URI。
scope与 Zoho Desk 关联的各种作用域。
access_type"offline"/"online"。如果无法存储刷新令牌,请将 access_type 设置为 online 。默认值是 online
stateState 是一个不透明的值,由客户用来维护请求与回调之间的状态。

调用授权 URI 之后,将会打开“user-consent”页面。一旦用户接受,就会向 redirect_uri 发出 GET 请求,并在查询参数中追加授权代码。


3.获取访问令牌

最后一步是,调用以下格式的 URL,以便用 OAuth 令牌来交换授权代码(在上一步结束时已获得)。

参数描述
code生成授予令牌后获得的授权代码。
client_id注册客户后获得的客户 ID。
client_secret注册客户后获得的客户密码。
scope指定 Zoho Desk 所允许的作用域。
grant_type"authorization_code"
redirect_uri注册客户时提及的重定向 URI。
stateState 是一个不透明的值,由客户用来维护请求与回调之间的状态。在整个验证过程中,它必须保持不变。

调用 URL 后,将会向您提供访问令牌,您必须将其包括在所有 API 调用中。



通过刷新令牌生成访问令牌

访问令牌通常一小时后就到期,这意味着必须生成新的访问令牌才能使该过程继续下去。通过使用刷新令牌,您无需执行整个过程来生成访问令牌。在访问令牌到期后,可使用刷新令牌来生成新的访问令牌。

仅当在创建访问令牌时将 access_type 设置为 offline,才能获得刷新令牌。

请参阅示例以了解如何使用刷新令牌来获得访问令牌。


在 API 调用中使用 OAuth 令牌

要调用 Zoho Desk 的 API,请在标头的 Authorization 参数中传递访问令牌,如示例所示。



OAuth 作用域

下面是使用 Zoho Desk 的 API 可访问的各种作用域:

作用域名称描述

Desk.tickets.ALL

授予对工单和相关数据的读写访问权。

Desk.tickets.READ

授予对工单和相关数据的读访问权。

Desk.tickets.WRITE

授予对工单的写访问权。

Desk.tickets.UPDATE

授予对工单和相关数据的更新访问权。

Desk.tickets.CREATE

授予创建工单的访问权

Desk.tickets.DELETE

授予删除工单的访问权

Desk.contacts.READ

授予对联系人、客户和相关数据的读访问权

Desk.contacts.WRITE

授予对联系人、客户和相关数据的写访问权

Desk.contacts.UPDATE

授予对联系人、客户和相关数据的更新访问权

Desk.contacts.CREATE

授予创建联系人和客户的访问权

Desk.tasks.ALL

授予对任务和相关数据的读写访问权

Desk.tasks.WRITE

授予对任务和相关数据的写访问权

Desk.tasks.READ

授予对任务和相关数据的读访问权

Desk.tasks.CREATE

授予创建任务的访问权

Desk.tasks.UPDATE

授予对任务和相关数据的更新访问权

Desk.tasks.DELETE

授予删除任务的访问权

Desk.basic.READ

授予对基本数据(例如,机构、客服和部门)的读访问权

Desk.basic.CREATE

授予创建基本数据(例如,机构、客服和部门)的访问权

Desk.settings.ALL

授予对设置数据的读写访问权

Desk.settings.WRITE

授予对设置数据的写访问权

Desk.settings.READ

授予对设置数据的读访问权

Desk.settings.CREATE

授予创建新设置数据的访问权

Desk.settings.UPDATE

授予更新现有设置数据的访问权

Desk.settings.DELETE

授予删除设置数据的访问权

Desk.search.READ

授予搜索数据的访问权

成功响应示例

授权 URL

GET https://accounts.zoho.com/oauth/v2/auth

查询参数

?response_type=code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&state=-5466400890088961855


访问令牌 URL

POST https://accounts.zoho.com/oauth/v2/token

查询参数

?code=1000.fadbca4c2be2f08b0ce82a54f4313.ba5325853af6f12a0f160
&grant_type=authorization_code
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&redirect_uri=https://www.zylker.com/oauthgrant
&scope=Desk.tickets.READ,Desk.basic.READ


响应示例

使用刷新令牌生成访问令牌

POST https://accounts.zoho.com/oauth/v2/token

查询参数

?refresh_token=1000.dd7e67013ab396012e3d6eb1a9bc08.40bf11e7d0a1781ffec859e
&client_id=1000.R2Z0WWOLFVMR287126QED3B4JWQ5EN
&client_secret=39c689de68c712fa5f1f06c3b1319ab98f59fa921b
&scope=Desk.tickets.READ,Desk.basic.READ
&redirect_uri=https://www.zylker.com/oauthgrant
&grant_type=refresh_token

响应示例

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.67013ab3960787bcf3affae67e649fc0.83a789c859e040bf11e7d05f9c8b5ef6"

响应示例

HTTP/1.1 200 Ok
Content-Type: application/json;charset=UTF-8

机构

在 Zoho Desk 中,每个企业都分类为一个机构。如果您有多个企业,请通过创建新的注册并生成唯一的机构 ID,将每个企业设置为单个机构。除了与机构直接相关的 API 外,所有其他 API 都必须在标头中包括以下格式的机构 ID:orgId:{organization_id}

属性

属性名称
数据类型
描述
companyName

字符串

必需

机构/企业的实际公司名称

organizationName

字符串

必需

Zoho Desk 中显示的机构门户名称,它只能包含小写字母和数字

phoneNumber

字符串

必需

机构的电话号码

id

长整数

只读

机构的唯一 ID

isDefault

布尔型

只读

此字段返回机构是否是用户的默认机构

isAdminInOrg

布尔型

只读

此字段返回用户是否是机构管理员

portalURL

字符串

只读

机构的 URL

logoURL

字符串

只读

机构的徽标图片文件的 URL

示例

{ "isDefault" : false, "phoneNumber" : "9884358080", "organizationName" : "zohocorp", "companyName" : "zohoDesk", "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do", "id" : 3981311, "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true }



获取一个机构

此 API 从服务中心提取机构详细信息。

GET /api/v1/organizations/{organization_Id}

OAuth 作用域

Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/organizations/3981311
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "isDefault" : false, "phoneNumber" : "9884358080", "organizationName" : "zohocorp", "companyName" : "zohoDesk", "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do", "id" : 3981311, "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true }

获取所有机构

此 API 列出当前用户所属的全部机构

GET /api/v1/organizations

Oauth 作用域

Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/organizations
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "isDefault" : "false", "phoneNumber" : "9884358081", "organizationName" : "zohocorp", "companyName" : "zohoDesk", "portalURL" : "http://desk.zoho.com/support/zohocorp/ShowHomePage.do", "id" : "3981311", "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true }, { "isDefault" : "true", "phoneNumber" : "9884358080", "organizationName" : "zohotech", "companyName" : "zohoCrmPlus", "portalURL" : "http://desk.zoho.com/support/zohotech/ShowHomePage.do", "id" : "3981312", "logoURL" : "http://img.zohostatic.com/support/1284527/images/portalLogo.png", "isAdminInOrg" : true } ] }

工单

工单是服务客服用来在 Zoho Desk 中处理客户查询、请求、投诉和其他这种交互的组织单元。

属性

属性名称
数据类型
描述
id

长整数

只读

工单的 ID

subject

字符串

必需

工单主题

长整数

必需

工单所属的部门

引用的对象

必需

提交工单的联系人

productId

引用的对象

可选

工单所映射至的产品

列表

可选

附件列表,请参阅 uploads API 以创建附件

email

字符串

可选

工单中的电子邮件 ID

phone

字符串

可选

工单中的电话号码

description

字符串

可选

工单描述

status

字符串

可选

工单的状态。包括服务中心中存在的自定义状态。

statusType

字符串

只读

工单解决状态的类型。可能的值为 OpenClosed

assigneeId

长整数

可选

工单所分配至的客服的 ID

category

字符串

可选

工单类别

subCategory

字符串

可选

工单子类别

resolution

字符串

可选

工单的解决状态

dueDate

时间戳

可选

工单到期日

priority

字符串

可选

工单优先级

channel

字符串

可选

通过其发起工单的渠道。

classification

字符串

可选

工单分类

customFields

列表

可选

工单中的自定义字段

webUrl

字符串

可选

用于访问资源的 URL

createdTime

时间戳

只读

工单创建时间

modifiedTime

时间戳

只读

工单修改时间

timeEntryCount

整数

只读

与工单关联的时间条目数

approvalCount

整数

只读

与工单关联的审批数

commentCount

整数

只读

工单中的评论数

attachmentCount

整数

只读

工单中的附件数

taskCount

整数

只读

与工单关联的任务数

threadCount

整数

只读

与工单关联的会话数

isDeleted

布尔型

只读

此字段指示工单是否已删除

product

产品

只读

与工单关联的产品。您可以使用查询参数 include:product 获取此信息。

closedTime

时间戳

只读

工单关闭时间

ticketNumber

整数

只读

工单号

contact

联系人

只读

提交工单的联系人。您可以使用查询参数 include:contact 获取此信息

customerResponseTime

时间戳

只读

客户响应时间

sharedDepartments

列表

可选

已提供工单给其共享的部门的详细信息

示例

{ "modifiedTime" : "2016-06-21T13:16:14.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "resolution" : null, "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "contact" : { "lastName" : "Carol", "firstName" : "Lucas", "phone" : "1 888 900 9646", "id" : "1892000000042032", "type" : "paid", "email" : "carol@zylker.com", "account" : { "website" : "www.desk.com", "accountName" : "desk Account", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "product" : null, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "1", "category" : "general", "status" : "Open" }



获取工单

此 API 从工作台提取单个工单。

查询参数

参数名称
数据类型
描述

字符串

允许的值如下:contactsproducts。您可以将这两个值都包括在查询参数中,但必须用逗号进行分隔。

GET /api/v1/tickets/{ticket_id}

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000143237?include=contacts,products
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "modifiedTime" : "2016-06-21T13:16:14.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "resolution" : null, "closedTime" : null, "approvalCount" : "1", "timeEntryCount" : "3", "isDeleted" : "false", "contact" : { "lastName" : "Carol", "firstName" : "Lucas", "phone" : "1 888 900 9646", "id" : "1892000000042032", "type" : null, "email" : "carol@zylker.com", "account" : { "website" : "www.desk.com", "accountName" : "desk Account", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "product" : null, "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "1", "category" : "general", "status" : "Open" }

列出所有工单

此 API 列出服务中心中的所有工单。

查询参数

参数名称
数据类型
描述
from

整数

起始索引

limit

整数

要提取的工单数

长整数

需要从中查询工单的部门

assignee

字符串

按工单受托人过滤。允许的值为 Unassigned 或有效的 asigneeIds。您可以包括多个值,但必须用逗号进行分隔

channel

字符串

按通过其发起工单的渠道过滤。您可以包括多个值,但必须用逗号进行分隔

status

字符串

按工单的解决状态过滤。您可以包括多个值,但必须用逗号进行分隔

sortBy

字符串

按以下特定属性排序: dueDaterecentThread。默认排序顺序是升序。- 前缀表示升序排序顺序。

receivedInDays

整数

根据 customer response time 提取最近的工单。允许的值为 153090

字符串

允许的值如下:contactsproducts。您可以将这两个值都包括在查询参数中,但必须用逗号进行分隔。

GET /api/v1/tickets

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets?include=contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "ticketNumber" : "101", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "productId" : null, "contactId" : "1892000000042032", "subject" : "Real Time analysis Requirement", "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "threadCount" : "121", "priority" : "High", "assigneeId" : "1892000000056007", "closedTime" : null, "commentCount" : "1", "phone" : null, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "contact" : { "firstName" : "Lucas", "lastName" : "Carol", "phone" : "1 888 900 9646", "id" : "1892000000042032", "type" : null, "email" : "carol@zylker.com", "account" : { "website" : null, "accountName" : "desk Account", "id" : "1892000000975382" } }, "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "email" : "carol@zylker.com", "status" : "Open" }, { "ticketNumber" : "176", "customerResponseTime" : "2014-03-22T05:05:08.471Z", "statusType" : "Closed", "productId" : null, "contactId" : "1892000000045028", "subject" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "dueDate" : "2016-06-01T14:04:07.000Z", "departmentId" : "1892000000006907", "channel" : "Forums", "threadCount" : "72", "priority" : "High", "assigneeId" : "1892000000056007", "closedTime" : null, "commentCount" : "0", "phone" : null, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b02214oc203b38", "contact" : { "firstName" : "Jonathan", "lastName" : "Casie", "phone" : null, "id" : "1892000000045028", "type" : null, "email" : "casie@zylker.com", "account" : { "website" : "www.zylker.com", "accountName" : "Zylker sAccount", "id" : "1892000000980421" } }, "createdTime" : "2014-03-06T09:49:50.000Z", "id" : "1892000000094004", "email" : "casie@zylker.com", "status" : "Closed" }, { "ticketNumber" : "191", "customerResponseTime" : "2014-03-21T10:54:21.802Z", "statusType" : "Open", "productId" : null, "contactId" : "1892000000045028", "subject" : "Real Time analysis Requirement", "dueDate" : null, "departmentId" : "1892000000006907", "channel" : "Chat", "threadCount" : "19", "priority" : "High", "assigneeId" : "1892000000042001", "closedTime" : null, "commentCount" : "0", "phone" : null, "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d11bcdfb061247d9edbacb9d93ba74750b0284bc703b38", "contact" : { "firstName" : "Jonathan", "lastName" : "Casie", "phone" : null, "id" : "1892000000045028", "type" : null, "email" : "casie@zylker.com", "account" : { "website" : "www.zylker.com", "accountName" : "Zylker Account", "id" : "1892000000980421" } }, "createdTime" : "2014-03-21T09:16:03.000Z", "id" : "1892000000137057", "email" : "casie@zylker.com", "status" : "Open" } ] }

创建工单

此 API 在服务中心中创建一个工单。

POST /api/v1/tickets

OAuth 作用域

Desk.tickets.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"subCategory":"Sub General", "productId":"", "contactId":"1892000000042032", "subject":"Real Time analysis Requirement", "customFields":{"secondaryEmail": null, "ModelName":"F3 2017", "severityPercentage":"0.0", "phone": null, "numberOfItems": null, "dateofPurchase": null, "permanentAddress": null, "url": null }, "dueDate":"2016-06-21T16:16:16.000Z", "departmentId":"1892000000006907", "channel":"Email", "description":"Hai This is Description", "priority":"High", "classification":"", "assigneeId":"1892000000056007", "phone":"1 888 900 9646", "category":"general", "email":"carol@zylker.com", "status":"Open"}'

响应示例

{ "modifiedTime" : "2016-06-21T12:50:04.000Z", "ticketNumber" : "773", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T18:50:04.573Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hai This is description", "resolution" : null, "closedTime" : null, "approvalCount" : "0", "timeEntryCount" : "0", "isDeleted" : "false", "createdTime" : "2016-06-21T12:50:04.000Z", "id" : "1892000001054003", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "productId" : null, "contactId" : "1892000000042032", "threadCount" : "1", "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "0", "taskCount" : "0", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "0", "category" : "general", "status" : "Open" }

更新一个工单

此 API 更新一个现有的工单。

PATCH /api/v1/tickets/{ticket_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/3000000024409
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"subCategory":"Sub General", "productId":"", "contactId":"1892000000042032", "subject":"Real Time analysis Requirement", "customFields":{"secondaryEmail": null, "ModelName":"F3 2017", "severityPercentage":"0.0", "phone": null, "numberOfItems": null, "dateofPurchase": null, "permanentAddress": null, "url": null }, "dueDate":"2016-06-21T16:16:16.000Z", "departmentId":"1892000000006907", "channel":"Phone", "description":"Sample Ticket", "priority":"Low", "classification":"", "assigneeId":"1892000000056007", "phone":"1 888 900 9646", "category":"general", "email":"carol@zylker.com", "status":"Open"}'

响应示例

{ "modifiedTime" : "2016-06-21T12:58:09.122Z", "ticketNumber" : "773", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-23T12:58:09.211Z", "departmentId" : "1892000000006907", "channel" : "Phone", "description" : "Sample Ticket", "resolution" : null, "closedTime" : null, "approvalCount" : "0", "timeEntryCount" : "0", "isDeleted" : "false", "createdTime" : "2016-06-21T12:50:04.000Z", "id" : "1892000001054003", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "productId" : null, "contactId" : "1892000000042032", "threadCount" : "1", "priority" : "Low", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "0", "taskCount" : "0", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "0", "category" : "general", "status" : "Open" }

合并两个工单

此 API 合并两个不同的工单。

POST /api/v1/tickets/{ticket_id}/merge

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000008749/merge
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"ids":["4000000018011"], "source":{"contactId":"4000000018011", "subject":"4000000018011", "priority":"4000000018011", "status":"4000000018011"}}'

响应示例

{ "modifiedTime" : "2016-06-21T10:16:15.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "42000000006907", "channel" : "Email", "description" : "Real Time analysis Requirement", "resolution" : null, "closedTime" : null, "approvalCount" : "0", "timeEntryCount" : "3", "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "4000000008749", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "productId" : null, "contactId" : "42000000042032", "threadCount" : "121", "priority" : "High", "classification" : null, "assigneeId" : "42000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "1", "category" : "general", "status" : "Open" }

移动工单

此 API 将工单从一个部门移到另一个部门。

查询参数

参数名称
数据类型
描述

长整数

要将工单移至的部门的 ID

POST /api/v1/tickets/{ticket_id}/move

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000093303/move?departmentId=1892000000082069
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

拆分工单

此 API 将会话拆分成工单。

POST /api/v1/tickets/{ticket_id}/thread/{thread_id}/split

Oauth 作用域

Desk.tickets.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000047005/threads/1892000000133023/split
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "modifiedTime" : "2016-06-21T10:16:15.000Z", "ticketNumber" : "101", "subCategory" : "Sub General", "statusType" : "Open", "subject" : "Real Time analysis Requirement", "customFields" : { "secondaryEmail" : null, "ModelName" : "F3 2017", "severityPercentage" : "0.0", "phone" : null, "numberOfItems" : null, "dateofPurchase" : null, "permanentAddress" : null, "url" : null }, "dueDate" : "2016-06-21T16:16:16.000Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Real Time analysis Requirement", "resolution" : null, "closedTime" : null, "approvalCount" : "0", "timeEntryCount" : "3", "createdTime" : "2013-11-04T11:21:07.000Z", "id" : "1892000000042034", "email" : "carol@zylker.com", "customerResponseTime" : "2013-11-04T11:21:07.912Z", "productId" : null, "contactId" : "1892000000042032", "threadCount" : "121", "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "1", "taskCount" : "1", "phone" : "1 888 900 9646", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/d126330fb061247d9ebddaeb9d93ba74750b0284bc703b38", "attachmentCount" : "1", "category" : "general", "status" : "Open" }

更新多个工单

此 API 同时更新多个工单。

POST /api/v1/tickets/updateMany

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/updateMany
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"fieldName":"subject", "isCustomField": false, "ids":["1892000000093303", "1892000000085009", "1892000000050003"], "fieldValue":"Ticket for support"}'

响应示例

200

标记垃圾邮件

此 API 将工单标记为垃圾邮件。

POST /api/v1/tickets/markSpam

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/markSpam
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"ids":[ 1892000001021097 ], "isSpam":"true"}'

响应示例

200

会话

会话是指客服与客户之间进行的对话。一个会话可来源于多个渠道,例如 FACEBOOKTWITTEREMAILTWITTER_DMWEBONLINE_CHATOFFLINE_CHATFORUMSTWILIOZTICUSTOMERPORTALFEEDBACKFEEDBACK_WIDGET

属性

属性名称
数据类型
描述
id

长整数

只读

会话的 ID

channel

字符串

必需

通过其发起会话的渠道。允许的值为 FACEBOOKTWITTEREMAILFORUMS

status

字符串

只读

会话的状态。可能的值为 SUCCESSPENDINGFAILEDDRAFT

content

字符串

必需

会话的内容

contentType

字符串

可选

用于表示内容类型(仅当 channel 为 EMAIL 时才需要提供此属性),它可以是 htmlplainText。默认类型为 plainText

isForward

布尔型

可选

指示是否已转发会话数据,仅适用于: EMAIL

inReplyToThreadId

长整数

可选

此会话所回复的会话的 ID,仅适用于: EMAIL

列表

可选

附件 ID 列表,仅适用于 EMAIL。您可以通过以下项获取附件 ID: Uploads API

createdTime

时间戳

只读

会话创建时间

direction

字符串

可选

返回此会话是传入还是传出会话

object

只读

会话作者的详细信息。

fromEmailAddress
(请参阅文档)

字符串

可选

用于创建电子邮件会话的必需参数,仅适用于 EMAILONLINE_CHATOFFLINE_CHATCUSTOMERPORTALFORUMS

to

字符串

可选

会话中的目标 ID,仅适用于: EMAIL

cc

字符串

可选

抄送至的电子邮件 ID(如果有)仅适用于: EMAIL

bcc

字符串

可选

密送至的电子邮件 ID(如果有)仅适用于: EMAIL

phoneno

字符串

只读

通过其发起会话的电话号码,仅适用于 ZTITWILIO

summary

字符串

只读

会话摘要

attachments

object

只读

会话中的附件

hasAttach

布尔型

可选

指示会话是否具有附件

列表

只读

当前状态下可用的操作,将根据当前状态包括这些操作。这是所有操作的集合,并且每个操作都具有 rel、href 和 method。在每个操作的“href”和“method”关键字下提供了要调用的各自链接和方法。

示例

{ "hasAttach" : true, "summary" : "How was our Customer Service", "attachments" : [ { "size" : "1913", "name" : "ScreenShot", "id" : "1892000001083005", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/176276372673/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade@zylker.zohodesk.com" }, "channel" : "FORUMS", "createdTime" : "2016-03-21T08:46:48.248Z", "id" : "1892000000135387", "actions" : [ ], "content" : "How was our Customer Service ?", "status" : "SUCCESS", "direction" : "out" }



获取会话

此 API 从工作台提取单个会话。

GET /api/v1/tickets/{ticket_id}/threads/{thread_id}

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000094004/threads/1892000000135387
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "cc" : "", "summary" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation", "attachments" : [ { "size" : "1913", "name" : "ScreenShot", "id" : "1892000001083005", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "bcc" : "", "visibility" : "public", "author" : { "photoURL" : null, "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@gmail.com" }, "channel" : "EMAIL", "content" : "Please provide us with a valid solution within the suggested time frame so that we can proceed with the implementation", "isForward" : false, "hasAttach" : true, "createdTime" : "2016-06-02T18:17:55.000Z", "to" : "techsupport@zylker.zohodesk.com", "id" : "1892000000135387", "fromEmailAddress" : "jade12tywin@gmail.com", "actions" : [ ], "status" : "SUCCESS", "direction" : "in" }

列出所有会话

此 API 列出服务中心中的所有会话。

查询参数

参数名称
数据类型
描述
from

整数

会话的起始索引

limit

整数

要显示的案例中的会话数

GET /api/v1/tickets/{ticket_id}/threads

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/threads
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "hasAttach" : false, "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo", "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@gmail.com" }, "channel" : "FEEDBACK", "createdTime" : "2015-03-25T13:40:23.031Z", "id" : "1892000000413186", "fromEmailAddress" : "jade12tywin@gmail.com", "actions" : [ ], "status" : "SUCCESS", "direction" : "in" }, { "summary" : "Customer Rating", "cc" : "", "bcc" : "", "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" }, "channel" : "EMAIL", "isForward" : false, "hasAttach" : true, "responderId" : "1892000000042001", "createdTime" : "2016-05-25T10:06:09.686Z", "id" : "1892000001004072", "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "actions" : [ { "method" : "POST", "rel" : "send", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/resendFailedThread?threadId=1892000001083008" } ], "status" : "FAILED", "direction" : "out" }, { "hasAttach" : false, "summary" : "Please fix this problem, since it is urgent posted the issue on Facebook ", "responderId" : "2150000000043591", "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/2150000000043591/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" }, "channel" : "FACEBOOK", "createdTime" : "2016-07-25T10:04:43.739Z", "id" : "2150000002498038", "actions" : [ { "method" : "POST", "rel" : "send", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072" }, { "method" : "DELETE", "rel" : "delete", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072" } ], "status" : "DRAFT", "direction" : "out" }, { "hasAttach" : false, "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/user/176276372673/photo", "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@gmail.com" }, "channel" : "FEEDBACK", "createdTime" : "2015-03-25T13:40:23.031Z", "id" : "1892000000413189", "fromEmailAddress" : "jade12tywin@gmail.com", "actions" : [ ], "status" : "SUCCESS", "direction" : "in" } ] }

发送电子邮件回复

此 API 发送电子邮件回复。电子邮件的发件人地址必须是服务中心中配置的某个发件人地址。

POST /api/v1/tickets/{ticket_id}/sendReply

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/sendReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"channel":"EMAIL", "attachmentIds":["1312123141313"], "to":"carol@zoho.com", "fromEmailAddress":"techsupport@zylker.zohodesk.com", "contentType":"plainText", "content":"We have identified the root cause and fixed it.", "isForward":"true"}'

响应示例

{ "summary" : "We have identified the root cause and fixed it.", "cc" : "", "bcc" : "", "attachments" : [ { "size" : "818", "name" : "atach.png", "id" : "1892000000042043", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/176276372673/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@gmail.com" }, "channel" : "EMAIL", "content" : "We have identified the root cause and fixed it.", "isForward" : true, "hasAttach" : true, "responderId" : "1892000000042001", "createdTime" : "2016-05-25T10:06:09.686Z", "id" : "1892000001004072", "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "actions" : [ ], "status" : "PENDING", "direction" : "out" }

起草电子邮件回复

此 API 起草电子邮件回复。电子邮件的发件人地址必须是服务中心中配置的某个发件人地址。

POST /api/v1/tickets/{ticket_id}/draftReply

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d'{"channel":"EMAIL", "attachmentIds":["1312123141313"], "to":"carol@zoho.com", "fromEmailAddress":"techsupport@zylker.zohodesk.com", "contentType":"plainText", "content":"We have escaled the issue.Will update you regarding the progress.", "isForward":"true"}'

响应示例

{ "summary" : "We have escaled the issue.Will update you regarding the progress.", "cc" : "", "bcc" : "", "attachments" : [ { "size" : "324", "name" : "atach.png", "id" : "1892000000042043", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005/content" } ], "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" }, "channel" : "EMAIL", "content" : "We have escaled the issue.Will update you regarding the progress.", "isForward" : false, "hasAttach" : true, "responderId" : "1892000000042001", "createdTime" : "2016-05-25T10:06:09.686Z", "id" : "1892000001004072", "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "actions" : [ { "method" : "POST", "rel" : "send", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072" }, { "method" : "DELETE", "rel" : "delete", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072" } ], "status" : "DRAFT", "direction" : "out" }

更新草稿

此 API 更新草稿会话。“更新操作”仅适用于电子邮件、FACEBOOK 和论坛

PATCH /api/v1/tickets/{ticket_id}/draftReply/{thread_id}

Oauth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"channel":"EMAIL", "to":"carol@zoho.com", "fromEmailAddress":"techsupport@zylker.zohodesk.com", "contentType":"plainText", "content":"We are analysing the issue currently , will update you with a solution as early as possible"}'

响应示例

{ "summary" : "We are analysing the issue currently , will update you with a solution as early as possible", "cc" : "", "bcc" : "", "visibility" : "public", "author" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/1892000000042001/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" }, "channel" : "EMAIL", "content" : "We are analysing the issue currently , will update you with a solution as early as possible", "isForward" : false, "hasAttach" : false, "responderId" : "1892000000042001", "createdTime" : "2016-05-25T10:06:09.686Z", "id" : "1892000001004072", "to" : "carol@zoho.com", "fromEmailAddress" : "techsupport@zylker.zohodesk.com", "actions" : [ { "method" : "POST", "rel" : "send", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/sendDraft?draftThreadId=1892000001004072" }, { "method" : "DELETE", "rel" : "delete", "href" : "https://desk.zoho.com/api/v1/tickets/1892000000094004/draftReply/1892000001004072" } ], "status" : "DRAFT", "direction" : "out" }

删除附件

此 API 删除会话中的草稿附件。

DELETE /api/v1/tickets/{ticket_id}/threads/{thread_id}/attachments/{attachment_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000000093205/threads/1892000001083008/attachments/1892000001083005
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

工单评论

工单评论是主要在服务中心中的不同客服之间进行的与工单相关的对话。工单中标记为私有的评论仅对客服可见,而标记为公开的评论还将显示在客户门户上。

属性

属性名称
数据类型
描述
id

长整数

只读

评论的 ID

content

字符串

可选

评论的内容。要检索或设置用户提及,请使用以下代码格式:zsu[@user:{zuid}zsu.

isPublic

布尔型

可选

此属性返回评论是否为公开评论。只能在发表评论时设置此属性的值。

commenterId

字符串

只读

发表评论的用户的 ID

commentedTime

时间戳

只读

评论创建时间

modifiedTime

时间戳

只读

评论修改时间

commenter

object

只读

发表评论的用户的详细信息。

示例

{ "commentedTime" : "2014-11-28T10:25:13.000Z", "isPublic" : false, "id" : "1892000000366001", "content" : "This is a comment structure", "commenterId" : "1892000000042001", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo", "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }



创建工单评论

此 API 对工单添加评论。要包括 @提及,请采用以下格式:zsu[@user:{zuid}]zsu.

POST api/v1/tickets/{ticket_id}/comments

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"isPublic":"true", "attachmentIds":["4000000008892"], "content":"zsu[@user:11550965]zsu Please fix this ASAP"}'

响应示例

{ "modifiedTime" : null, "attachments" : [ { "size" : "12734", "name" : "Attachment.png", "id" : "4000000008892", "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008892/content" } ], "commentedTime" : "2017-01-24T14:06:58.193Z", "isPublic" : true, "id" : "4000000529001", "content" : "zsu[@user:11550965]zsu Please fix this ASAP", "commenterId" : "4000000008692", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" } }

更新工单评论

此 API 修改现有的评论。要包括 @提及,请采用以下格式:zsu[@user:{zuid}]zsu.

PATCH api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"attachmentIds":["4000000008994"], "content":"Edited comment."}'

响应示例

{ "modifiedTime" : "2017-01-24T14:12:45.163Z", "attachments" : [ { "size" : "12734", "name" : "Attachment_edited.png", "id" : "4000000008994", "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content" } ], "commentedTime" : "2017-01-24T14:06:58.000Z", "isPublic" : true, "id" : "4000000529001", "commenterId" : "4000000008692", "content" : "Fixed the issue.", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo", "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } }

删除工单评论

此 API 删除现有的评论。

DELETE api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

获取工单评论

此 API 从工单中提取评论。

GET api/v1/tickets/{ticket_id}/comments/{comment_id}

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "modifiedTime" : "2017-01-24T14:12:45.000Z", "attachments" : [ { "size" : "12734", "name" : "Attachment_edited.png", "id" : "4000000008994", "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content" } ], "commentedTime" : "2017-01-24T14:06:58.000Z", "isPublic" : true, "id" : "4000000529001", "commenterId" : "4000000008692", "content" : "Fixed the issue.", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" } }

列出所有工单评论

此 API 根据所指定的限制列出工单中记录的特定数目的评论。 

查询参数

参数名称
数据类型
描述
from

整数

必须从其开始提取评论的索引号

limit

整数

要提取的评论数

sortBy

字符串

commentedTime 属性排序。默认排序顺序是升序。- 前缀表示升序排序顺序。

GET api/v1/tickets/{ticket_id}/comments

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000528005/comments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "modifiedTime" : "2017-01-24T14:12:45.000Z", "attachments" : [ { "size" : "12734", "name" : "Attachment_edited.png", "id" : "4000000008994", "href" : "https://desk.zoho.com/api/v1/tickets/4000000528005/comments/4000000529001/attachments/4000000008994/content" } ], "commentedTime" : "2017-01-24T14:06:58.000Z", "isPublic" : true, "id" : "4000000529001", "content" : "Fixed the issue.", "commenterId" : "4000000008692", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/agent/4000000008692/photo", "name" : "Jade Tywin", "type" : "AGENT", "email" : "jade12tywin@zylker.com" } }, { "modifiedTime" : null, "commentedTime" : "2017-01-24T14:14:37.000Z", "isPublic" : false, "id" : "4000000529007", "content" : "zsu[@user:11550965]zsu Please fix this ASAP", "commenterId" : "4000000008692", "commenter" : { "photoURL" : "https://desk.zoho.com/api/v1/portalUser/4000000008692/photo", "name" : "Jade Tywin", "type" : "END_USER", "email" : "jade12tywin@zylker.com" } } ] }

工单附件

工单附件是您附加到工单以帮助快速解决的文件。

属性

属性名称
数据类型
描述
id

长整数

只读

附件的 ID

creatorId

长整数

只读

添加附件的用户的 ID

createdTime

时间戳

只读

文件附件的时间

name

字符串

只读

附件名称

isPublic

布尔型

只读

附件的可见性设置

size

长整数

只读

附件大小

示例

{ "size" : "1079", "creatorId" : "1892000000047001", "name" : "ScreenShot", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : true, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content" }



列出所有附件

此 API 列出工单中的所有附件。

查询参数

参数名称
数据类型
描述
sortBy

字符串

createdTime 属性排序。默认排序顺序是升序。- 前缀表示升序排序顺序。

from

整数

起始索引

limit

整数

要显示的附件数

isPublic

布尔型

获取公共、私有或所有附件

GET /api/v1/tickets/{ticket_id}/attachments

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "size" : "1079", "creatorId" : "1892000000047001", "name" : "issues.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : true, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000047041/content" }, { "size" : "135222", "creatorId" : "1892000000047001", "name" : "guidelines.pdf", "createdTime" : "2014-03-05T06:16:15.000Z", "isPublic" : true, "id" : "1892000000089041", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000000089041/content" }, { "size" : "97951", "creatorId" : "1892000000042001", "name" : "CreditHistory.pdf", "createdTime" : "2016-06-21T10:15:34.000Z", "isPublic" : false, "id" : "1892000001052021", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052021/content" }, { "size" : "97951", "creatorId" : "1892000000042001", "name" : "values.txt", "createdTime" : "2016-06-21T10:15:49.000Z", "isPublic" : false, "id" : "1892000001052025", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001052025/content" } ] }

创建附件

此 API 将文件附加到工单。

文件参数

file

Content-Type:multipart/form-data

要附加到工单的文件

POST /api/v1/tickets/{ticket_id}/attachments

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "size" : "32", "creatorId" : "1892000000042001", "name" : "issues.txt", "createdTime" : "2016-05-30T08:32:51.338Z", "isPublic" : false, "id" : "1892000001010001", "href" : "https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001/content" }

更新附件

此 API 更新现有的附件。

PATCH /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X PATCH https://desk .zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"isPublic": true }'

响应示例

200

删除附件

此 API 从工单中删除附件。

DELETE /api/v1/tickets/{ticket_id}/attachments/{attachment_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

工单时间条目

工单时间条目是指客服解决工单所用的时间。

属性

属性名称
数据类型
描述
id

长整数

只读

时间条目的 ID

ticketId

长整数

只读

工单的 ID

requestChargeType

字符串

可选

对时间条目的描述

ownerId

字符串

可选

时间条目的所有者

executedTime

时间戳

可选

执行时间

hoursSpent

整数

可选

处理工单所用的小时数

minutesSpent

整数

可选

处理工单所用的分钟数

secondsSpent

整数

可选

处理工单所用的秒数

agentCostPerHour

双精度型

可选

每小时的客服成本

additionalCost

双精度型

可选

所产生的附加成本

totalCost

双精度型

只读

所产生的总成本

description

字符串

可选

对时间条目的描述

customFields

列表

可选

时间条目中的自定义字段

createdTime

时间戳

只读

工单时间条目的创建时间

modifiedTime

时间戳

只读

工单时间条目的修改时间

createdBy

字符串

只读

创建时间条目的用户

modifiedBy

字符串

只读

修改时间条目的用户

示例

{ "secondsSpent" : "0", "executedTime" : null, "customFields" : { }, "minutesSpent" : "0", "creatorId" : "4000000008688", "agentCostPerHour" : null, "description" : "Time Entry description", "hoursSpent" : "2", "ownerId" : null, "createdTime" : "2016-05-30T09:58:08.149Z", "id" : "4000000033010", "requestChargeType" : "Product Consultation", "additionalCost" : null, "totalCost" : null }



Get a Ticket Time Entry

此 API 从服务中心提取时间条目

查询参数

参数名称
数据类型
描述

字符串

允许的值如下: owner

GET /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000033010?include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "owner" : { "photoURL" : "https://contacts.csez.zohocorpin.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "21", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time1" }, "minutesSpent" : "23", "creatorId" : "4000000008692", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "createdTime" : "2016-06-16T07:24:44.000Z", "id" : "4000000033001", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }

列出工单时间条目

此 API 提取所有与工单关联的时间条目

查询参数

参数名称
数据类型
描述
module

字符串

模块首选项。它可以是: tickets tasks

isBillable

布尔型

是否是可计费的首选项

from

整数

起始索引

limit

整数

要提取的时间条目数

orderBy

字符串

ASCDESC,默认情况下为 ASC(升序)顺序

字符串

允许的值如下: owner

GET /api/v1/tickets/{ticket_id}/timeEntry

OAuth 作用域

Desk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry?from=0&limit=10&include=owner
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "owner" : { "photoURL" : "https://contacts.csez.zohocorpin.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "21", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time1" }, "minutesSpent" : "23", "creatorId" : "4000000008692", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "createdTime" : "2016-06-16T07:24:44.000Z", "id" : "4000000033001", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }, { "owner" : { "photoURL" : "https://contacts.csez.zohocorpin.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "21", "executedTime" : "2016-06-24T19:30:00.000Z", "customFields" : { "timeEntryName" : "time2" }, "minutesSpent" : "34", "creatorId" : "4000000008692", "agentCostPerHour" : "10.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000012090", "createdTime" : "2016-06-16T07:46:39.000Z", "id" : "4000000033006", "requestChargeType" : "Product Consultation", "additionalCost" : "10.0", "totalCost" : "45.72" }, { "owner" : { "photoURL" : "https://contacts.csez.zohocorpin.com/file?t=user&ID=4851669", "name" : "Case" }, "secondsSpent" : "22", "executedTime" : "2016-06-13T19:30:00.000Z", "customFields" : { "timeEntryName" : "time3" }, "minutesSpent" : "22", "creatorId" : "4000000008692", "agentCostPerHour" : "20.0", "description" : "Time Entry description", "hoursSpent" : "32", "ownerId" : "4000000008692", "createdTime" : "2016-06-16T07:49:52.000Z", "id" : "4000000033011", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "657.46" } ] }

添加工单时间条目

此 API 在服务中心中创建时间条目

POST /api/v1/tickets/{ticket_id}/timeEntry

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"secondsSpent":"21", "executedTime":"2016-06-22T20:30:00.000Z", "customFields":{"timeEntryName":"time2"}, "minutesSpent":"23", "agentCostPerHour":"3.0", "description":"Time Entry description", "hoursSpent":"3", "ownerId":"4000000008692", "requestChargeType":"Customer Service", "additionalCost":"10.0", "totalCost":"20.17"}'

响应示例

{ "secondsSpent" : "21", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time2" }, "minutesSpent" : "23", "creatorId" : "4000000008692", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "createdTime" : "2016-06-21T05:52:00.828Z", "id" : "4000000045001", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }

更新工单时间条目

此 API 更新现有的时间条目

PUT /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X PUT https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"description":"Time Entry description", "requestChargeType":"Customer Service"}'

响应示例

{ "secondsSpent" : "21", "executedTime" : "2016-06-22T20:30:00.000Z", "customFields" : { "timeEntryName" : "time1" }, "minutesSpent" : "23", "creatorId" : "4000000008692", "agentCostPerHour" : "3.0", "description" : "Time Entry description", "hoursSpent" : "3", "ownerId" : "4000000008692", "createdTime" : "2016-06-21T05:52:00.000Z", "id" : "4000000045001", "requestChargeType" : "Customer Service", "additionalCost" : "10.0", "totalCost" : "20.17" }

删除工单时间条目

此 API 从服务中心中删除时间条目

DELETE /api/v1/tickets/{ticket_id}/timeEntry/{timeEntry_id}

OAuth 作用域

Desk.tickets.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/tickets/4000000031007/timeEntry/4000000034008
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

联系人

联系人是向客户服务团队提出请求或咨询/投诉的最终客户。每个联系人都映射到一个客户。

属性

属性名称
数据类型
描述
id

长整数

只读

联系人的 ID

customFields

object

可选

用户定义的字段

lastName

字符串

必需

联系人的姓氏

firstName

字符串

可选

联系人的名字

facebook

字符串

可选

联系人的 Facebook ID

twitter

字符串

可选

联系人的 Twitter ID

secondaryEmail

字符串

可选

联系人的备用电子邮件 ID

email

字符串

可选

联系人的电子邮件 ID

phone

字符串

可选

联系人的电话号码

mobile

字符串

可选

联系人的手机号码

city

字符串

可选

联系人居住的城市

country

字符串

可选

联系人居住的国家或地区

state

字符串

可选

联系人居住的省/市/自治区

street

字符串

可选

联系人的地址

zip

字符串

可选

邮政编码

description

字符串

可选

联系人描述

title

字符串

可选

联系人职位

type

字符串

可选

联系人类型

ownerId

长整数

可选

联系人所有者

长整数

可选

联系人所映射至的客户

zohoCRMContact

object

只读

从 Zoho CRM 提取的联系人详细信息

customerHappiness

object

只读

联系人的平均客户满意度评价

isDeleted

布尔型

只读

此字段指示联系人是否已删除

photoURL

字符串

只读

联系人的照片 URL

createdTime

时间戳

只读

联系人创建时间

modifiedTime

时间戳

只读

联系人修改时间

示例

{ "lastName" : "Smith", "modifiedTime" : "2015-03-02T14:49:32.000Z", "country" : null, "secondaryEmail" : null, "city" : null, "customFields" : { "permanentAddress" : null, "lastContactedOn" : null }, "description" : null, "ownerId" : "3263000000057001", "type" : null, "title" : null, "photoURL" : null, "twitter" : null, "isDeleted" : false, "street" : null, "createdTime" : "2015-02-16T14:46:24.000Z", "zohoCRMContact" : { "id" : "5000000014010", "type" : "potentials" }, "state" : null, "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "id" : "3263000000064001", "email" : "jade@zoho.com", "zip" : null, "facebook" : null, "mobile" : null, "accountId" : null, "firstName" : "Jade", "phone" : "123 99 888 23" }



获取联系人

此 API 从工作台提取单个联系人。

查询参数

参数名称
数据类型
描述

字符串

允许的值如下: accounts

GET /api/v1/contacts/{contact_id}

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000000042032
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "lastName" : "Lawrence", "modifiedTime" : "2016-05-04T09:57:17.000Z", "country" : null, "secondaryEmail" : null, "city" : null, "customFields" : { "permanentAddress" : null, "lastContactedOn" : null }, "description" : null, "ownerId" : "1892000000042001", "type" : null, "title" : null, "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo", "twitter" : null, "isDeleted" : false, "street" : null, "createdTime" : "2013-11-04T11:21:07.000Z", "zohoCRMContact" : { "id" : "5000000014010", "type" : "contacts_leads" }, "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "state" : null, "id" : "1892000000042032", "email" : "lawrence@zylker.com", "zip" : null, "facebook" : null, "mobile" : null, "accountId" : "1892000000975382", "firstName" : "Jennifer", "phone" : "1 888 900 9646" }

列出所有联系人

此 API 列出服务中心中的所有联系人。

查询参数

参数名称
数据类型
描述

列表

允许的值如下: accounts

from

整数

起始索引

limit

字符串

要提取的联系人数

sortBy

字符串

按以下特定属性排序:firstNamelastNamecreatedTime。默认排序顺序为升序。- 前缀表示升序排序顺序。

GET /api/v1/contacts

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "lastName" : "Case", "accountId" : "1892000000091433", "firstName" : "Jonathan", "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000772003/photo", "secondaryEmail" : null, "phone" : "555555", "zohoCRMContact" : null, "id" : "1892000000772003", "customerHappiness" : { "badPercentage" : "0", "okPercentage" : "0", "goodPercentage" : "0" }, "ownerId" : null, "type" : null, "email" : "case@zylker.com" }, { "lastName" : "Jade", "accountId" : "1892000000052077", "firstName" : "Christ", "photoURL" : null, "secondaryEmail" : null, "phone" : null, "zohoCRMContact" : { "id" : "1892000000772030", "type" : "contacts_leads" }, "id" : "1892000000772001", "customerHappiness" : { "badPercentage" : "22", "okPercentage" : "31", "goodPercentage" : "47" }, "ownerId" : null, "type" : null, "email" : "jade@zylker.com" } ] }

创建联系人

此 API 在服务中心中创建一个联系人。

POST /api/v1/contacts

OAuth 作用域

Desk.contacts.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/contacts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"zip":"123902", "lastName":"Jack", "country":"USA", "secondaryEmail":"hughjack@zylker.com", "city":"Texas", "facebook":"hugh jacks", "mobile":"+10 2328829010", "description":"first priority contact", "ownerId":"1892000000056007", "type":"paidUser", "title":"The contact", "accountId":"1892000000052077", "firstName":"hugh", "twitter":"Hugh jack", "phone":"91020080878", "street":"North street", "state":"Austin", "email":"jack@zylker.com"}'

响应示例

{ "lastName" : "Jack", "modifiedTime" : "2016-07-26T13:11:02.000Z", "country" : "USA", "secondaryEmail" : "hughjack@zylker.com", "city" : "Texas", "customFields" : { "permanentAddress" : null, "lastContactedOn" : null }, "description" : "first priority contact", "ownerId" : "1892000000056007", "type" : "paidUser", "title" : "The contact", "photoURL" : null, "twitter" : "Hugh jack", "isDeleted" : false, "street" : "North street", "createdTime" : "2016-07-26T13:11:02.000Z", "zohoCRMContact" : null, "state" : "Austin", "id" : "1892000001128052", "customerHappiness" : { "badPercentage" : "0", "okPercentage" : "0", "goodPercentage" : "0" }, "email" : "jack@zylker.com", "zip" : "123902", "facebook" : "hugh jack", "mobile" : "+10 2328829010", "accountId" : "1892000000052077", "firstName" : "hugh", "phone" : "91020080878" }

更新联系人

此 API 更新现有联系人的详细信息。

PATCH /api/v1/contacts/{contact_id}

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/contacts/1892000001128052
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"zip":"123902", "lastName":"john"}'

响应示例

{ "lastName" : "john", "modifiedTime" : "2016-07-26T13:11:02.000Z", "country" : "USA", "secondaryEmail" : "stephen@zylker.com", "city" : "Texas", "customFields" : { "permanentAddress" : null, "lastContactedOn" : null }, "description" : "first priority contact", "ownerId" : "1892000000056007", "type" : "paidUser", "title" : "The contact", "photoURL" : null, "twitter" : "stephen john", "isDeleted" : false, "street" : "East street", "createdTime" : "2016-07-26T13:11:02.000Z", "zohoCRMContact" : null, "state" : "Austin", "id" : "1892000001128052", "customerHappiness" : { "badPercentage" : "0", "okPercentage" : "0", "goodPercentage" : "0" }, "email" : "stephent@zylker.com", "zip" : "123902", "facebook" : "Steve john", "mobile" : "+129737289298", "accountId" : "1892000000052077", "firstName" : "Stephen", "phone" : "8981901921" }

按联系人列出工单

此 API 列出从特定联系人接收到的工单。

查询参数

参数名称
数据类型
描述
departmentId

长整数

需要从中查询工单的部门

from

整数

起始索引

limit

整数

要提取的工单数

sortBy

字符串

按以下特定属性排序: createdTimemodifiedTime。默认排序顺序是升序。- 前缀表示升序排序顺序。

GET /api/v1/contacts/{contact_id}/tickets

OAuth 作用域

Desk.contacts.READ 、Desk.tickets.READ 和 esk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contacts/18944000000421011/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "ticketNumber" : "149", "customerResponseTime" : "2017-11-03T07:03:09.203Z", "statusType" : "Open", "productId" : "18944000000424033", "contactId" : "18944000000421011", "subject" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "dueDate" : "2017-11-04T07:03:09.000Z", "departmentId" : "18944000000092305", "channel" : "Email", "threadCount" : "7", "lastThread" : null, "priority" : "Medium", "assigneeId" : null, "closedTime" : null, "commentCount" : "0", "phone" : "9876543321", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe", "createdTime" : "2017-10-12T13:11:50.000Z", "id" : "18944000000336005", "email" : "support@zohodesk.com", "status" : "Open" } ] }

联系人附件

联系人附件是您附加到联系人以帮助快速解决的文件。

属性

属性名称
数据类型
描述
id

长整数

只读

附件的 ID

creatorId

长整数

只读

添加附件的用户的 ID

createdTime

时间戳

只读

文件附件的时间

name

字符串

只读

附件名称

isPublic

布尔型

只读

附件的可见性设置

size

长整数

只读

附件大小

示例

{ "size" : "2345", "creatorId" : "1892000000047002", "name" : "contact_details.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content" }



列出所有附件

此 API 列出联系人中的所有附件。

查询参数

参数名称
数据类型
描述
sortBy

字符串

createdTime 属性排序。默认排序顺序是升序。- 前缀表示升序排序顺序。

from

整数

起始索引

limit

整数

要显示的附件数

GET /api/v1/contacts/{contact_id}/attachments

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "size" : "1079", "creatorId" : "1892000000047002", "name" : "creation.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000047041/content" }, { "size" : "135222", "creatorId" : "1892000000047002", "name" : "profile.jpg", "createdTime" : "2014-03-05T06:16:15.000Z", "isPublic" : false, "id" : "1892000000089041", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000000089041/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "contact_MobileNo.pdf", "createdTime" : "2016-06-21T10:15:34.000Z", "isPublic" : false, "id" : "1892000001052021", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052021/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "contact_profile.jpg", "createdTime" : "2016-06-21T10:15:49.000Z", "isPublic" : false, "id" : "1892000001052025", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001052025/content" } ] }

创建附件

此 API 将文件附加到联系人。

文件参数

file

Content-Type:multipart/form-data

要添加的附件

POST /api/v1/contacts/{contact_id}/attachments

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "size" : "32", "creatorId" : "1892000000042002", "name" : "profile.jpg", "createdTime" : "2016-05-30T08:32:51.338Z", "isPublic" : false, "id" : "1892000001010001", "href" : "https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001/content" }

删除附件

此 API 从联系人删除附件。

DELETE /api/v1/contacts/{contact_id}/attachments/{attachment_id}

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/contacts/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

客户

客户是指使用您的产品或服务的客户机构。一个客户可以有多个联系人。

属性

属性名称
数据类型
描述
id

长整数

只读

客户的 ID

customFields

列表

可选

与客户关联的用户定义字段

accountName

字符串

必需

客户名称

email

字符串

可选

客户的电子邮件 ID

website

字符串

可选

客户的网站

fax

字符串

可选

客户的传真号码

ownerId

长整数

可选

客户所有者的 ID

associatedSLAIds

列表

可选

与客户关联的 SLA 的 ID。一个客户可以有多个 SLA,但对于客户的每个部门,您只能映射一个 SLA

industry

字符串

可选

客户所经营的行业

city

字符串

可选

客户总部所在的城市

country

字符串

可选

客户总部所在的国家或地区

state

字符串

可选

客户总部所在的省/市/自治区

street

字符串

可选

客户的地址

code

字符串

可选

邮政编码

description

字符串

可选

客户的简短描述

phone

字符串

可选

客户的电话号码

annualrevenue

双精度型

可选

客户的年收入

createdTime

时间戳

只读

客户创建时间

modifiedTime

时间戳

只读

客户修改时间

示例

{ "country" : "USA", "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : "www.zylker.com", "code" : "4436", "accountName" : "Zylker", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "contactCount" : "1" }, "description" : null, "industry" : "Automation", "ownerId" : "3263000000057001", "phone" : "9382991011", "street" : null, "annualrevenue" : null, "createdTime" : "2015-02-16T16:57:44.000Z", "id" : "3263000000074571", "state" : null, "fax" : "+1 444 8439 2350", "email" : "support@zylker.com" }



获取客户

此 API 从工作台提取一个客户。

GET /api/v1/accounts/{account_id}

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/accounts/3263000000074571
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "country" : "USA", "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : "www.zylker.com", "code" : "3211", "accountName" : "Zylker", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "contactCount" : "1" }, "description" : null, "industry" : "Automation", "ownerId" : "3263000000057001", "phone" : "6218129190", "street" : null, "annualrevenue" : null, "createdTime" : "2015-02-16T16:57:44.000Z", "state" : null, "id" : "3263000000074571", "fax" : "+1 444 8656 8732", "email" : "support@zylker.com" }

列出所有客户

此 API 列出服务中心中的所有客户。

查询参数

参数名称
数据类型
描述
from

整数

起始索引

limit

整数

要提取的客户数

sortBy

字符串

按以下特定属性排序: accountNamecreatedTime。默认排序顺序是升序。- 前缀表示升序排序顺序。

GET /api/v1/accounts

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "website" : "112121", "accountName" : "Admin Account", "phone" : "121212", "id" : "1892000000052077", "email" : "admin@zylker.com" }, { "website" : "1211212", "accountName" : "Agent Account", "phone" : "11211", "id" : "1892000000052090", "email" : "agent@zylker.com" } ] }

创建客户

此 API 在服务中心中创建一个客户。

POST /api/v1/accounts

OAuth 作用域

Desk.contacts.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/accounts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"accountName":"Zylker", "phone":"98348229382"}'

响应示例

{ "country" : null, "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : null, "code" : null, "accountName" : "Zylker", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "contactCount" : null }, "description" : null, "industry" : null, "ownerId" : "3263000000057001", "phone" : "98348229382", "street" : null, "annualrevenue" : null, "createdTime" : "2015-02-16T16:57:44.000Z", "state" : null, "id" : "3263000000074571", "fax" : null, "email" : null }

更新客户

此 API 更新现有客户的详细信息。

PATCH /api/v1/accounts/{account_id}

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/accounts/3263000000074571
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"accountName":"Zylker Agents", "phone":"82301023900123"}'

响应示例

{ "country" : null, "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : null, "code" : null, "accountName" : "Zylker Agents", "city" : null, "associatedSLAIds" : [ 3263000000057, 3000000057001 ], "customFields" : { "contactCount" : "1" }, "description" : null, "industry" : null, "ownerId" : "3263000000057001", "phone" : "82301023900123", "street" : null, "annualrevenue" : null, "createdTime" : "2015-02-16T16:57:44.000Z", "state" : null, "id" : "3263000000074571", "fax" : null, "email" : null }

按客户列出工单

此 API 列出从特定客户接收到的工单。

查询参数

参数名称
数据类型
描述
departmentId

长整数

需要从中查询工单的部门

from

整数

起始索引

limit

整数

要提取的工单数

sortBy

字符串

按以下特定属性排序: createdTimemodifiedTime。默认排序顺序是升序。- 前缀表示升序排序顺序。

GET /api/v1/accounts/{account_id}/tickets

OAuth 作用域

Desk.accounts.READ 、Desk.tickets.READ 和 Desk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/accounts/18944000000421015/tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "ticketNumber" : "149", "customerResponseTime" : "2017-11-03T07:03:09.203Z", "statusType" : "Open", "productId" : "18944000000424033", "contactId" : "18944000000421011", "subject" : "Hi.There is a sudden delay in the processing of the orders.Check this with high priority", "dueDate" : "2017-11-04T07:03:09.000Z", "departmentId" : "18944000000092305", "channel" : "Email", "threadCount" : "7", "lastThread" : null, "priority" : "Medium", "assigneeId" : null, "closedTime" : null, "commentCount" : "0", "phone" : "9876543321", "webUrl" : "https://desk.zoho.com/support/zylker/ShowHomePage.do#Cases/dv/20d7881a46edfcffefe308ab38676ec3e612657a51fd5fbe", "createdTime" : "2017-10-12T13:11:50.000Z", "id" : "18944000000336005", "email" : "support@zohodesk.com", "status" : "Open" } ] }

客户附件

客户附件是您附加到客户以帮助快速解决的文件。

属性

属性名称
数据类型
描述
id

长整数

只读

附件的 ID

creatorId

长整数

只读

添加附件的用户的 ID

createdTime

时间戳

只读

文件附件的时间

name

字符串

只读

附件名称

isPublic

布尔型

只读

附件的可见性设置

size

长整数

只读

附件大小

示例

{ "size" : "2345", "creatorId" : "1892000000047002", "name" : "Associated_contacts.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content" }



列出所有附件

此 API 列出客户中的所有附件。

查询参数

参数名称
数据类型
描述
sortBy

字符串

createdTime 属性排序。默认排序顺序是升序。- 前缀表示升序排序顺序。

from

整数

起始索引

limit

整数

要显示的附件数

GET /api/v1/accounts/{account_id}/attachments

OAuth 作用域

Desk.contacts.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "size" : "1079", "creatorId" : "1892000000047002", "name" : "profile_photo.jpg", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000047041/content" }, { "size" : "135222", "creatorId" : "1892000000047002", "name" : "profile.pdf", "createdTime" : "2014-03-05T06:16:15.000Z", "isPublic" : false, "id" : "1892000000089041", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000000089041/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "logo.jpg", "createdTime" : "2016-06-21T10:15:34.000Z", "isPublic" : false, "id" : "1892000001052021", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052021/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "profile.pdf", "createdTime" : "2016-06-21T10:15:49.000Z", "isPublic" : false, "id" : "1892000001052025", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001052025/content" } ] }

创建附件

此 API 将文件附加到客户。

文件参数

file

Content-Type:multipart/form-data

要添加的附件

POST /api/v1/accounts/{account_id}/attachments

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "size" : "32", "creatorId" : "1892000000042002", "name" : "AccountDetails.txt", "createdTime" : "2016-05-30T08:32:51.338Z", "isPublic" : false, "id" : "1892000001010001", "href" : "https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001/content" }

删除附件

此 API 从客户删除附件。

DELETE /api/v1/accounts/{account_id}/attachments/{attachment_id}

OAuth 作用域

Desk.contacts.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/accounts/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

任务

任务是分配给客服的工作活动。任务并不一定要仅与工单解决相关。

属性

属性名称
数据类型
描述
id

长整数

只读

任务的 ID

customFields

列表

可选

与任务相关的用户定义字段

长整数

必需

与任务关联的部门

subject

字符串

必需

任务的主题

长整数

可选

工单 ID(如果任务与特定工单关联)

dueDate

时间戳

可选

完成任务的到期日

ownerId

字符串

可选

任务所有者

category

字符串

可选

任务类别

status

字符串

可选

任务完成状态

优先级

字符串

可选

任务优先级

description

字符串

可选

任务描述

createdTime

时间戳

只读

任务创建时间

modifiedTime

时间戳

只读

任务修改时间

creatorId

字符串

只读

创建任务的用户的 ID

ticket

工单

只读

与任务关联的工单

示例

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "customFields" : { }, "subject" : "New Task", "completedTime" : null, "departmentId" : "3000000007043", "dueDate" : "2016-07-29T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "createdTime" : "2016-07-26T17:32:11.000Z", "id" : "3000000018001", "category" : null, "ticketId" : "3000000008753", "status" : "Not Started" }



获取任务

此 API 从工作台提取单个任务。

查询参数

参数名称
数据类型
描述

字符串

允许的值如下: tickets

GET api/v1/tasks/{task_id}

OAuth 作用域

Desk.tasks.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tasks/3000000018001?include=tickets
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "modifiedTime" : "2016-07-26T17:32:11.000Z", "ticket" : { "ticketNumber" : "101", "contact" : { "firstName" : null, "lastName" : "Lawrence", "id" : "3000000008749" }, "id" : "3000000008753" }, "customFields" : { }, "subject" : "New Task", "completedTime" : null, "departmentId" : "3000000007043", "dueDate" : "2016-07-29T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "createdTime" : "2016-07-26T17:32:11.000Z", "id" : "3000000018001", "category" : null, "ticketId" : "3000000008753", "status" : "Not Started" }

列出所有任务

此 API 列出服务中心中的所有任务。

查询参数

参数名称
数据类型
描述

字符串

允许的值如下: tickets

from

整数

起始索引

limit

整数

要提取的任务数

长整数

需要从中查询任务的部门

sortBy

字符串

按以下特定属性排序: dueDatecreatedTime。默认排序顺序为升序。- 前缀表示升序排序顺序。

GET api/v1/tasks

OAuth 作用域

Desk.tasks.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "modifiedTime" : "2016-07-13T06:45:56.000Z", "subject" : "New task", "completedTime" : null, "dueDate" : "2013-12-28T06:30:00.000Z", "departmentId" : "1892000000006907", "creatorId" : "1892000000042001", "description" : null, "ownerId" : "1892000000056007", "priority" : "Low", "isCommented" : true, "createdTime" : "2013-12-19T12:02:23.000Z", "id" : "1892000000055041", "category" : "Meeting", "ticketId" : "1892000001125055", "status" : "Not Started" }, { "modifiedTime" : "2014-03-21T11:31:55.000Z", "subject" : "Modify ticket 102", "completedTime" : null, "dueDate" : "2014-03-28T06:30:00.000Z", "departmentId" : "1892000000006907", "creatorId" : "1892000000042001", "description" : null, "ownerId" : "1892000000042001", "priority" : "High", "isCommented" : false, "createdTime" : "2014-03-21T11:31:03.000Z", "id" : "1892000000138005", "category" : null, "ticketId" : "1892000000094004", "status" : "Not Started" }, { "modifiedTime" : "2014-05-26T07:26:46.000Z", "subject" : "Review changes", "completedTime" : null, "dueDate" : null, "departmentId" : "1892000000006907", "creatorId" : "1892000000042001", "description" : "Make all the mentioned changes", "ownerId" : "1892000000042001", "priority" : "High", "isCommented" : false, "createdTime" : "2014-05-26T07:26:46.000Z", "id" : "1892000000272001", "category" : null, "ticketId" : null, "status" : "Not Started" } ] }

创建任务

此 API 在服务中心中添加一个任务。

POST api/v1/tasks

OAuth 作用域

Desk.tasks.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"subject":"Bug Fix #120", "departmentId":"3000000007043", "dueDate":"2016-07-21T16:16:16.000Z", "category": null, "priority":"High", "status":"In Progress"}'

响应示例

{ "modifiedTime" : "2016-07-14T09:14:41.000Z", "customFields" : { }, "subject" : "Bug Fix #120", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "High", "createdTime" : "2016-07-14T08:27:26.000Z", "id" : "3000000054002", "category" : "null", "ticketId" : "3000000008753", "status" : "In Progress" }

更新任务

此 API 更新现有的任务。

PATCH api/v1/tasks/{task_id}

OAuth 作用域

Desk.tasks.UPDATE

请求示例

$ curl -X PATCH https://desk.zoho.com/api/v1/tasks/3000000054002
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

  -d '{"subject":"Bug Fix #120", "departmentId":"3000000007043", "dueDate":"2016-07-21T16:16:16.000Z", "category": null, "priority":"High", "status":"In Progress"}'

响应示例

{ "modifiedTime" : "2016-07-14T09:14:41.000Z", "customFields" : { }, "subject" : "Bug Fix #120", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "High", "createdTime" : "2016-07-14T08:27:26.000Z", "id" : "3000000054002", "category" : "null", "ticketId" : "3000000008753", "status" : "In Progress" }

按工单列出任务

此 API 列出所有与特定工单相关的任务。

查询参数

参数名称
数据类型
描述
from

整数

起始索引

isCompleted

布尔型

任务的完成状态

limit

整数

要提取的任务数

GET /api/v1/tickets/{ticket_id}/tasks

OAuth 作用域

Desk.tasks.READ 和 esk.tickets.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/1892000000042034/tasks
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "modifiedTime" : "2016-07-14T08:22:16.000Z", "customFields" : { }, "subject" : "Bug Fix #120", "departmentId" : "3000000007043", "dueDate" : "2016-07-21T16:16:16.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : null, "priority" : "Normal", "createdTime" : "2016-07-14T08:22:16.000Z", "id" : "3000000053002", "category" : "null", "ticketId" : "3000000008753", "status" : "In Progress" } ] }

任务附件

任务附件是您附加到任务以帮助快速解决的文件。

属性

属性名称
数据类型
描述
id

长整数

只读

附件的 ID

creatorId

长整数

只读

添加附件的用户的 ID

createdTime

时间戳

只读

文件附件的时间

name

字符串

只读

附件名称

isPublic

布尔型

只读

附件的可见性设置

size

长整数

只读

附件大小

示例

{ "size" : "2345", "creatorId" : "1892000000047002", "name" : "taskfile.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047042", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" }



列出所有附件

此 API 列出任务中的所有附件。

查询参数

参数名称
数据类型
描述
sortBy

字符串

createdTime 属性排序。默认排序顺序是升序。- 前缀表示升序排序顺序。

from

整数

起始索引

limit

整数

要显示的附件数

GET /api/v1/tasks/{task_id}/attachments

OAuth 作用域

Desk.tasks.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "size" : "1079", "creatorId" : "1892000000047002", "name" : "issue.txt", "createdTime" : "2013-11-06T10:25:03.000Z", "isPublic" : false, "id" : "1892000000047041", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" }, { "size" : "135222", "creatorId" : "1892000000047002", "name" : "program.pdf", "createdTime" : "2014-03-05T06:16:15.000Z", "isPublic" : false, "id" : "1892000000089041", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "errorfixed.txt", "createdTime" : "2016-06-21T10:15:34.000Z", "isPublic" : false, "id" : "1892000001052021", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" }, { "size" : "97951", "creatorId" : "1892000000042002", "name" : "error_page.pdf", "createdTime" : "2016-06-21T10:15:49.000Z", "isPublic" : false, "id" : "1892000001052025", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000000047041/content" } ] }

创建附件

此 API 将文件附加到任务。

文件参数

file

Content-Type:multipart/form-data

要添加的附件

POST /api/v1/tasks/{task_id}/attachments

OAuth 作用域

Desk.tasks.UPDATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "size" : "32", "creatorId" : "1892000000042002", "name" : "task_history.txt", "createdTime" : "2016-05-30T08:32:51.338Z", "isPublic" : false, "id" : "1892000001010001", "href" : "https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001/content" }

删除附件

此 API 从任务删除附件。

DELETE /api/v1/tasks/{task_id}/attachments/{attachment_id}

OAuth 作用域

Desk.tasks.UPDATE

请求示例

$ curl -X DELETE https://desk.zoho.com/api/v1/tasks/1892000001004024/attachments/1892000001010001
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

200

客服

客服是机构中的客户服务专员。他们是服务中心软件的主要用户,使用该软件与联系人交互并解决工单。

属性

属性名称
数据类型
描述
emailId

字符串

必需

客服的电子邮件 ID

status

字符串

只读

客服的激活状态: ACTIVEDISABLED

lastName

字符串

必需

客服的姓氏

firstName

字符串

可选

客服的名字

phone

字符串

可选

客服的电话号码

mobile

字符串

可选

客服的手机号码

xtn

字符串

可选

客服的分机号

associatedDepartmentIds

列表

必需

与客服关联的部门

associatedChatDepartmentIds

列表

可选

与客服关联的聊天部门

id

长整数

只读

客服的 ID

zuid

长整数

只读

客服的 Zoho 用户标识

roleId

长整数

只读

客服的角色 ID

profileId

长整数

只读

客服的简档 ID

photoURL

字符串

只读

客服的照片 URL

isConfirmed

布尔型

只读

客服的确认状态

countryCode

字符串

可选

客服的国家/地区代码。一个人只能更新自己的 countryCode。如果传递了其他客服的此属性,它将被忽略。

langCode

字符串

可选

客服的语言代码。一个人只能更新自己的 langCode。如果传递了其他客服的此属性,它将被忽略。

示例

{ "lastName" : "case", "extn" : "3298", "roleId" : "1892000000056099", "langCode" : "fr_FR", "mobile" : "", "emailId" : "case@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10687231", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ], "firstName" : "", "photoURL" : null, "phone" : "12121", "profileId" : "1892000000056091", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000056007", "status" : "ACTIVE" }



获取客服

此 API 从服务中心提取客服详细信息。

查询参数

参数名称
数据类型
描述

字符串

允许的值如下:profileroleassociatedDepartmentsassociatedChatDepartments。您可以在查询参数中提供多个以逗号分隔的值。

GET /api/v1/agents/{agent_id}

OAuth 作用域

Desk.settings.READ 和 Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/agents/1892000000056096?include=profile,role,associatedDepartments,associatedChatDepartments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "associatedChatDepartments" : [ { "name" : "Developement", "id" : "1892000000006907" } ], "lastName" : "case", "extn" : "3298", "role" : { "name" : "CEO", "id" : "1892000000056099" }, "roleId" : "1892000000056099", "langCode" : "fr_FR", "profile" : { "name" : "Administrator", "id" : "1892000000056091" }, "mobile" : "", "emailId" : "case@zylker.com", "associatedChatDepartmentIds" : [ "1892000000006907" ], "zuid" : "10687231", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069" ], "associatedDepartments" : [ { "name" : "Developement", "id" : "1892000000006907" }, { "name" : "R & D", "id" : "1892000000082069" } ], "firstName" : "", "photoURL" : null, "phone" : "12121", "profileId" : "1892000000056091", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000056096", "status" : "ACTIVE" }

列出所有客服

此 API 列出服务中心中的客服。

查询参数

参数名称
数据类型
描述
from

整数

起始索引

limit

整数

要提取的客服数;默认值为 10,最大值为 200

status

字符串

用于根据客服的激活状态对客服进行过滤的参数: ACTIVEDISABLED

GET /api/v1/agents

OAuth 作用域

Desk.settings.READ 和 Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/agents
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "lastName" : "case", "extn" : "3298", "roleId" : "1892000000056099", "langCode" : "en_US", "mobile" : "", "emailId" : "case@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10687231", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ], "firstName" : "", "photoURL" : null, "phone" : "12121", "profileId" : "1892000000056091", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000056007", "status" : "ACTIVE" }, { "lastName" : "jade", "extn" : "3203", "roleId" : "1892000000056899", "langCode" : "en_US", "mobile" : "", "emailId" : "jade@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10657727", "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717", "1892000001019041", "1892000001106673", "1892000001109673" ], "firstName" : "", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727", "phone" : "", "profileId" : "1892000000056091", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000042001", "status" : "ACTIVE" }, { "lastName" : "john", "extn" : "3228", "roleId" : "1892000000056004", "langCode" : "en_US", "mobile" : "", "emailId" : "john@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : "10713988", "associatedDepartmentIds" : [ "1892000000006907", "1892000001019041" ], "firstName" : "", "photoURL" : null, "phone" : "68779989", "profileId" : "18920000000232043", "countryCode" : "en_US", "isConfirmed" : true, "id" : "1892000000070001", "status" : "DISABLED" }, { "lastName" : "Waugh", "extn" : "4020", "roleId" : "1892000000056004", "langCode" : "ja_JP", "mobile" : "", "emailId" : "stephen@zylker.com", "associatedChatDepartmentIds" : [ ], "zuid" : null, "associatedDepartmentIds" : [ "1892000000006907", "1892000000082069", "1892000000639717" ], "firstName" : "Steve", "photoURL" : null, "phone" : "", "profileId" : "18920000000232043", "countryCode" : "en_US", "isConfirmed" : false, "id" : "1892000000888059", "status" : "ACTIVE" } ] }

部门

部门是服务中心中配置的组织分部。

属性

属性名称
数据类型
描述
id

长整数

只读

部门的 ID

name

字符串

必需

部门名称

nameInCustomerPortal

字符串

可选

部门的显示名称

description

字符串

可选

部门描述

isVisibleInCustomerPortal

布尔型

必需

客户门户中的部门可见性

isEnabled

布尔型

可选

部门的激活状态

hasLogo

布尔型

只读

指示部门是否具有徽标

creatorId

长整数

只读

创建部门的用户的 ID

associatedAgentIds

列表

必需

与部门关联的客服的 ID

示例

{ "hasLogo" : true, "isVisibleInCustomerPortal" : true, "isEnabled" : true, "name" : "Testing", "creatorId" : "1892000000042001", "description" : "This is default department", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "id" : "1892000000082069", "nameInCustomerPortal" : "TestingPortal" }



获取部门

此 API 从服务中心提取部门详细信息。

GET /api/v1/departments/{department_id}

OAuth 作用域

Desk.settings.READ 和 Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/departments/1892000000006907
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "hasLogo" : false, "isVisibleInCustomerPortal" : true, "isEnabled" : true, "creatorId" : "1892000000042001", "name" : "Department 1", "description" : "This is department description", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "id" : "1892000000006907", "nameInCustomerPortal" : "Customer Relations" }

列出所有部门

此 API 列出服务中心中的部门。

查询参数

参数名称
数据类型
描述
isEnabled

布尔型

用于根据部门的已启用状态对部门进行过滤的参数

from

整数

起始索引

limit

整数

要提取的部门数;默认值为 10,最大值为 200

GET /api/v1/departments

OAuth 作用域

Desk.settings.READ 和 Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/departments
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "isDefault" : true, "hasLogo" : false, "isVisibleInCustomerPortal" : true, "isEnabled" : true, "creatorId" : "1892000000042001", "name" : "Department 1", "description" : "This is department description", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059" ], "id" : "1892000000006907", "nameInCustomerPortal" : "Department 1" }, { "isDefault" : false, "hasLogo" : false, "isVisibleInCustomerPortal" : true, "isEnabled" : true, "creatorId" : "1892000000042001", "name" : "newdept", "description" : "Dept example", "associatedAgentIds" : [ "1892000000042001", "1892000000056007", "1892000000888059", "1892000000292001" ], "id" : "1892000000082069", "nameInCustomerPortal" : "newdept" } ] }

上传内容

上传内容是与工单一起仅存在 24 小时的临时附件。

属性

属性名称
数据类型
描述
id

长整数

只读

附件的 ID

creatorId

长整数

只读

添加附件的用户的 ID

createdTime

时间戳

只读

文件附件的时间

name

字符串

只读

附件名称

isPublic

布尔型

只读

附件的可见性设置

size

长整数

只读

附件大小

示例

{ "size" : "4769", "creatorId" : "4000000008692", "name" : "zoho.jpeg", "createdTime" : "2016-06-23T07:31:42.000Z", "isPublic" : false, "id" : "4000000055001" }



上传文件

此 API 上传一个文件。

文件参数

file

Content-Type:multipart/form-data

要附加的文件

POST /api/v1/uploads

OAuth 作用域

Desk.basic.CREATE

请求示例

$ curl -X POST https://desk.zoho.com/api/v1/uploads
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "size" : "4769", "creatorId" : "4000000008692", "name" : "zoho.jpeg", "createdTime" : "2016-06-23T07:31:42.000Z", "isPublic" : false, "id" : "4000000055001", "href" : "https://desk.zoho.com/api/v1/uploads/1892000001008043/contents" }

合同

合同可帮助您规划您的办公桌承诺,从而使您能够提供更专业、更热忱的客户服务。通过定义合同,您可以确定要提供的服务水平,并为客户或产品设置合同期限。

属性

属性名称
数据类型
描述
id

长整数

只读

合同的 ID

associatedSLAId

长整数

可选

与合同关联的 SLA 的 ID

accountId

长整数

可选

与合同关联的客户的 ID

departmentId

长整数

可选

合同所属的部门

productId

长整数

可选

与合同关联的产品的 ID

contractNumber

字符串

可选

合同的序列号

notificationAgentIds

列表

可选

要通知的客服的列表

notifyBefore

整数

可选

endDate 之前的天数,必须在此时向相关客服发送关于合同到期的通知

notifyOn

日期

只读

必须发送合同到期通知的日期

startDate

日期

可选

合同生效日期

endDate

日期

可选

合同失效日期

ownerId

长整数

可选

合同所有者的 ID

createdBy

字符串

只读

创建合同的用户

modifiedBy

字符串

只读

修改合同的用户

createdTime

时间戳

只读

合同创建时间

modifiedTime

时间戳

只读

合同修改时间

contractName

字符串

可选

合同名称

description

字符串

可选

合同的简短描述

customFields

列表

可选

与合同关联的用户定义字段

示例

{ "associatedSLAId" : "5000000007671", "modifiedTime" : "2018-01-15T11:13:04.000Z", "productId" : "5000000009328", "endDate" : "2019-01-10", "customFields" : { "hasExpired" : "true" }, "departmentId" : "5000000007235", "notifyBefore" : "5", "contractNumber" : "101", "description" : null, "ownerId" : "5000000009148", "notificationAgentIds" : [ "5000000009148" ], "accountId" : "5000000009326", "createdBy" : "5000000009148", "notifyOn" : "2019-01-05", "createdTime" : "2018-01-10T11:29:41.000Z", "contractName" : "Ticket Resolution Contract for 5 Star Crisps", "modifiedBy" : "5000000009148", "id" : "5000000009331", "startDate" : "2018-01-10" }



获取合同

此 API 从服务中心提取单个合同。

GET api/v1/contracts/{{contract_id}}

OAuth 作用域

Desk.settings.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contracts/5000000009331
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "associatedSLAId" : "5000000007671", "modifiedTime" : "2018-01-15T11:13:04.000Z", "productId" : "5000000009328", "endDate" : "2019-01-10", "customFields" : { "hasExpired" : "true" }, "departmentId" : "5000000007235", "notifyBefore" : "5", "contractNumber" : "101", "description" : null, "ownerId" : "5000000009148", "notificationAgentIds" : [ "5000000009148" ], "accountId" : "5000000009326", "createdBy" : "5000000009148", "notifyOn" : "2019-01-05", "createdTime" : "2018-01-10T11:29:41.000Z", "contractName" : "Ticket Resolution Contract for 5 Star Crisps", "modifiedBy" : "5000000009148", "id" : "5000000009331", "startDate" : "2018-01-10" }

列出所有合同

要获取合同列表

查询参数

参数名称
数据类型
描述
from

整数

起始索引

limit

整数

要提取的合同数

viewId

整数

提取合同时要应用的视图的 ID

长整数

必须从中提取合同的部门的 ID

长整数

与合同关联的客户的 ID

ownerId

长整数

合同所有者的 ID

sortBy

字符串

用于按下列其中一个属性对合同排序的参数:
accountName

contractName

contractEndDate

contractStartDate

createdTime
 
modifiedTime
默认排序顺序是升序。要按升序顺序进行排序,请在参数前面添加 -

GET api/v1/contracts

OAuth 作用域

Desk.settings.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contracts
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "associatedSLAId" : "5000000007671", "accountId" : "5000000009326", "productId" : "5000000009328", "endDate" : "2019-01-10", "departmentId" : "5000000007235", "contractName" : "Ticket Resolution Contract for 5 Star Crisps", "id" : "5000000009331", "ownerId" : "5000000009148", "startDate" : "2018-01-10" }, { "associatedSLAId" : "5000000007673", "accountId" : "5000000009248", "productId" : "5000000009328", "endDate" : "2018-01-14", "departmentId" : "5000000007235", "contractName" : "Ticket Resolution Contract for Colum Stories", "id" : "5000000018008", "ownerId" : "5000000009148", "startDate" : "2018-01-01" } ] }

跨实体搜索

此 API 根据模块查询参数的值返回所有模块或特定模块中的信息。

查询参数

参数名称
数据类型
描述
searchStr

字符串

要搜索的关键字或短语

module

字符串

要在其中搜索的模块:ticketsaccountscontactstasks。默认响应包括所有模块。

departmentId

长整数

需要从中查询实体的部门

from

整数

起始索引,从 0 开始

limit

整数

要提取的实体数

sortBy

字符串

按以下特定属性排序: relevancemodifiedTime

GET /api/v1/search?searchStr={searchStr}&departmentId={departmentId}&from={from}&limit={limit}&sortBy={sortField}

OAuth 作用域

Desk.contacts.READ、Desk.tickets.READ、Desk.tasks.READ 和 Desk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/search?searchStr=zylker&from=0&limit=10&sortBy=modifiedTime
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "customerResponseTime" : "2016-06-27T07:22:52.117Z", "productId" : "4000000013043", "contactId" : "4000000013012", "subject" : "Zylker ticket", "customFields" : { "featureRequest" : false, "region" : "Asia" }, "module" : "tickets", "departmentId" : "4000000007043", "dueDate" : null, "channel" : "Phone", "threadCount" : "0", "priority" : null, "assigneeId" : "4000000008692", "closedTime" : null, "commentCount" : "0", "number" : "104", "phone" : null, "contact" : { "phone" : null, "name" : "Stephen", "id" : "4000000013012", "type" : null, "email" : null, "account" : { "website" : null, "name" : "Zylker Accounts", "id" : "4000000008850" } }, "createdTime" : "2016-06-27T07:22:52.000Z", "assignee" : { "firstName" : "", "lastName" : "jade", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727", "emailId" : "jade@zylker.com", "id" : "5000000009116", "zuid" : "10657727" }, "id" : "4000000016009", "department" : { "name" : "Testing", "id" : "5000000007235" }, "email" : null, "status" : "Open" }, { "ticket" : null, "subject" : "Wifi adapter not working in zylker", "completedTime" : null, "customFields" : { "severity" : "High", "followUpDate" : "2016-07-07T19:30:00.000Z" }, "module" : "tasks", "dueDate" : "2016-06-27T19:30:00.000Z", "description" : null, "ownerId" : "4000000008692", "priority" : "High", "isCommented" : false, "createdBy" : "4000000008692", "contact" : null, "createdTime" : "2016-06-27T06:39:48.000Z", "id" : "4000000013065", "assignee" : { "firstName" : "", "lastName" : "jade", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727", "emailId" : "jade@zylker.com", "id" : "5000000009116", "zuid" : "10657727" }, "category" : null, "department" : { "name" : "Testing", "id" : "5000000007235" }, "ticketId" : null, "status" : "Not Started" }, { "website" : null, "phone" : null, "accountName" : "Zylker India", "customFields" : { "city" : "Delhi", "state" : "India" }, "module" : "accounts", "id" : "4000000013027", "email" : null }, { "lastName" : "Stephen", "accountId" : "4000000008850", "firstName" : "Henry", "photoURL" : null, "phone" : null, "customFields" : { "customerSince" : "2011", "editionUsed" : "Professional" }, "module" : "contacts", "fullName" : "Henry Stephen", "id" : "4000000013012", "ownerId" : "4000000008692", "email" : null, "account" : { "website" : null, "name" : "Zylker India", "id" : "4000000008850" } } ], "count" : { "tickets" : 1, "accounts" : 1, "tasks" : 1, "contacts" : 1 } }

“工单搜索”API

此 API 在服务中心中搜索工单。可提供以逗号分隔的值,这表示将使用所提供的任一值对字段进行搜索。

Zoho Desk API 支持两种类型的搜索:exact matchwildcard match
仅当传递的值与服务中心中的资源完全匹配时,exact match 才会返回该资源。
即使传递的值与服务中心中的资源部分匹配,wildcard match 也返回该资源。
要执行 wildcard match,请在要搜索的值后面追加星号 (*)。

CustomField 参数示例:
customField1=ModelName:F3*
customField2=phone:902*
customField3=permanentAddress: Wall Street*

注:
wildcard match 不适用于并非字符串类型的自定义字段

已进行 URL 编码的示例:
customField1=ModelName%3AF3*
customField2=phone%3A902*
customField3=permanentAddress%3AWall%20Street*

查询参数

参数名称
数据类型
描述
from

整数

起始索引,从 0 开始

limit

整数

要提取的实体数

departmentId

长整数

必须从中提取实体的部门的 ID。如果未传递此属性,将在允许的部门中搜索
exact match

ticketNumber

字符串

服务中心中工单的序列号
exact match

subject

字符串

服务中心中工单的主题
wildcard search

status

字符串

工单的状态。包括服务中心中存在的自定义状态
exact match

priority

字符串

工单优先级
exact match

email

字符串

工单中的电子邮件 ID
wildcard search

phone

字符串

工单中的电话号码
wildcard search

channel

字符串

通过其接收工单的渠道
exact match

assigneeId

字符串

客服的 ID,已分配该客服来解决工单
exact match

contactId

字符串

提交工单的联系人的 ID
exact match

accountId

字符串

与工单关联的客户的 ID
exact match

contactName

字符串

提交工单的联系人的名称
wildcard search

accountName

字符串

与工单关联的客户的名称
wildcard search

customField1

字符串

工单中的自定义字段
wildcard search

customField2

字符串

工单中的自定义字段
wildcard search

customField3

字符串

工单中的自定义字段
wildcard search

GET /api/v1/tickets/search

OAuth 作用域

Desk.tickets.READ 和 Desk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tickets/search?limit=1&subject=analysis*
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "ticketNumber" : "101", "modifiedTime" : "2016-06-21T12:58:09.122Z", "subCategory" : "Sub General", "subject" : "Real Time analysis Requirement", "customFields" : { }, "dueDate" : "2016-06-23T12:58:09.211Z", "departmentId" : "1892000000006907", "channel" : "Email", "description" : "Hai This is description", "resolution" : null, "closedTime" : null, "isOverDue" : true, "responseDueDate" : null, "contact" : { "firstName" : "Jonathan", "lastName" : "Casie", "accountId" : "1892000000045028", "id" : "5000000009587", "email" : "casie@zylker.com", "account" : { "accountName" : "Zylker Account", "id" : "1892000000980421" } }, "createdTime" : "2016-06-21T12:50:04.000Z", "modifiedBy" : "1892000000056007", "id" : "1892000001054003", "department" : { "name" : "Testing", "id" : "5000000007235" }, "email" : "carol@zylker.com", "customerResponseTime" : "2016-11-02T10:38:07.000Z", "productId" : null, "contactId" : "1892000000042032", "threadCount" : "0", "lastThread" : null, "priority" : "High", "classification" : null, "assigneeId" : "1892000000056007", "commentCount" : "0", "accountId" : null, "phone" : null, "assignee" : { "firstName" : "", "lastName" : "jade", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727", "emailId" : "jade@zylker.com", "id" : "5000000009116", "zuid" : "10657727" }, "category" : "General", "status" : "Open" } ], "count" : 1 }

“客户搜索”API

此 API 在服务中心中搜索客户。可提供以逗号分隔的值,这表示将使用所提供的任一值对字段进行搜索。
Zoho Desk API 支持两种类型的搜索:exact matchwildcard match
仅当传递的值与服务中心中的资源完全匹配时,exact match 才会返回该资源。
即使传递的值与服务中心中的资源部分匹配,wildcard match 也返回该资源。
要执行 wildcard match,请在要搜索的值后面追加星号 (*)。

查询参数

参数名称
数据类型
描述
from

整数

起始索引,从 0 开始

limit

整数

要提取的实体数

accountName

字符串

客户名称
wildcard search

customField1

字符串

客户中的自定义字段
wildcard search
示例:customField1=activeAccount:true

customField2

字符串

客户中的自定义字段
wildcard search

customField3

字符串

客户中的自定义字段
wildcard search

GET /api/v1/accounts/search

OAuth 作用域

Desk.accounts.READ 和 esk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/accounts/search?limit=1&accountName=Zylker
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "country" : "USA", "modifiedTime" : "2015-03-02T14:49:18.000Z", "website" : "www.zylker.com", "code" : "3211", "accountName" : "Zylker", "city" : null, "customFields" : { }, "description" : null, "industry" : "Automation", "ownerId" : "3263000000057001", "phone" : "6218129190", "street" : null, "annualrevenue" : "0.0", "createdTime" : "2015-02-16T16:57:44.000Z", "state" : null, "id" : "+1 444 8656 8732", "fax" : null, "email" : "support@zylker.com" } ], "count" : 1 }

“联系人搜索”API

此 API 在服务中心中搜索联系人。可提供以逗号分隔的值,这表示将使用所提供的任一值对字段进行搜索。
Zoho Desk API 支持两种类型的搜索:exact matchwildcard match
仅当传递的值与服务中心中的资源完全匹配时,exact match 才会返回该资源。
即使传递的值与服务中心中的资源部分匹配,wildcard match 也返回该资源。
要执行 wildcard match,请在要搜索的值后面追加星号 (*)。

查询参数

参数名称
数据类型
描述
from

整数

起始索引,从 0 开始

limit

整数

要提取的实体数

id

字符串

联系人的 ID
exact match

fullName

字符串

联系人的全名
wildcard search

firstName

字符串

联系人的名字
wildcard search

lastName

字符串

联系人的姓氏
wildcard search

email

字符串

联系人的电子邮件 ID
wildcard search

phone

字符串

联系人的电话号码
wildcard search

mobile

字符串

联系人的手机号码
wildcard search

accountName

字符串

与联系人关联的客户的名称
wildcard search

customField1

字符串

联系人中的自定义字段
wildcard search
示例:customField1=mappedWithAccount:true

customField2

字符串

联系人中的自定义字段
wildcard search

customField3

字符串

联系人中的自定义字段
wildcard search

GET /api/v1/contacts/search

OAuth 作用域

Desk.contacts.READ 和 esk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/contacts/search?limit=1&lastName=Lawrence
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "zip" : null, "lastName" : "Lawrence", "country" : null, "modifiedTime" : "2016-05-04T09:57:17.000Z", "secondaryEmail" : null, "city" : null, "customFields" : { "permanentAddress" : null, "lastContactedOn" : null }, "facebook" : null, "mobile" : null, "description" : null, "title" : null, "type" : null, "ownerId" : "1892000000042001", "photoURL" : "https://desk.zoho.com/api/v1/contacts/1892000000042032/photo", "firstName" : null, "accountId" : "1892000000975382", "twitter" : null, "phone" : "1 888 900 9646", "street" : null, "createdTime" : "2013-11-04T11:21:07.000Z", "state" : null, "id" : "1892000000042032", "email" : "support@zohodesk.com", "account" : { "accountName" : "Zylker", "id" : "1892000000975382" } } ], "count" : 1 }

“任务搜索”API

此 API 在服务中心中搜索任务。可提供以逗号分隔的值,这表示将使用所提供的任一值对字段进行搜索。
Zoho Desk API 支持两种类型的搜索:exact matchwildcard match
仅当传递的值与服务中心中的资源完全匹配时,exact match 才会返回该资源。
即使传递的值与服务中心中的资源部分匹配,wildcard match 也返回该资源。
要执行 wildcard match,请在要搜索的值后面追加星号 (*)。

查询参数

参数名称
数据类型
描述
from

整数

起始索引,从 0 开始

limit

整数

要提取的实体数

departmentId

长整数

必须从中提取实体的部门的 ID。如果未传递此属性,将在允许的部门中搜索
exact match

subject

字符串

服务中心中任务的主题
wildcard search

ticketNumber

字符串

与任务关联的工单的工单号
exact match

status

字符串

任务的状态
exact match

priority

字符串

任务优先级
exact match

customField1

字符串

任务中的自定义字段
wildcard search

customField2

字符串

任务中的自定义字段
wildcard search

customField3

字符串

任务中的自定义字段
wildcard search

GET /api/v1/tasks/search

OAuth 作用域

Desk.tasks.READ 和 esk.search.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/tasks/search?limit=1&priority=High,Low
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "modifiedTime" : "2016-09-13T12:14:41.000Z", "ticket" : null, "customFields" : { }, "subject" : "Bug Fix #121", "completedTime" : null, "departmentId" : "3000000007043", "dueDate" : "2016-09-19T12:27:26.000Z", "creatorId" : "3000000008692", "description" : null, "ownerId" : "3000000054002", "priority" : "High", "isCommented" : false, "createdTime" : "2016-08-14T08:27:26.000Z", "assignee" : { "firstName" : "", "lastName" : "jade", "photoURL" : "https://contacts.zoho.com/file?t=user&ID=10657727", "emailId" : "jade@zylker.com", "id" : "5000000009116", "zuid" : "10657727" }, "id" : "3000000054004", "department" : { "name" : "Testing", "id" : "5000000007235" }, "category" : null, "ticketId" : null, "status" : "Not Started" } ], "count" : 1 }

邮件回复地址

邮件回复地址是指从其向客户发送回复的电子邮件 ID。

示例

{ "address" : "techsupport@zylker.com", "displayName" : "Tech", "departmentId" : "4000000007043", "id" : "4000000026003", "isActive" : true }



列出所有邮件回复地址

此 API 列出服务中心中配置的所有邮件回复地址。

查询参数

参数名称
数据类型
描述
departmentId

长整数

需要从中查询地址的部门

isActive

布尔型

回复电子邮件 ID 的激活状态

GET /api/v1/mailReplyAddress

OAuth 作用域

Desk.settings.READ 和 Desk.basic.READ

请求示例

$ curl -X GET https://desk.zoho.com/api/v1/mailReplyAddress?departmentId=4000000007043
  -H "orgId:2389290"
  -H "Authorization:Zoho-oauthtoken 1000.3d0a155402dbb59f776fd63adb1e67c0.a41ea557a6a8d7e402690098b2056f60s"

响应示例

{ "data" : [ { "address" : "support@zylker.com ", "displayName" : "Support", "departmentId" : "4000000007043", "id" : "4000000025003", "isActive" : true }, { "address" : "market@zylker.com", "displayName" : "Marketing", "departmentId" : "4000000007043", "id" : "4000000026001", "isActive" : false }, { "address" : "techsupport@zylker.com", "displayName" : "Tech", "departmentId" : "4000000007043", "id" : "4000000026003", "isActive" : true } ] }