Data can be exported to JSON or CSV.

API

The API to be used for export is:

GET https://api.voicegain.ai/v1/sa/call

It uses JWT token for authorization which has to be passed as Authorization: Bearer <JWT> header

The API method takes the following query parameters that may be relevant for exporting data (there are other query parameters but they are meant for use cases related to the Web UI):

• format
  string
  Default: "json"
  Enum: "json" "csv"
  Format of the Calls data to be returned:
  • json - returns data in json
  • csv - returns data it CSV file
• consecutive
  boolean
  Default: false
  If true then it will automatically do sorting ascending by callId. It will also stop export on the first call that it encounters which is not DONE or ERROR (i.e. still being processed). The next request will need to include afterCallId parameter that specifies highest callId not to be included in the export.
  Using sort_dir or sort_by parameters in conjunction with consecutive will return Bad Request error.
• afterCallId
  integer >= 0
  Example: afterCallId=11345
  CallId after which the export should continue. This is used in conjunction with consecutive=true parameter.
• fromTime
  string <date-time> <= 32 characters
  Example: fromTime=2020-07-21T00:00:00Z
  Start (the oldest value) of the time range for the query.
  Format as defined in RFC 3339, section 5.6
• toTime
  string <date-time> <= 32 characters
  Example: toTime=2020-07-21T19:32:28Z
  End (the newest value) of the time range for the query.
  Format as defined in RFC 3339, section 5.6
• aivrAppId
  Array of strings <uuid> [ items <uuid > [ 16 .. 48 ] characters ]
  Example: aivrAppId=736e7954-dc21-11ea-87d0-0242ac130030&aivrAppId=ah4e7954-dc21-71ea-87d0-0242ac130821
  Ids of AIVR Apps to query
• agentId
  Array of strings <uuid> [ items <uuid > [ 16 .. 48 ] characters ]
  Example: agentId=9d6e7954-dc21-11ea-87d0-0242ac130030&agentId=ge3e7954-dc21-71ea-87d0-0242ac130821
  Ids of Agents to query
• queueId
  Array of strings <uuid> [ items <uuid > [ 16 .. 48 ] characters ]
  Example: queueId=1a6e7954-dc21-11ea-87d0-0242ac130030&queueId=aa4e7954-dc21-71ea-87d0-1242ac130821
  Ids of Queues to query
• page
  integer >= 1
  Default: 1
  Example: page=1
  Which page from the results to include in response. Page numbering starts from 1.
  Note: we are not using offsets, so we assume that all pages have the same size as the current page.
• per_page
  integer [ 1 .. 10000 ]
  Default: 50
  Example: per_page=100
  What is the page size in paginated response.
  For more info see: Pagination
• sort_dir
  Array of strings
  Default: "asc"
  Items Enum: "asc" "desc"
  Example: sort_dir=asc&sort_dir=asc
  direction of sort - asccending or descending - elements must match the elements in sort_by
• sort_by
  Array of strings
  Default: "documentId"
  Items Enum: "time" "score" "documentId"
  Example: sort_by=time&sort_by=documentId
  By what value should the results be sorted (later we will add more sortable columns)

List of data columns

• accountId, e.g. f9f32f4b-845d-4110-8b9a-4f8eef06cfe5
• contextId, e.g. 17396f85-57b1-446c-874b-e40037998113 -- this is the project id
• callId, e.g. 14603
• startTime, e.g. 05-12-2024 6:15:45 PM
• endTime, e.g. 05-12-2024 6:20:30 PM
• duration, e.g. 274
• direction, e.g. inbound
• externalEndpoint, e.g. +14694519385 -- for inbound calls this is ANI
• internalEndpoint, e.g. 14693333606 -- for inbound calls this is DNIS
• recording, e.g. 49532709-1f2a-4e5b-a8c8-9e301c5a749d -- recording id (can be used to download the audio
• saSessionId, e.g. USDVDArvLUwoDZFzCLDs -- id of the speech analytics session
• agent.id, e.g. 436828 -- external agent user id, e.g. on Aircall
• agent.email, e.g. joe@voicegain.ai -- agent email
• agent.name, e.g. Joe Shmoe - agent name
• agent.userId, e.g. 4ed10e44-cdbd-4506-a2a0-f2eb6bf50933 - id of the agent user on the Speech Analytics App
• agent.channel, e.g. right -- channel in which agent audio is present
• queue.id, e.g. 873490 -- queue id
• queue.name, e.g. Q-English-Member-Services -- name of the queue
• sentiment, e.g. 0.25 - sentiment value
• crAnswersId -- if of the QA Form
• score -- Agent score from QA Form
• reviewStatus -- QA review status
• reviewNotes -- QA review notes
• notes -- call notes/summary (generated by LLM, may have new lines)
• tags, e.g. C_Member|NEW_TAG|V_Verified|R_Coverage
• keywords -- list of detected keywords
• topics -- list of detected intents
• isCallResolved -- true if the call resolved the issue (only present if call resolution detection configured)
• incidents -- count of incidents (e.g. overtalk) identified in the file
• wordCloud -- top 100 words
• numAudioChannels, e.g. 2
• numSpkChannels, e.g. 2
• version, currently 2
• aivrAppId -- id of the Voicebot app
• aivrSessionId - id of the Voicebot session
• originatingCallId -- will be there if this call was launched by voicebot
• progressPhase - processing phase of transcription and Speech Analytics (normally DONE or ERRROR)
• aivrTransferDestType, e.g. Internal or Agency
• callCenterCallId, e.g.  2444036749 -- id of the call continuation on the call center  (e.g. in Aircall)
• language e.g. en
• dtmfEvents -- list of DTMF events (if present)
• dailyRepeatCalls -- count of teh repeat calls from the same ANI in the past 24 hours
• markers, e.g. 201897,CC_AGENT_ANSWER,null|179162,CC_ANSWER,null - delineates different parts of the call

How to obtain JWT token

The token can be generated from Project Settings

Example of consecutive-export use case

A common use case is to use the API to regularly (daily, weekly, etc.) export all the data e.g. for the purpopse of importing it into a BI system or into a Database.

Let's assume that this export will be run weekly. We will need to store externally the highest previously exported callId - let'a call it  maxExportedCallId - this will be our input to the run each week ( first week we can start with 0).

Each Run would consists of the following steps:

1. Set pageNum variable to 1 and per_page to 1000
2. Loop until API request returns zero rows
3. In each Loop
   1. run GET https://api.voicegain.ai/v1/sa/call?format=csv&per_page=1000&page=pageNum&afterCallId=maxExportedCallId &consecutive=true
   2. if the returned CSV has no data rows then save newMaxExportedCallId for next run and exit
   3. otherwise,
      1. write the CSV data to a file
      2. find the highest callId (will be the bottom row) and assign it to newMaxExportedCallId ( to be used in 3.2.)
      3. increment pageNum value by 1,
      4. then go to step 3.1. (continue the loop)

Example python code is available on Voicegain Platform Github: platform/speech-analytics/reports at master · voicegain/platform