The Euphoria API (Application Programming Interface) is a web service that can be interacted with other systems to achieve a number of tasks. Some of these tasks may be actions that the system can perform, such as dialling a number; or may be retrieving certain information for use in another system like a CRM application (hereafter referred to as the “target system”). The uses and business cases of interacting with APIs is very broad, but everything within the Euphoria platform is achieved via API, and this can in turn create some very meaningful applications for customers.


In order to achieve any level of integration between systems, both may need the ability to interact with each other via API, so find out what APIs the other system can offer before embarking on an integration project.


Integration is an advanced topic, and may require assistance from developers or systems engineers to configure.


Note: System webhooks usage is restricted to extensions that have agent functionality enabled.



Integration Centre


The Integration Centre has two main uses: 


  1. To send data to another system, this may be information such as numbers, call duration, attending agent or even call outcomes. 

  2. To query and retrieve information from the other system, often based on information available in the call such as the number calling in or supplied by an agent, such as a reference/ticket number.


In order to converse with the other system, the Integration Centre allows the creation of “webhooks”. A webhook is essentially a way to talk to an API on the other system for processing (whatever that may involve), which means it needs to understand (and be configured for) the way the API on the other system expects to interact. In order to achieve


In order to create webhooks, it is first necessary to create the ground rules for communication, these most often include parameters like authentication and the particulars should be available in the documentation of the other system. 



Groups

An administrator can create groups in the Integration Centre, so as to allow multiple webhooks to use the same parameters. 


When adding a group, an authentication type may need to be chosen. There are three authentication types: 


  1. None - this may be used if the target system does not support authentication or is using something IP authentication. 

  2. API Key - a password. 

  3. Credentials - a username and password. 


Once the authentication type is selected, the level of authentication will need to set. Authentication levels define whether the authentication will be on per-user basis or global. 

  • Global - a single set of credentials is used for all interaction with the target system. 

  • User - each user interaction with the target system will require individual credentials. A “Members” link will show up next to the group to allow the configuration of each individual set of credentials. 


Members

Members can be selected from the list of extensions that have been enabled as agents. Each member will need to have been allocated an API key/Credentials that has been provided by the target system.

 


Webhook

The format of the webhook will depend on the target system. When creating a webhook there are several fields that need to be considered and chosen.




  • Name - used to identify the webhook, it is useful to make this descriptive.

  • URL - the location of the web service on the target system, including page name. 

  • Parameters - data that is going to be sent to the target system, including variable names to identify components. These variables should be detailed in the target system’s documentation. Multiple variables and their accompanying parameters can be set by selecting the “+” button to add additional lines.

  • Test Value - to test whether the target system is responding as expected, test values may be set to gauge responses.  

  • Webhook Type

    • Browser Window:  Goes directly to the URL given by the target system, like opening a new tab) 

    • AJAX Get: Preferred when reading information. Data is sent in the  background, i.e. the agent will not see the action occur. 

    • AJAX Post: Same as “get”, however it is used to update or delete info.


  • Content Type: Format of the data being sent.

  • Response Type: How the target system wants the response to be handled.


When selecting the “Test and Configure” button, test values that have been set are sent to the target system, and the result is displayed. Often the result may contain many fields that are not essential to the current objective, by selecting checkboxes at the head of each column, the view that will be presented to the agent can be configured.



When selecting the  “Agent View”, a manager will be able to view what the agent will see as the end result. 



Note: Webhooks can not be deleted if in use. 



 Webhook Variables

Variable

Description

{CALLERID_NAME}

Name of the contact (calling/getting called)

{CALLERID_NUMBER}

The phone number of the contact (calling/getting called)

{CALLERID}

Output >> 
{CALLERID_NAME} <{CALLERID_NUMBER}@{PBX Server}>

Example Conrad <100@pbx0.euphoria.co.za>

{CALL_CRMTAG}

CRM tag of the call 

{CALL_DIR}

Direction of the call >> outgoing / incoming

{CALL_DISPOSITION}

The disposition agent selected for the call (Success, Unsure, Failed, Failed Contact). Hint: Failed = Failed Number 

{CALL_DURATION}

Total seconds of the call since answered 

{CALL_NOTES}

Notes agent wrote for the call 

{CALL_NUMBER}

The phone number of the contact (calling/getting called)

{CALL_OUTCOME}

The outcome agent selected for the call, can be system tags defined for the campaign/queue or admin definer. Example if Unsure >> the return can be “Voicemail”

{CALL_QUEUE}

The queue of the current call 

{CALL_SIPID}

SIP call ID of the current call - unique ID

{DATETIME_DATE}

Example: 2020-01-01_00-00-00

{DATETIME_TIME}

Example: 00-00-00

{DATETIME}

Example: 2020-01-01

{DYNAMIC_PARAMETER}

Used for webhook in webhook and can be anything

{EXTENSION_NO}

The extension number of the current agent. Example : 100

{EXTENSION}

Full extension username of the current agent. Example 100-Euphoria

 

API Manager

As described in the previous section, the Euphoria platform is controlled entirely by API actions, a customer may wish to interact directly with some of these actions from a platform outside of the TMS. Documentation on these actions is available, and the objectives should be discussed beforehand.


The API Manager page is simply for creating and managing API keys to be used by the other system in such inter-system communication.



API Monitoring

API Monitoring page is an audit log of API actions, including the date, user that initiated the API call, the action name that was called, and the duration it ran for. This information can be used for diagnostic purposes, and can be filtered by date range or action name.