Guide to the integration of your own telephony in Omnidesk

Introduction

It is possible to integrate your own telephony system with the ticketsystem of Omnidesk with enterprise accounts. In this guide we will provide detailed instructions on how to achieve this. The following image provides an high level overview of the API calls and webhooks involved.

Inbound calls

API calls

The API calls can be used to update Omnidesk on the existence and status of calls. The callID is a call ID that can be used from your own telephone system. We require it matches our format: ^([\-a-zA-Z0-9]+)$.

post
newInboundCall

https://account.omnidesk.com/api/v2/telephone/newInboundCall
Register a new inbound call in the system. The call should be registered immediately, even if the call is still in the IVR.
Request
Response
Request
Form Data Parameters
telephoneNumberCalling
required
string
^([+0-9]+)$
telephoneNumberCalled
required
string
^([+0-9]+)$
callID
required
string
^([\-a-zA-Z0-9]+)$
pbxID
required
string
^([\-a-zA-Z0-9]+)$
pbxIP
required
string
^([\.0-9]+)
Response
200: OK
{}

post
callCreateTicket

https://account.omnidesk.com/api/v2/telephone/callCreateTicket
When the call is in the waiting queue a ticket should be created for the call.
Request
Response
Request
Form Data Parameters
callID
required
string
^([\-a-zA-Z0-9]+)$
pbxID
required
string
^([\-a-zA-Z0-9]+)$
pbxIP
required
string
^([\.0-9]+)$
variables
optional
object
{}
tags
optional
array
[]
skipAssignment
optional
boolean
true/false (todo)
Response
200: OK
{}

post
callUpdateTicket

https://account.omnidesk.com/api/v2/telephone/callUpdateTicket
This endpoint used used when you want to redirect a call to a different queue.
Request
Response
Request
Form Data Parameters
callID
required
string
^([\-a-zA-Z0-9]+)$
pbxID
required
string
^([\-a-zA-Z0-9]+)$
pbxIP
required
string
^([\.0-9]+)$
variables
optional
object
{}
tags
optional
array
[]
Response
200: OK
{}

post
updateCall

https://account.omnidesk.com/api/v2/telephone/updateCall
This method will update the call to a new state: failed, in-progress or completed.
Request
Response
Request
Form Data Parameters
pbxResponse
optional
string
pbx response for logging purposes, required when registerCallID = true
registerCallID
optional
boolean
true/false (true only for the first updateCall)
accountCallID
optional
integer
internal omnidesk id of the customer or agent call, this internal id was provided by omnidesk, in the case of outbound through the hookpoint keys: accountCallIDAgent and accountCallIDCustomer
agentID
optional
integer
^([0-9]+)$
callID
required
string
^([\-a-zA-Z0-9]+)$ your call id (for omnidesk external call id)
pbxID
required
string
^([\-a-zA-Z0-9]+)$
status
required
string
^failed|in-progress|completed$
Response
200: OK

post
assignCall

https://account.omnidesk.com/api/v2/telephone/assignCall
Assign a call to a user based on the userID or the mail address of the user. The response returns the user id of the user to which the call was assigned, this userID can be user later on in other requests. This also returns the internal call id of Omnidesk.
Request
Response
Request
Form Data Parameters
externalCallID
required
string
pbxID
required
string
userEmailAddress
required
string
Response
200: OK
{
"type": "result",
"message": "call assigned",
"userID": 1
}

post
updateStatus

https://account.omnidesk.com/api/v2/user/updateStatus
Request
Response
Request
Form Data Parameters
endWrapup
optional
boolean
true/false
userEmailAddress
optional
string
use the agent mail address if the userID is not available
lastInternalCallID
optional
integer
id of the last call, if applicable, will set the end wrapup time on the call record
statusID
required
integer
the status id
userID
optional
integer
Response
200: OK
{"status":"ok"}

Hookpoints

Omnidesk will provide information to the integration software to the hookpoints based on specific events.

post
userStatusUpdate

{{integration software url}}/userStatusUpdate
This hookpoint will be called (if configured) when the user status is updated in Omnidesk.
Request
Response
Request
Form Data Parameters
userEmailAddress
required
string
userID
required
string
statusIDPrevious
required
integer
statusIDNew
required
integer
Response
200: OK

post
endCall

{{integration software url}}/endCall
This hookpoint is called when the user clicks the end call button.
Request
Response
Request
Path Parameters
callID
required
string
Response
200: OK

post
muteCall

{{integration software url}}/muteCall
This hookpoint is called when the user clicks the mute/unmute button
Request
Response
Request
Form Data Parameters
mute
required
string
\(on|off)+
callIDCustomer
required
string
^\([0-9a-z\-])+$
callIDAgent
required
string
\([0-9a-z\-])+
Response
200: OK
done

post
createWarmTransfer

{{integration software url}}/createWarmTransfer
This method is invoked when the user wants to start a warm call transfer
Request
Response
Request
Form Data Parameters
callIDCustomer
required
string
a^([0-9a-z\-])+$
callIDAgent
required
string
^([0-9a-z\-])+$
accountCallIDTransferTo
required
string
^([0-9])+$ - a call ID you can create yourself
phoneNumberToTransferTo
required
string
^\\+([0-9])+$
agentID
required
string
^([0-9])+$
Response
200: OK

post
cancelWarmTransfer

{{integration software url}}/cancelWarmTransfer
This method is invoked when the user decides to cancel the warm transfer and wants to go back to the call with the customer.
Request
Response
Request
Form Data Parameters
callIDTransfer
required
string
^([0-9a-z\-])+$
callIDCustomer
required
string
^([0-9a-z\-])+$
callIDAgent
required
string
^([0-9a-z\-])+$
Response
200: OK

post
continueWarmTransferInboundCallingType

{{integration software url}}/continueWarmTransferInboundCallingType
This method is invoked when the user decides to continue the warm transfer and wants to transfer the call to the number that was provided to transfer to.
Request
Response
Request
Form Data Parameters
callIDTransfer
required
string
^([0-9a-z\-])+$
callIDCustomer
required
string
^([0-9a-z\-])+$
callIDAgent
required
string
^([0-9a-z\-])+$
Response
200: OK

post
redirectCall

{{integration software url}}/redirectCall
This method is invoked when the user decides to redirect the call to a new call flow.
Request
Response
Request
Form Data Parameters
callIDCustomer
required
string
([0-9a-z\-])+$
callIDAgent
required
integer
^([0-9a-z\-])+$
steps
required
string
call instructions (call flow)
Response
200: OK

Outbound calls

Hookpoints

post
createOutboundCallInbound

{{integration software url}}/createOutboundCallInbound
This hookpoint is called when the user initiated a new outbound call.
Request
Response
Request
Form Data Parameters
accountCallIDAgent
required
string
^([0-9])+$
accountCallIDCustomer
required
string
^([0-9])+$
agentNumber
required
string
^\\+([0-9])+$
customerNumber
required
string
^\\+([0-9])+$
agentID
optional
string
^([0-9])+$
ticketID
optional
string
^([0-9])+$
Response
200: OK
+OK {{external call id}}