Integration Description

Five9 is a cloud contact center platform hosted in Google Cloud Platform, while Cogito is a real- time speech analytics solution hosted in an AWS cloud environment.

Cogito Dialog is artificial intelligence software designed to provide real-time interactive guidance to service agents. For example, the software provides notifications to service agents to help them communicate more clearly, empathize with frustrated callers, and avoid long periods of silence thus improving their overall performance.

Cogito service is enabled by capturing the live media stream in Cogito Dialog using the Five9 VoiceStream application. The Five9 VoiceStream application provides CTI (Computer Telephony Integration) regarding the service agent calls and the media associated with the call is streamed via a Five9 proprietary extension to SIP. The SIP sessions use a fleet of Cogito Media Session Streamers (MSS) deployed in the Cogito AWS VPC. The application traffic between Five9 and Cogito is encrypted by TLS.

High Level Overview of Cogito-Five9 Solution

  1. Cogito deploys a dedicated AWS environment for the integration and exposes integration endpoints.
  2. Client works with Five9 and Cogito to enable VoiceStream application.
  3. Once Voicestream is enabled - the client creates a subscription in the VoiceStream application. This authorizes Cogito to call Five9 VoiceStream API and allows Five9 to provide telephony events to Cogito via REST API.
  4. Five9 SBC initiates the encrypted SIP session (SIP over TLS) and stream secured media (SRTP) to Cogito for call analysis.
  5. Telephony CTI events are collected for registered Cogito agents and sent to Cogito using webhook API.
  6. As Cogito processes call audio in real time, feedback is provided to agents via a web application. This is a HTML5 based application which is accessed through the agent’s browser or Desktop App.

Solution Architecture Diagram

Integration Points

CTI Event Monitoring

Five9 uses Cogito’s REST API to publish call events for Hold, Transfer, Consult and Conference.

A request payload from Five9 would include following attributes:

idthe identifier of the call
filterIdthe identifier of the associated filter
directioninbound or outbound
campaignthe campaign name
agentthe agent identifier
contactthe caller if known
stationIdthe station identifier

Once a call event is detected from an agent, Cogito will check whether such agent exists in Cogito and will respond with either answer to signal the desired media action:

IGNOREthe stream will not be started
ACCEPTthe stream will be started

This API runs from a serverless lambda function in central VPC to relay CTI events into selective Five9 customer accounts by dedicated Domain ID stored in dynamoDN. This lambda, aka. REST CTI Tracker, is protected by an AWS API Gateway instance. CTI events’ attributes are parsed, then forwarded as CTICallEvent messages to the Matcher service via a message broker.

Media Streaming

Audio Streaming is enabled by a client initiating the VoiceStream subscription by selecting the Cogito app from Five9 Admin portal

Through Five9’s VoiceStream Directives API, Cogito advertises SIP service targets. Five9 starts sending calls, regular SIP INVITEs over TLS, to those advertised endpoints with the trust token on a specific SIP header for authentication purposes. It is expected there are two separated SIP sessions initiated by Five9 per agent’s call. Each SIP session represents a dedicated audio channel, agent or customer, in the user dialog. Cogito will correlate these two calls into one with matching logic developed for this specific integration requirement based on a matched CallID.

The Cogito MSS server receives and processes this call signaling information, extracting pertinent data, which is reported to the Cogito matcher service for call “matching” purposes.


The call matching process is described in detail in the next section.

After the conditions of recording have been satisfied, audio is streamed to Cogito Compute service for analysis. Only then users will receive real-time behavioral guidance and coaching to help improve the caller experience. These notifications are conveyed to the users via an encrypted HTML5 based browser application.

VoiceStream Customer & Partner Flow

Call Matching

The call matcher uses two pieces of unique call data within each individual call. It compares these values to the CTI data that is also received by the matcher:

  • callid (CTI)
  • native_call_id (media)

The matcher will try to match native_call_id values received from media sessions to callid values received in CTI sessions.

If a match is found, the matcher then queries the User Management Database to see if the agent or extension that received the call is provisioned within the Cogito User Database.

  • If during this query an agent ID or extension match is found in the User Management database, the Cogito MSS server will respond 200 OK to activate the RTP steam and begin streaming the concerned media from the Cogito MSS server towards Cogito’s datastore and compute services.
  • If a match is not found in Cogito’s User Management database, MSS will not discard the media and this session will remain idle in the system until it is ended by the Five9’s network. Five9 will typically send a SIP BYE request in order to terminate the SIP session, or the session may simply timeout when Cogito’s timer is triggered.

User Management

Five9 provides an API accessible through the web to return their system setup information. There are two main API functions that are useful in helping to create dynamic user management via automation: getUsersInfo and getAgentGroups. These APIs are used by software which runs on a configurable periodic basis to pull data regarding the agents and agent hierarchy provisioned in Five9. The data is then normalized and accepted by Cogito’s AdminService before processing.

Prerequisites for Using Automated User Sync

  1. Each agent has a specific Cogito role assigned, e.g. “Agent” or “Supervisor”.
  2. A hierarchical supervisor to agent relationship is created using a group data structure with M:1 (many to one) relationship between agents and supervisor under the following conditions:
  • There should be one Agent Group per Supervisor team
  • Agent Group description must include the term “Cogito”
  • Only one Supervisor may be defined per group. Agent Groups with no Supervisor defined will not be processed.
  1. Client creates and shares a Five9 admin user account with Cogito to enable Five9 API access. Only ‘read-only’ permission is required to allow Cogito to pull data for user administration.

Automated User Sync Functionality

  • Cogito is integrated with the Five9 platform to import ‘Agent Groups’ representing teams.
  • New users added to Agent Groups will be imported into Cogito during the next scheduled user import.
  • Inactive users removed from “Agent Group” will be removed from Cogito during the next scheduled user import.
  • Cogito triggers user import periodically to ensure all new users from Five9 are added to Cogito’s user management system.
  • Import every 24 hours is recommended.
  • Cogito will be alerted if user import fails and can restart the process to add affected users.
  • Executive users currently can not be configured using automated sync with Five9. They can be added manually to Cogito using the manual solution.
Field NameValueDescription
adapterFive9adapter name
contactCenterFive9CCcontact center name
lobNameFive9LOBline of business name
organizationFive9Orgorganization name
siteFive9Sitesite name

Role mapping recommendation

User Role(s) assigned in Five9User Role assigned in Cogito
Administrator + Supervisor + AgentSupervisor
Administrator + SupervisorSupervisor
Administrator + AgentManager
Supervisor + AgentSupervisor

Manual User Management

Manual User Management is accomplished via a master .csv file of all users per the ‘Org file’ specifications provided and sent to Cogito CSM representative.

Customer Configuration Items

Configure VoiceStream Application

In order to allow Five9 to stream data to Cogito, the client must create a VoiceStream Subscription in the Five9 Web Admin Console. Clients authorize Cogito for their domain then select calls they would like Five9 to stream for guidance.

  1. Gain access to the admin interface with appropriate credentials
  2. Select "VoiceStream".
  1. Click "Create".

You will see a screen similar to the second one below.

  1. Select “All Calls” under “Streaming filter” if you wish to stream all calls to Cogito for analysis. Alternatively clients can select a “Custom Filter” and choose specific Campaigns or Agents.
    Select “Cogito Dialog” under “Streaming Destination”.
  1. Click on the “Services” icon. At this point the subscription should show as “Pending” under “VoiceStream Subscriptions”. The subscription will show as “Active” once the authorization process completes in the background.


It may take up to 10 minutes for the subscription to reflect as “Active”.

Configure Admin Account for User Management (optional)

In order to utilize automated user sync functionality the Client is required to create and share an admin user account to enable Five9 API access to ‘read-only’ permission. This will allow Cogito to pull data for user administration.

Client to username[email protected]
PermissionsLimited Permissions as shown below

The Cogito user account will require the following minimal permissions to be assigned:

  • No password expiration

The Administrator role will need to be assigned to our user account:

  • Check box: "User can use Administrator Services"

If NO agents or supervisors user accounts have the Administrator role assigned to them:

  • Select "Limited permissions"
  • Select "User can manage users, except administrator users"

If agents or supervisors user accounts have the Administrator role assigned to them:

  • Select "All administrator permissions" (User can edit other administrator users)

The following screenshot details the permissions that need to be assigned:

Client has to create one Agent Group per supervisor team. Individual Agent Groups has to be created with the following configuration:

  • Name: Sup_1 group_LOB (no restrictions)


Agent Group description must include the term “Cogito

Only one Supervisor has to be assigned per group. Agent Groups with no Supervisor user will not be processed.

We kindly ask the Client to gather supervisor team alignment with business & create separate agent groups for Cogito.

Please refer to the Automated User Sync Functionality section for the visual aids and role mapping recommendation.


Five9 VoiceStream Integration

VoiceStream Partner OAuth Guide - Developer’s Guide

VoiceStream Partner API - Developer’s Guide