The Euphoria API (Application Programming Interface) is a web service that can be interacted with by other systems to achieve several tasks. Some of these tasks may be actions that the system can perform, such as dialling a number; or maybe 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 API’s are vast, but everything within the Euphoria platform is achieved via API, and this can, in turn, create some very meaningful applications for customers.


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 include 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.


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) how the API on the other system expects to interact. 


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 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: 

  • None: This may be used if the target system does not support authentication or is using something like IP authentication. 
  • API Key: A password. 
  • Open OAuth 2: Is an open standard for access delegation, commonly used for allowing third-party applications to access resources on a user's behalf, without exposing their credentials. An example of this, is being able to sign up to a new website with Google credentials.
  • Credentials: A username and password. 


Once the authentication type is selected, the level of authentication will need to be set. Authentication levels define whether the authentication will be on a 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” button 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 the target system has provided.

 

Webhook

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


  • Name: Used to identify the webhook; it is useful to make this descriptive.

  • 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 insert info.

    • AJAX Put: Same as “get”; however it is used to update.

    • AJAX Delete: Same as “get”; however it is used to delete info.

    • Both browser window and AJAX Get: Triggers both browser window new tab and Ajax get.


  • Webhook Data Type:

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

    • JOSN: (JavaScript Object Notation) is a lightweight data-interchange format.

    • XML: (Extensible Markup Language) is a markup language that defines a set of rules for encoding documents.


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

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

  • Parameters: Data that will 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 responds as expected, test values may be set to gauge responses.  


Webhook Variables/Dynamic Parameters

Dynamic Parameters can be added when selecting the add request parameter button. These variables are found in the target system’s API documentation.


Parameter

Variable

Description

Agent Extension

{EXTENSION}

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

Extension Number

{EXTENSION_NO}

The extension number of the current agent. Example: 100

Call Direction

{CALL_DIR}

The direction of the call >> outgoing / incoming

Caller ID

{CALLERID}

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

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

Call Date & Time

{DATETIME}

Example: 2020-01-01

Call Date

{DATETIME_DATE}

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

Call Time

{DATETIME_TIME}

Example: 00-00-00

Caller ID Name

{CALLERID_NAME}

Name of the contact (calling/getting called).

Caller ID Number

{CALLERID_NUMBER}

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

Call Duration

{CALL_DURATION}

Total seconds of the call since answered.

Call SIP ID

{CALL_SIPID}

SIP call ID of the current call - unique ID.

Initial Call SIP ID

{CALL_ORIGSIPID}

Initial SIP call ID of the current call - unique ID.

Call Unique ID

{UNIQUEID}


The euphoria generated unique ID of the call.

Call Ring Time

{CALL_RINGTIME}

The time of ringing of the call.

Call Caller ID

{CALL_CALLERID}

The caller ID used for the call.

CRM Tag

{CALL_CRMTAG}

CRM tag of the call.

Agent Notes

{CALL_NOTES}

Notes agent wrote for the call.

Call Disposition

{CALL_DISPOSITION}

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

Call Outcome

{CALL_OUTCOME}

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

Queue

{CALL_QUEUE}

The queue of the current call.

Number

{CALL_NUMBER}

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

Number-No Prefix

{CALL_NUMBER_NOPREFIX}

The phone number of the call without the prefix.

Dynamic

{DYNAMIC_PARAMETER}

Used for webhook in webhook and can be anything.

Agent Input 1

{AGENT_INPUT_1}

The system will ask the agent to enter data before triggering the webhook.

Agent Input 2

{AGENT_INPUT_2}

The system will ask the agent to enter data before triggering the webhook.

Agent Input 3

{AGENT_INPUT_3}

The system will ask the agent to enter data before triggering the webhook.

Agent Input 4

{AGENT_INPUT_4}

The system will ask the agent to enter data before triggering the webhook.

Agent Input 5

{AGENT_INPUT_5}

The system will ask the agent to enter data before triggering the webhook.

Auth API Key

{API_KEY}

This Will be replaced by the group/user authentication API key

Auth Username

{USERNAME}

This Will be replaced by the group/user authentication username. 

Auth Password

{PASSWORD}

This Will be replaced by the group/user authentication password.



Once all parameters have been chosen and set, press 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 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. 


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 simply creates and manages 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.



Articles Related “How To” Document Links:

API Manager: How to Set Up an API Key.

API - Euphoria Public API Site

Can a webhook be activated during a call?

How to Create a Webhook.

Integration Center: How to Create an Integration Group.