API - Historical Data

How to use Omni APIs

This document will show, in a practical and explanatory way, how to use the Omni APIs, which are available at the following link: https://docs-history.omni.digitalcontact.cloud/.

Authentication

To use the Omni API, you must first perform authentication. For this, you need to copy the x-api-key located in the channels menu within Omni. After that, simply click the Copy API Key button, as shown in the screenshot below:

With the key copied, you need to access the Omni APIs through this link: https://docs-history.omni.digitalcontact.cloud/.
After that, simply click the Authorize button and paste the key into the api_key field.
Below are the screenshots with the step-by-step process:

Login APIs

Currently, there are two login APIs. The /Login/loginApi is required to execute requests from the contact or integration module, and the /Login/organization is used to execute report requests.

Login - Contact or Integration

This API expects two variables: login and password.
To execute the API, you need to click on the /Login/loginApi field and then on the Try it out button:

After entering these data, simply click Execute, and the API will return the organizations associated with your user, as shown in the example below:

If the goal is to execute the contact or integration APIs, just copy the token into the Authorization field and add Bearer followed by a space before the token.
After that, it is necessary to click the Authorize button, as shown in the screenshot below:

All set — now it will be possible to use all the contact/integration APIs that are available.

Login - Reports

To execute the report APIs, we need to copy the organization ID from the /Login/loginApi API and then select the /Login/organization API, clicking again on the Try it out button:

This API expects the login, password, and the organization ID that was copied earlier.
After entering these data, simply click Execute, and the API will return the token and the organization data, as shown in the example below:

In this case, we only need the token. After copying the token, we can return to the Authorize menu, where we previously placed the api_key.
Now simply paste the token into the Authorization field and add Bearer followed by a space before the token.
After that, it is necessary to click the Authorize button, as shown in the screenshot below:

All set — now it will be possible to use all the report APIs that are available.
In addition, here is a video demonstrating all the steps mentioned earlier:

Main routes: service-history, voice-log, and service-history-audio-links

The main routes are as follows:

• service-history
  • Captures data from all attendances between the dates specified in the request.
• voice-log
  • Returns data from inbound and outbound calls between the dates specified in the request.
• service-history-audio-links
  • Route that allows obtaining the link to recordings of attendances carried out on the platform, between the dates specified in the request.

Service-history

The service-history route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture other attendances.
• date_ini
  • The initial date the API will consider when searching for attendances. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for attendances. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each attendance. Below is the definition of each returned attribute:

• Total
  • Total number of documents found.
• Page
  • Value entered in the “report_skip” field when generating the data for the response.
• Data
  • List of all information found within the previously defined parameters.
  • agente
    • Name of the user/agent who received the attendance.
  • agent
    • Email of the user/agent.
  • cliente
    • Client identifier (phone number, email, bot ID, etc.).
  • contato
    • Contact name.
  • data_inicio
    • Date and time the attendance was received. For chat media, it is the entry time into Omni.
  • data_atendida
    • Start date of the attendance between client and agent. For chat media, it is the date/time of the agent’s first interaction.
  • data_fim
    • End date of the attendance.
  • data_primeira_resposta
    • Date of the agent’s first response.
  • midia
    • Media code in which the attendance was carried out. Common codes:
      • 1 - Voice
      • 2 - Chat
      • 3 - Email
      • 4 - WhatsApp
      • 5 - Facebook/Messenger
      • 12 - Instagram
      • 17 - Consumidor Gov
  • portfolio
    • Indicates whether the attendance is portfolio-based or not.
  • protocolo
    • Unique identifier of the attendance.
  • ramal
    • Agent’s extension.
  • serviço
    • Name of the service used for the attendance.
  • documento_cliente
    • Client’s CPF or CNPJ.
  • status
    • Call status.
  • tag
    • Name of the tag or tabulation used to finalize the attendance.
  • recebida
    • Interaction flow.
  • comentarios_internos
    • Internal comments about the attendance.
  • id
    • Key used internally.

To access this route, simply go to the /ReportsApi/service-history field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

This is an example of API service-history:

Voice-log

Just like the service-history route, the voice-log route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture other calls.
• date_ini
  • The initial date the API will consider when searching for calls. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for calls. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each call performed. Below is the definition of each returned attribute:

• Total
  • Total number of documents found.
• Page
  • Value entered in the “report_skip” field when generating the response.
• Data
  • List of all information found within the previously defined parameters.
  • data_inicio — Date and time the attendance was received
  • data_atendida — Start date of the attendance between client and agent
  • data_primeira_resposta — Date of the agent’s first response
  • data_fim — End date of the attendance
  • serviço — Name of the service used for the attendance
  • agente — Name of the user/agent who received the attendance
  • agent — Email of the user/agent
  • ramal — Agent’s extension
  • contato — Contact name
  • status — Call status
  • portfolio — Indicates whether the attendance is portfolio-based or not
  • tipo — Classification of the call type (inbound or outbound)
  • integração — Type of integration
  • src_voice_log — Source
  • from_voice_log — Source identifier
  • type_voice_log — Call type (inbound or outbound)
  • voice_internal_status — Internal call status
  • ipbx_external_endpoint — External endpoint
  • ipbx_dialed_string — Dialed value
  • ipbx_external_callerid — External ID
  • ipbx_external_channel_id — External channel ID
  • ipbx_external_channel_desc — Description of external channel ID
  • ipbx_external_channel_creationtime — External channel creation time
  • ipbx_internal_channel_creationtime — Internal channel creation time
  • service_flow_type_did — DID flow
  • ipbx_internal_channel_desc — Description of internal channel ID
  • ipbx_internal_channel_id — Internal channel ID
  • feature_request_type — Request type
  • transfer_result — Transfer result
  • protocolo — Unique identifier of the attendance
  • comentarios_internos — Internal comments about the attendance
  • respostas_pesquisas
    • questão — Title of the answered question
    • score — Answer score
    • status — Answer status
    • data_encerramento — Date the answer was finalized
    • id — Primary key of the answer
  • id — Primary key

To access this route, simply go to the /ReportsApi/voice-log field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

Here is an example of the return from the voice-log API:

Service-history-audio-links

Just like the service-history and voice-log routes, the service-history-audio-links route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture other attendances.
• date_ini
  • The initial date the API will consider when searching for attendances. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for attendances. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each attendance. Below is the definition of each returned attribute:

• Total
  • Total number of documents found.
• Page
  • Value entered in the “report_skip” field when generating the response.
• Data
  • List of all information found within the previously defined parameters.
  • _id — Interaction ID
  • data_inicio — Date and time the attendance was received
  • data_atendida — Date and time the attendance started
  • data_fim — Date and time the attendance ended
  • cliente — Client identifier
  • contato — Contact
  • agente — Agent name
  • agent — Agent’s email
  • servico — Service
  • ramal — Extension
  • origem — Inbound/Outbound
  • protocolo — Attendance protocol
  • status — Call status
  • documento — Client’s CPF or CNPJ
  • tag — Tag or tabulation name used to finalize the attendance
  • download_url — File link (only for status Contact — attended call)
  • id — Primary key

To access this route, simply go to the /ReportsApi/service-history-audio-links field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

Here is an example of the return from the service-history-audio-links API:

In addition, below is a video explaining how to execute the previously mentioned routes:

Login and Pause Report: activity-history

Just like the other report routes, the activity-history route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture user logins/logouts.
• date_ini
  • The initial date the API will consider when searching for user logins/logouts. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for user logins/logouts. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each login and pause. Below is the definition of each returned attribute:

• Total
  • Total number of documents found.
• Page
  • Value entered in the “report_skip” field when generating the response.
• Data
  • List of all information found within the previously defined parameters.
  • agent_id — Agent ID, for internal use
  • agente — User name
  • agent — User email
  • evento — Type of action taken (Login or Pause)
  • data_inicio — Start date and time of the event
  • data_fim — End date and time of the event
  • id — Identifier for internal use

If there are customized pauses configured in Omni, the pause name will be returned in the evento field, provided that a user has registered that pause.

To access this route, simply go to the /ReportsApi/activity-history field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

Here is an example of the return from the activity-history API:

Below is a video explaining how to execute the activity-history route:

Satisfaction Survey Report: satisfaction-survey-history

This request returns all surveys assigned to attendances within the specified date. Just like the other report routes, the satisfaction-survey-history route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture the remaining surveys.
• date_ini
  • The initial date the API will consider when searching for satisfaction surveys. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for satisfaction surveys. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each satisfaction survey. Below is the definition of each returned attribute:

• Total — Total number of documents found.
• Page — Value entered in the “report_skip” field when generating the response.
• Data — List of all information found within the previously defined parameters.
  • data_inicio — Date and time the survey response was received
  • data_fim — Date and time the survey response ended
  • data_completado — Date and time the survey response was completed
  • media_type — Media type (1 - Voice, 2 - Chat, 4 - WhatsApp)
  • voice_type — For voice calls, inbound or outbound
  • research_type — CSAT or NPS
  • question_id — Question identifier for internal use
  • score — Survey score
  • completed — Whether the survey was completed (yes or no)
  • satisfaction_nps_level — NPS level
  • calculation_type — Calculation type
  • satisfaction_level — Satisfaction level
  • status — Response status
  • protocolo — Attendance protocol
  • questão — Title of the answered question
  • agente — Agent name
  • agent — Agent email
  • contato — Contact name/code/identifier
  • id — Unique key for internal use

To access this route, simply go to the /ReportsApi/satisfaction-survey-history field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

Here is an example of the return from the satisfaction-survey-history API:

Below is a video explaining how to execute the satisfaction-survey-history route:

Attendance Message History: service-history-messages

This request returns all attendances and their associated messages within the specified date. Just like the other report routes, the service-history-messages route expects three variables, explained below:

• report-skip
  • Defines which page of documents the API will return. By default, the value is 0. The API returns 1000 documents per page, so it is necessary to increase this value to capture the remaining records.
• date_ini
  • The initial date the API will consider when searching for attendances. The route accepts two date formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 00:00:00.
• date_end
  • The final date the API will consider when searching for attendances. Like date_ini, it accepts two formats, with or without a defined time. Examples: 2024-12-31, 2024-12-31 23:59:00.

After the request is made, the API will return a set of information for each interaction. Below is the definition of each returned attribute:

• Total — Total number of documents found
• Number of pages — Total number of pages
• Page — Value entered in the “report_skip” field when generating the response
• Data — List of all information found within the previously defined parameters
  • data_inicio — Date and time the interaction started
  • data_atendida — Date and time the interaction was assigned to the agent
  • data_fim — Date and time the attendance ended
  • contato — Contact
  • agente — Agent name
  • agent — Agent email
  • servico — Service
  • media_type — Media type (2 - Chat, 3 - Email, 4 - WhatsApp, 5 - Facebook/Messenger, 12 - Instagram, 17 - Consumidor Gov)
  • protocolo — Attendance protocol
  • mensagens
    • recebida — Field will be true if the message is from the client
    • send_time — Date and time the message was sent
    • message — Message content
    • media — If any media is attached to the message, it will appear in this field
    • message_type — Message type
  • id — Unique attendance identifier

To access this route, simply go to the /ReportsApi/service-history-messages field and click the “Try it out” button:

After entering the data, simply click the Execute button located just below the panel:

Here is an example of the return from the service-history-messages API:

---