PhoneBridge API Documentation
NAV

Introduction

Zoho Desk introduces the PhoneBridge API (Application Programming Interface) to integrate your PBX (Private Branch eXchange) system with Zoho Desk. Upon successful integration, the following functionalities will be enabled in your help desk account:


Getting Started

API Endpoint

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

Before you get started with the PhoneBridge API, you need register yourself as PBX vendor and integrate your Zoho Desk Account.

1. PBX Vendor Registration:

Please write to us at support@zohodesk.com so that we could register your PBX and assist you with integrating the system with Zoho Desk.


2. Integrating with Zoho Desk Account:

To integrate any Zoho Desk Account, please do the following:


Understanding Authentication

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/integrate" -X GET
-H Authorization: Zoho-OAuthtoken d92d401c80396c5cbhd09d0b4216f67
  

curl uses the -H flag to pass the OAuth credentials. Replace the sample OAuthtoken with your actual token to test requests from your help desk account. Note that, the OAuthtoken is valid only for 60 minutes from the time of generation.

Zoho Desk REST API supports OAuth protocol to enable users access data in a secured way.

Before making API Calls, please make sure that you authenticate using OAuth, so that you have the permission to access the API service.

The PhoneBridge API requires the following mandatory header:

Authorization - OAuthtoken request header.

Understanding HTTP Methods

Method Description
GET To retrieve data from the given server.
POST To insert or upload any new resource to the server.
PUT To update an existing resource. This replaces the target resource with the updated content.
DELETE To delete a resource at a particular location.

Each resource in Zoho Desk is accessed using standard HTTP methods such as GET, POST, PUT and DELETE, which are used to read, create, update and delete resources respectively. Please note that, all the response and requests will be in JSON format (JSON object).

Understanding HTTP Status Codes

Status Codes Meaning Description
200 OK The API request is successful.
204 NO CONTENT There is no content available for the request.
400 BAD REQUEST The request is considered to be invalid.
401 AUTHORIZATION ERROR Invalid authtoken provided.
403 FORBIDDEN No permission to do the operation.
404 NOT FOUND Invalid request.
405 METHOD NOT ALLOWED The specified method is not allowed.
500 INTERNAL SERVER ERROR Generic error that is encountered due to an unexpected server error.

Zoho PhoneBridge API uses HTTP status codes to specify the success or failure of an API request.

Enable/disable Integration


Example Request:

To enable Telephony integration,

"curl "https://desk.zoho.com/phonebridgeapi/v1/integrate" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

StatusCode:HttpStatus.SC_OK(200)

{ "message": "(PBX Name) Integration is successful" "status": "success", "code": "SUCCESS", }

Example Request:

To disable Telephony integration,

"curl "https://desk.zoho.com/phonebridgeapi/v1/integrate" -X DELETE -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

StatusCode:HttpStatus.SC_OK(200)

{ "message": "(PBX Name)Integration has been successfully removed" "status": "success", "code": "SUCCESS", }

Error Responses:

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent, if the telephony integration is not accessible for the current user's license.

{ "message": "PBX Integration is not available for your license type" "status": "error", "details": {}, "code": "NO_PERMISSION", }

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent, if the requested user does not have enough permission to perform the PhoneBridge integration.

{ "message": "Requested user doesn't have enough privilege in Zoho Desk to enable PhoneBridge integration" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following response is sent, if the PhoneBridge registration information is not available for the PBX vendor name that is obtained from the OAuth Token object.

{ "message": "(PBX Name) is not registered" "status": "error", "details": {}, "code": "PBX_NOT_REGISTERED", }

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response is sent, if the same PBX integration has already been enabled for the account.

{ "message": "(PBX Name) has been already enabled for the Account" "status": "error", "details": {}, "code": "PBX_ALREADY_ENABLED", }

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response is sent, if a different PBX integration has been enabled for the account already.

{ "message": "Different PBX has been enabled for the Account" "status": "error", "details": {}, "code": "DIFFERENT_PBX_ALREADY_ENABLED", }

Purpose

To enable/disable the PBX vendor integration within Zoho Desk.

Request URL

https://desk.zoho.com/phonebridgeapi/v1/integrate

Request Method

POST - To enable integration

DELETE- To disable integration

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.

* - Mandatory parameters

Enable/disable clicktocall & call control

Example Request:

To enable clicktocall and call control,

"curl "https://desk.zoho.com/phonebridgeapi/v1/clicktocallandcallcontrol" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

StatusCode:HttpStatus.SC_OK(200):

The following response is sent when callcontrol is enabled for the account successfully.

{ "message": "(PBX Name) Call control notifications has been enabled for the account
successfully"
"status": "success", "code": "SUCCESS", }

Example Request:

To disable clicktocall and call control,

"curl "https://desk.zoho.com/phonebridgeapi/v1/clicktocallandcallcontrol" -X DELETE -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

StatusCode:HttpStatus.SC_OK(200):

The following response is sent when callcontrol and clicktocall is disabled for the account.

{ "message": "(PBX Name) Call control notifications has been disabled for the account successfully" "status": "success", "code": "SUCCESS", }

Error Responses:

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent if the telephony integration is not accessible for the current user's license.

{ "message": "PBX Integration is not available for your license type" "status": "error", "details": {}, "code": "NO_PERMISSION", }

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent in case there is an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent, if the callcontrol parameters has been sent and the requested user does not have enough permission to perform the PhoneBridge integration.

{ "message": "Requested user doesn't have enough privilege to perform this process" "status": "error", "details": {}, "code": "NO_PERMISSION", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following response is sent, if the PhoneBridge registration information is not available for the PBX vendor name that is obtained from the OAuth Token object.

{ "message": "(PBX Name) is not registered" "status": "error", "details": {}, "code": "PBX_NOT_REGISTERED", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response is sent, if the PBX vendor integration information is not available.

{ "message": "(PBX Name) Integration is not enabled" "status": "error", "details": {}, "code": "PBX_NOT_INTEGRATED", }

Purpose

To enable or disable the clicktocall and call control functionality for the users. We will post the call details to the clicktocall API whenever an agent uses clicktocall button to initiate an outbound call from within Zoho Desk. Vendors can also send the call functionality URLs such as clicktocallurl, answerrul, hungupurl, muteurl, unmuteurl, holdurl, unholdurl, and keypressurl as parameters in this API. Please note that, these parameters has to be sent in URL format.

Request URL

https://desk.zoho.com/phonebridgeapi/v1/clicktocallandcallcontrol

Request Method

POST - To enable clicktocall and call control notifications

DELETE - To disable clicktocall and call control notifications

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
clicktocallurl To be used for the clicktocall functionality. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/clicktocall
answerurl To send a request to answer the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/answerurl
hungupurl To send a request to hungup the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/hungupurl
muteurl To send a request to mute the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/muteurl
unmuteurl To send a request to unmute the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/unmuteurl
holdurl To send a request to hold the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/holdurl
unholdurl To send a request to unhold the call. It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/unholdurl
keypressurl To send the details about the keys/digits pressed during the call.It has to be sent in URL format as shown below:
https://api.pbx.com/zoho/keypressurl
userid If you want to enable clicktocall and call control for multiple users, you have to pass the userid parameter in your API request. Userid is the id of the Zoho Desk user who is making the outbound call. You can send multiple userids as a comma seperated string. Both incoming and outgoing notifications will be enabled for the mentioned users.
authorizationparam authorization param contains the name and value pairs in JSON format. Example: {name:param/header name,value:token value}
clicktocallparam

It is a parameter in the JSON array format with name and value pairs. This param can be used when you want to send any custom parameters while calling the clicktocall API. You are allowed to send any number of names and value pairs using clicktocallparam.

Example: [{name:pbxuserid,value:pbxuser1234}, {name:emailaddress,value:xyz@pbx.com}]
callcontrolparam

It is a parameter in the JSON array format with name and value pairs. This param can be used when you want to send any custom parameters while calling the callcontrol APIs. You are allowed to send any number of names and value pairs using callcontrolparam.

Example: [{name:pbxuserid,value:pbxuser1234}, {name:emailaddress,value:xyz@pbx.com}]

* - Mandatory parameters

Incoming Call APIs

Call received

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callreceived" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId", "accountId": "AccountId", "accountName": "AccountName", "happinessRatingPercentage": "HappinessRatingPercentage", "email": "Email Address", "phone": "PhoneNumber", "mobile": "Mobile Number" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify an inbound call when the destination phone rings

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callreceived

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
transfercallrefid This is the unique caller id of the transferred call.

* - Mandatory parameters

Call answered

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callanswered" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify when a destination client/agent/phone answers the call

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callanswered

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.

* - Mandatory parameters

Call hungup

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callhungup" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify when a call is hungup or has ended

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callhungup

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
callstarttime* The start time of the incoming call. The callstarttime should be in yyyy-MM-dd HH:mm:ss format. For example, 2016-09-20 15:09:10.
direction* Set the value as inbound.
duration* Call recording duration in seconds.
voiceurl URL of the audio file where the voicemessage s available.

* - Mandatory parameters

Call missed

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callmissed" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400) :

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify when a call is missed

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callmissed

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
callmissedtime* Time when the call is missed. (Date-Time Format: yyyy-MM-dd HH:mm:ss. For example, 2016-09-20 15:09:10)
voicemailurl voicemailurl has the file path of the voicemail i.e., URL of the audio file where the voice message is available.
sequential

To indicate whether there is a need to create a ticket. Ticket will be created in case if a call is missed.

sequential = true
If a user is unavailable, then the call will be forwarded to the next user. Sequential = true will be sent only if the call is forwarded to the next available user. Ticket will not be created if sequential = true

sequential = false
Ticket will be created, since the call has not been answered by any user.

* - Mandatory parameters

Outgoing Call APIs

Call dialed

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/calldialed" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId", "accountId": "AccountId", "accountName": "AccountName", "happinessRatingPercentage": "HappinessRatingPercentage", "email": "Email Address", "phone": "PhoneNumber", "mobile": "Mobile Number" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify an outbound call when the destination phone rings or is about to ring

Request URL

https://desk.zoho.com/phonebridgeapi/v1/calldialed

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
agentstatus* Status of the sales agent's phone number. The agentstatus can be any of the following:
success - The agent has successfully connected the call.
notavailable - The agent number is not available.
rejected - The call has been rejected by the agent.
noanswer - The call has ended without being answered by the agent.
busy - Agent phone is busy.
internationaldisabled- International connection is disabled.
notenoughfunds - No sufficient funds to make the call.
blocked - The call is blocked.
customerstatus* Status of the call made to your customer. The customerstatus can be any of the following:
success - The customer has successfully answered the call.
inprogress - The call was answered and is in progress currently.
notavailable - The customer is not available to answer the call.
rejected - The customer has rejected the call.
noanswer - The call has ended without being answered by the customer.
busy - The caller has received a busy signal.
blocked - The caller has been blocked
invalid - The call made was invalid.

* - Mandatory parameters

Call hungup

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callhungup" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName ", "id": "EntityId" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify when a call is hungup or has ended

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callhungup

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
callstarttime* The start time of the call. The callstarttime should be in yyyy-MM-dd HH:mm:ss format. For example, 2016-09-20 15:09:10.
direction* Set the value as outbound.
duration* Call recording duration in seconds.
voiceurl URL of the audio file where the voicemessage is available.

* - Mandatory parameters

Outgoing using clicktocall APIs

Call dialed

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/calldialed" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId", "accountId": "AccountId", "accountName": "AccountName", "happinessRatingPercentage": "HappinessRatingPercentage", "email": "Email Address", "phone": "PhoneNumber", "mobile": "Mobile Number" } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify an outbound call when the destination phone rings or is about to ring

Request URL

https://desk.zoho.com/phonebridgeapi/v1/calldialed

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
agentstatus*

Status of the sales agent's phone number. The agentstatus can be any of the following:

success
The agent has successfully connected the call.
notavailable
The agent number is not available.
rejected
The call has been rejected by the agent.
noanswer
The call has ended without being answered by the agent.
busy
Agent phone is busy.
internationaldisabled
International connection is disabled.
notenoughfund
No sufficient funds to make the call.
blocked
The call is blocked.

customerstatus* Status of the call made to your customer. The customerstatus can be any of the following:
success
The customer has successfully answered the call.
inprogress
The call was answered and is in progress currently.
notavailable
The customer is not available to answer the call.
rejected
The customer has rejected the call.
noanswer
The call has ended without being answered by the customer.
busy
The caller has received a busy signal.
blocked
The caller has been blocked
invalid
The call made was invalid.

* - Mandatory parameters

Call hungup

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/callhungup" -X POST -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "data": [ { "fullName": "EntityName", "module": "ModuleName", "id": "EntityId", } ] }

Error Responses:

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case of an exception while processing the request.

{ "message": "Internal server error" "status": "error", "details": {}, "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response will be sent, if all the mandatory parameters are not sent in the API request.

{ "message": "One of the expected parameters is missing" "status": "error", "code": "REQUIRED_PARAM_MISSING", "details": {"param":"id"}, }

Purpose

To notify when a call is hungup or has ended

Request URL

https://desk.zoho.com/phonebridgeapi/v1/callhungup

Request Method

POST

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.
callrefid* A unique caller id generated by the PBX vendor. The callrefid should be sent in the format shown below:
callid123456
fromnumber* Contact number of the Agent or Customer based on the call state. The fromnumber should be sent in the phone number format. For example: 0018885554567
tonumber* Contact number of the Agent or Customer based on the call state. The tonumber should be sent in the phone number format. For example: 0018885556748
userid It is the unique id of the Zoho Desk user.
callstarttime* The start time of the call. The callstarttime should be in yyyy-MM-dd HH:mm:ss format. For example, 2016-09-20 15:09:10.
direction* Set the value as outbound.
duration* Call duration in seconds.
voiceurl URL of the audio file where the voicemessage s available.

* - Mandatory parameters

Get Active Users List

Users

Example Request:

"curl "https://desk.zoho.com/phonebridgeapi/v1/users" -X GET -H Authorization: Zoho-oauthtoken d92d401c80396c5cbhd09d0b4216f67

Example Response:

{ "users": [ { "userid": "useridvalue", "username": "user full name" }, { "userid": "useridvalue", "username": "user full name" } ] }

Error Responses:

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent, if the telephony integration is not accessible for the current user license.

{ "message": "PBX Integration is not available for your license type" "status": "error", "details": {}, "code": "NO_PERMISSION", }

StatusCode:HttpStatus.SC_INTERNAL_SERVER_ERROR(500):

The following error response will be sent, in case there is an exception while processing the request.

{ "message": "Internal server error" "status": "error", "code": "INTERNAL_ERROR", }

StatusCode:HttpStatus.SC_FORBIDDEN(403):

The following error response will be sent, if the callcontrol parameters has been sent and the requested user does not have enough permission to perform the PhoneBridge integration.

{ "message": "Requested user doesn't have enough privilege to perform this process" "status": "error", "details": {}, "code": "NO_PERMISSION", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following response is sent, if the PhoneBridge registration information is not available for the PBX vendor name that is obtained from the OAuth Token object.

{ "message": "(PBX Name) is not registered" "status": "error", "details": {}, "code": "PBX_NOT_REGISTERED", }

StatusCode:HttpStatus.SC_BAD_REQUEST(400):

The following error response is sent, if the PBX vendor integration information is not available.

{ "message": "(PBX Name) Integration is not enabled" "status": "error", "details": {}, "code": "PBX_NOT_INTEGRATED", }

Purpose

To retrieve all users specified in the API request.

Request URL

https://desk.zoho.com/phonebridgeapi/v1/users

Request Method

GET

Parameters

Parameter Description
Zoho-oauthtoken OAuthToken* Encrypted alphanumeric string to authenticate your Zoho credentials.

* - Mandatory parameters