--- title: "Versão 1.10 - API de integração Hi Platform" slug: "api-de-integracao-hi-platform" updated: 2024-10-01T15:06:13Z published: 2024-10-01T15:06:13Z canonical: "help.hiplatform.com/api-de-integracao-hi-platform" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.hiplatform.com/llms.txt > Use this file to discover all available pages before exploring further. # Versão 1.10 - API de integração Hi Platform ## API de integração da Hi Platform Versão 1.10 ### **Endereço base** - URL: `https://api.directtalk.com.br/1.10/` ## **Autenticação/Autorização** A *Hi Platform* irá fornecer um usuário e uma senha de acesso exclusivo para o uso da *API*. [Saiba mais.](https://help.hiplatform.com/docs/gestao-de-usuarios-de-api) A autenticação da *API* será feita utilizando o protocolo [Basic](https://en.wikipedia.org/wiki/Basic_access_authentication). Vamos descrever brevemente o como autenticar usando o protocolo *Basic*. Considere hipoteticamente que o usuário da *API* passado é `usuarioApi` e a senha é `senhaApi`. Primeiro, calcule um token da seguinte forma: - Concatene o usuario e a senha separado por `:`. No nosso exemplo `usuarioApi:senhaApi`; - Codifique o resultado acima utilizando o formato [Base64](https://pt.wikipedia.org/wiki/Base64). No nosso exemplo o exemplo o resultado (*token*) dessa operação é `dXN1YXJpb0FwaTpzZW5oYUFwaQ==`. O *token* deve ser passado em todas as requisições através do *header HTTP* ***Authorization***. O valor do *header* é a junção do esquema de autenticação (no caso *Basic*) com o *token* previamente enviado, separados por um espaço em branco. Exemplo: ``` Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ== ``` Caso o token de autenticação seja inválido, o acesso será negado e um *status code HTTP 401 (Unauthorized)* será devolvido. Caso, tente acessar com um usuário e senha válidos da *Hi Platform*, mas que não seja um usuário da *API* o acesso será negado e um *status code HTTP 403 (Forbidden)* será devolvido. ### **Cotas de consumo** O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como *Rate Limiting* e é fundamental para garantir a qualidade do serviço. A cada 'X' minutos (variável conforme o método solicitado) o cliente tem direito a fazer um determinado número de requisições (também variável conforme o método solicitado). Passado o tempo especificado, o limite é reiniciado. O consumo do limite pode variar conforme o método solicitado e deve ser acompanhado pelos seguintes *http headers*: - ***X-Rate-Limit-Limit***: informa o total de requisições permitidas dentro de uma janela de X minutos. - ***X-Rate-Limit-Remaining***: informa quantas requisições para *API* ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a *API* retornará o *HTTP status code 429 (Too many connections.)*. - ***X-Rate-Limit-Reset***: devolve o número de segundos disponíveis na janela atual. #API: Info# Objetivo: Prover informações provenientes dos canais de atendimentos das soluções da Hi Platform. ### **Método Contacts** - Objetivo: Busca de atendimentos. - URL: `https://api.directtalk.com.br/1.10/info/contacts` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Como a consulta de atendimentos pode potencialmente retornar muitos registros, os resultados serão sempre paginados. Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes *headers HTTP*: ``` X-Pagination-TotalResult: Total de resultados. X-Pagination-TotalPages: Total de páginas. Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" ``` É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link "Previous" não estará disponível. Outro ponto importante é quanto aos parâmetros. A API irá manter os parâmetros da primeira consulta efetuada. ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros obrigatórios:** Os únicos campos obrigatórios são os que restringem o intervalo de busca de atendimentos - ***startDate:*** data/hora inicial do atendimento, no formato *epoch*; - ***endDate:*** data/hora final do atendimento, no formato *epoch*. O intervalo máximo de busca permitido é de 31 dias. O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere. **Parâmetros opcionais:** - ***channel:*** canal de comunicação onde o atendimento ocorreu. Valores possíveis para esse campo: `HiChat`, `HiMail`, `HiPhone`, `HiBot`, `HiInbox`. Caso esse parâmetro não seja especificado, serão devolvidos atendimentos de todos os canais na consulta; - ***pageNumber:*** número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1; - ***pageSize:*** quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000; - ***dateInfo:*** parâmetro que informa sobre qual data o intervalo definido pelos parâmetros obrigatórios ***startDate*** e ***endDate*** dizem respeito. Esse parâmetro tem duas opções: `onSystem` (data de entrada do atendimento no sistema) e `contactFinished` (data que o atendimento foi finalizado). Se esse parâmetro não for passado, será assumido o valor `contactFinished`. - ***identifications:*** chaves de identificação a serem utilizadas como filtro. Somente atendimentos que possuírem uma das chaves informadas serão retornados. Deverá ser informado no formato JSON, seguindo o exemplo: `[{"key":"Consumidor_Chat","value":"Brás Cubas"},{"key":"email","value":"teste@teste.com"}]` - ***departmentId:*** id do departamento a ser usado como filtro; Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a requisição for bem sucedida, a resposta será: Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "protocolNumber": "...", "agentName": "...", "agentLogin": "...", "groupName": "...", "channel": "...", "departmentName": "...", "onSystemDate": 1, "contactStartedDate": 1, "contactFinishedDate": 1, "customerInQueueTime": 1, "agentServingTime": 1, "contactTotalTime": 1, "contactState": "...", "contactStateDetail": "...", "classifications": [ "...", "...", ], "mailQueue": "...", "mailStartQueue": "...", "origin": "...", "identifications": [ { "key": "...", "value": "..." }, ... ], "formAnswers": [ { "question": "...", "answer": "...." }, ... ], "ratings": [ { "question": "...", "answer": "...." }, ... ] }, ... ] } ``` Cada elemento (item) do corpo possui os seguintes campos: - ***protocolNumber:*** identificação do atendimento; - ***agentName:*** nome do operador que atendeu o cliente; - ***agentLogin:*** login do operador que atendeu o cliente; - ***groupName:*** nome do grupo ao qual o operador pertence; - ***channel:*** canal no qual o atendimento foi feito; - ***departmentName:*** nome do departamento no qual o atendimento foi feito; - ***onSystemDate:*** data de entrada do atendimento no sistema no formato *epoch*; - ***contactStartedDate:*** data na qual o operador começou a atender, no formato *epoch*; - ***contactFinishedDate:*** data na qual o atendimento foi finalizado, no formato *epoch*; - ***customerInQueueTime:*** tempo em segundos que o consumidor ficou em fila; - ***agentServingTime:*** tempo em segundos que o operador ficou atendendo o cliente; - ***contactTotalTime:*** duração total do atendimento em segundos; - ***contactState:*** estado no qual o atendimento se encontra; - ***contactStateDetail:*** descrição mais completa do estado; - ***classifications:*** lista de classificações atribuídas ao atendimento; - ***mailQueue:*** campo específico para atendimentos de *email*. Informa por qual fila de *email* o atendimento está atualmente; - ***mailStartQueue:*** campo específico para atendimentos de *email*. Informa por qual fila de *email* o atendimento entrou; - ***origin:*** origem do atendimento; - ***identifications:*** lista de chaves utilizadas para o atendimento; - ***formAnswers:*** lista de perguntas e respostas provenientes do formulário de classificação do atendimento. - ***ratings:*** lista com as avaliações do atendimento do tipo estrela; ### **Exemplo de utilização** Este exemplo realiza uma busca de atendimentos feitos no `HiChat` cuja data de entrada no sistema está no intervalo de tempo entre `13/06/2015 1:46:40 PM` e `13/06/2015 2:53:20 PM`. Além disso, vamos pedir apenas 10 registros por página e assumir que exista uma página número 136. A requisição é a seguinte: ``` https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=136 ``` Resultado possível: ``` 200 OK Content-Type: application/json X-Rate-Limit-Limit: 60 X-Rate-Limit-Remaining: 59 X-Rate-Limit-Reset: 600 X-Pagination-TotalResults: 1035 X-Pagination-TotalPages: 518 Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" { [ { "protocolNumber":"12345678-90", "agentName":"José da Silva", "agentLogin":"tst.josesilva", "groupName":"Turno da tarde", "channel":"DTChat", "departmentName":"Atendimento Crítico", "onSystemDate":1434216932, "contactStartedDate":1434217049, "contactFinishedDate":1434217667, "customerInQueueTime":117, "agentServingTime":618, "contactTotalTime":735, "contactState":"FINALIZADO", "contactStateDetail":"Consumidor finalizou", "contactSource":"Robô de atendimento", "classifications":["Atraso no pagamento"], "origin":"bot", "identifications": [ { "key": "Consumidor_Chat", "value": "Brás Cubas" }, { "key": "email", "value": "brascubas@mda.com.br" } ], "formAnswers": [ { "question": "Informe a Data", "answer": "13/06/2015 14:40" } ], "ratings": [ { "question": "Avaliação", "answer": 7 } ] }, { "protocolNumber":"12345678-91", "agentName":"Maria Santos", "agentLogin":"tst.mariasantos", "groupName":"Turno da tarde", "channel":"DTChat", "departmentName":"Sugestões", "onSystemDate":1434216940, "contactStartedDate":1434216940, "contactFinishedDate":1434217093, "customerInQueueTime":0, "agentServingTime":153, "contactTotalTime":153, "contactState":"FINALIZADO", "contactStateDetail":"Operador finalizou", "contactSource":"Site", "classifications":["Melhorias", "Processos"], "origin":"bot", "rating": 9, "identifications": [ { "key": "Consumidor_Chat", "value": "Ed Mort" }, { "key": "email", "value": "edmort@lfv.com.br" } ], "formAnswers": [ { "question": "Informe a Data", "answer": "13/06/2015 14:39" } ], "ratings": [] } ] } ``` ## **Método Contacts -> Detail** - Objetivo: Busca detalhes do atendimento. - URL: `https://api.directtalk.com.br/1.10/info/contacts/{id}/detail` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **IMPORTANTE:** essa requisição não deve ser utilizada por atendimentos do canal HiInbox **Parâmetros obrigatórios:** Os únicos campos obrigatórios são os que restringem o intervalo de busca de atendimentos - ***id:*** id do atendimento; **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será a seguinte: ``` 200 OK Content-Type: application/json { //Resposta para os canais chat e bot "customer": { "email": "teste@teste.com" }, "properties": [ { "key": "ip", "value": "200.86.120.53" }, { "key": "knowledgeBaseId", "value": "0adbd202-d12d-4543-b0a9-8c2df45228d5" }, { "key": "ipCity", "value": "Sao Paulo - Brazil" }, { "key": "browserVersion", "value": "61.0.3163" }, { "key": "departmentId", "value": "06e006fb-5fec-4d5c-a733-16b8b14bc50a" }, { "key": "platform", "value": "Windows" }, { "key": "nome_usuario", "value": "Teste" }, { "key": "browser", "value": "Chrome" }, { "key": "email", "value": "teste@teste.com" }, { "key": "retention", "value": "True" } ], "startDate": "1536858065", "endDate": "1536858065", "origin": "DTBot", "state": "Em andamento", "messages": [ { "sender": "DTBot", "date": 1507666554, "text": "Olá! Bem-vindo, como posso te ajudar?" }, { "sender": "Teste", "date": 1507666556, "text": "Bom dia" } ], "attachments": [ { "id": "8b5831c1-f111-46e5-a86f-6540792e092a", "size": "5000", "name": "file.jpg" } ], "classifications": [ "Melhorias", "Processos", ] //apenas para HiChat e HiMail } ``` ``` 200 OK Content-Type: application/json { //Resposta para o canal email "subject": "teste anexo2", "account": "mdirecttalk41@gmail.com ", "rule": "Regra Padrão", "id": 595811, "events": [ { "date": 1536858065, "message": "Mensagem enviada pelo cliente" }, { "date": 1536858824, "message": "Mensagem incluída no sistema" }, { "date": 1536858840, "message": "Mensagem movida para a fila Fila Padrão pela regra Regra Padrão" } ], "customer": { "email": "customer@customerdomain.com" }, "properties": [ { "key": "retention", "value": "True" } ], "startDate": 1536858065, "endDate": 1536858840, "state": "Na fila", "messages": [ { "sender": "customer@customerdomain.com", "date": 1536858065, "text": "
anexos
\r\n" }, { "sender": "operador", "date": 1536858065, "text": "
resposta operador
\r\n" } ], "attachments": [ { "id": "93dac79e-5f69-44a7-b637-faaaed6b9c2f", "size": "1.00 MB", "name": "E-book - chatbots o impacto do vendedor online na operação.pdf" } ], "classifications": [ "Atraso no pagamento" ] //apenas para HiChat e HiMail } ``` Cada elemento (item) do corpo possui os seguintes campos: **IMPORTANTE:** A propriedade messages só estará disponível para atendimentos do **HiChat**, **HiBot** e **HiMail**. - ***sender:*** quem enviou a mensagem; - ***date:*** data da mensagem *epoch*; - ***text:*** texto da mensagem; ## **Método Contacts -> Attachments** - Objetivo: Acessar os anexos dos atendimentos. - URL: `https://api.directtalk.com.br/1.10/info/contacts/{id}/attachments/{attachmentId}` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto **Parâmetros obrigatórios:** - ***id:*** id do atendimento; - ***attachmentId:*** id do anexo; **Resposta** Se o anexo não pertencer ao id de atendimento solicitado, o sistema devolverá uma mensagem informativa com o código de status http 403. Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada o sistema devolverá um código de status http 200. Através do header de resposta da requisição haverá no valor da chave *Content-Disposition* o nome do arquivo, como no exemplo abaixo: *Content-Disposition: attachment; filename="filename.jpg"* ## **Método Reports -> HiBot -> ArticleHits** - Objetivo: Artigos acessados no HiBot. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtbot/articlehits` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Os resultados serão sempre paginados. Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes *headers HTTP*: ``` X-Pagination-TotalResult: Total de resultados. X-Pagination-TotalPages: Total de páginas. Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" ``` É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link "Previous" não estará disponível. Outro ponto importante é quanto aos parâmetros. A API irá manter os parâmetros da primeira consulta efetuada. ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros obrigatórios:** Os campos obrigatórios restringem o intervalo de busca de artigos acessados - ***startDate:*** data/hora inicial, no formato *epoch*; - ***endDate:*** data/hora final, no formato *epoch*. - ***departmentId:*** id do departamento que deseja extrair os dados. **Parâmetros opcionais:** - ***pageNumber:*** número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1; - ***pageSize:*** quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000; O intervalo máximo de busca permitido é de 90 dias. O resultado das consultas será sempre ordenado pela data que o intervalo passado se refere. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "articleId": "...", "date": "...", "amount": "...", "question": "...", "category": "...", "department": { "id": "...", "name": "..." }, }, ... ] } ``` Cada elemento (item) do corpo possui os seguintes campos: - ***articleId:*** guid, com o id do artigo; - ***date:*** data do agrupamento no formato *epoch*; - ***amount:*** inteiro, quantidade de acessos; - ***question:*** string, nome da questão; - ***category:*** string, nome da categoria; - ***department:*** departamento, com id e nome; ## **Método Reports -> HiBot -> Volumetry** - Objetivo: Volumetria do HiBot. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtbot/volumetry` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Os resultados serão sempre paginados. Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes *headers HTTP*: ``` X-Pagination-TotalResult: Total de resultados. X-Pagination-TotalPages: Total de páginas. Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" ``` É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link "Previous" não estará disponível. Outro ponto importante é quanto aos parâmetros. A API irá manter os parâmetros da primeira consulta efetuada. ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros obrigatórios:** Os campos obrigatórios restringem o intervalo de busca de volumetria e o tipo de quebra - ***startDate:*** data/hora inicial, no formato *epoch*; - ***endDate:*** data/hora final, no formato *epoch*; - ***departmentId:*** Id do departamento de bot. **Parâmetros opcionais:** - ***pageNumber:*** número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1; - ***pageSize:*** quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000; - ***groupBy:*** tipo de agrupamento que será aplicado. 'day' indica que que a quebra deve ser por dia. 'hour' indica que a quebra deve ser por hora. Se este parâmetro não for passado, o padrão é 'day'. O intervalo máximo de busca permitido é de 30 dias. O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "date": "...", "condition": "...", "dialogCount": "...", "interactionCount": "...", "answerCount": "...", "answerPercentage": "...", "transferCount": "...", "transferPercentage": "...", "retentionCount": "...", "retentionPercentage": "...", "transferByEvasionCount": "...", "transferByEvasionPercentage": "...", "totalTimeOfContact": "...", "totalAvgTimeOfContact": "...", "userCount": "...", "newUserCount": "...", "newUserPercentage": "...", "recurrentUserCount": "...", "recurrentUserPercentage": "...", "SimultaneousUserCount": "...", "yesCount": "...", "noCount": "...", "likeCount": "...", "unlikeCount": "...", "withoutInformationCount": "...", "wrongAnswerCount": "...", "notAnsweredCount": "..." }, ... ] } ``` Cada elemento (item) do corpo possui os seguintes campos: - **date**: data/hora conforme a quebra escolhida, no formato *epoch*; - **condition**: condição - **dialogCount**: quantidade de diálogos - **interactionCount**: quantidade de interações - **answerCount**: quantidade de respostas - **answerPercentage**: percentual de respostas - **transferCount**: quantidade de transferências - **transferPercentage**: percentual de transferências - **retentionCount**: quantidade de retenções - **retentionPercentage**: percentual de retenções - **transferByEvasionCount**: quantidade de transferências por evasivas - **transferByEvasionPercentage**: percentual de transferências por evasivas - **totalTimeOfContact**: tempo total de atendimento - **totalAvgTimeOfContact**: tempo médio de atendimento - **userCount**: quantidade de usuários - **newUserCount**: quantidade de novos usuários - **newUserPercentage**: percentual de novos usuários - **recurrentUserCount**: quantidade de usuários recorrentes - **recurrentUserPercentage**: percentual de usuários recorrentes - **SimultaneousUserCount**: quantidade de usuários simultâneos - **yesCount**: quantidade de 'sim' - **noCount**: quantidade de 'não' - **likeCount**: quantidade de 'gostei' - **unlikeCount**: quantidade de 'não gostei' - **withoutInformationCount**: quantidade de sem informação - **wrongAnswerCount**: quantidade de respostas incorretas - **notAnsweredCount**: quantidade sem resposta ## **Método Reports -> HiBot -> Evaluation** - Objetivo: Avaliação do HiBot. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtbot/evaluation` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros obrigatórios:** Os campos obrigatórios restringem o intervalo de busca de volumetria e o tipo de quebra - ***startDate:*** data/hora inicial, no formato *epoch*; - ***endDate:*** data/hora final, no formato *epoch*. - ***departmentId:*** id do departamento que deseja extrair os dados. - ***groupBy:*** formato que deseja agrupar os dados. Os formatos válidos p/ este campo são: groupByDay (p/ agrupar por dia) e groupByMonth (p/ agrupar por mês) - ***formId:*** id do formulário que deseja extrair os dados. - ***viewMode:*** formato que deseja listar os dados. Os formatos válidos p/ este campo são: GroupByDate (p/ exibir os dados agrupados somente por dia; neste formato de visualização, o campo de retorno ***evaluationsByPeriod*** será alimentado com as informações) e GroupByDateAndEvaluation (p/ exibir os dados agrupados por dia e nota de avaliação; neste formato de visualização, o campo de retorno ***evaluationsByPeriodAndEvaluation*** será alimentado com as informações). O intervalo máximo de busca permitido é de 30 dias. O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será (exemplo retornando visualização com viewMode: GroupByDate): ``` 200 OK Content-Type: application/json { "items": [ { "questionName": "Pergunta 1", "evaluationValuePeriod": 5.09090909090909, "evaluationsByPeriod": [ { "date": "2018-09-24T00:00:00", "value": 5.625 }, { "date": "2018-09-25T00:00:00", "value": 3.66666666666667 } ], "evaluationsByPeriodAndEvaluation": null } ], "totalResults": 1, "totalPages": 0, "pageNumber": 1 } ``` Cada elemento (item) do corpo possui os seguintes campos: - **questionName**: texto da questão - **evaluationValuePeriod**: média ponderada das avaliações do período - **evaluationsByPeriod**: lista com os dados das datas e valores as médias das notas; este campo será populado sempre que o parâmetro viewMode = GroupByDate - **evaluationsByPeriodAndEvaluation**: lista os dados das avaliações, agrupados por dia e avaliação; este campo será populado sempre que o parâmetro viewMode = GroupByDateAndEvaluation ## **Método Reports -> HiChat -> Queue** - Objetivo: Informações em near real time sobre a situação atual das filas de atendimento de chat para os departamentos. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtchat/queue` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Não existe paginação para esse método. ``` X-Pagination-TotalResult: Total de resultados. ``` ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros opcionais:** - ***departmentId:*** o id do departamento (guid) que se deseja monitorar; Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "departmentId": "...", "departmentName": "...", "customersInQueue": ..., "waitingTime": "..." }, ... ] } ``` Caso a chamada tenha sido filtrada por departamento, será exibido apenas o departamento especificado. Cada elemento (item) do corpo possui os seguintes campos: - **departmentId**: Id do departamento de chat; - **departmentName**: nome do departamento de chat; - **customersInQueue**: número de consumidores aguardando na fila do chat deste departamento, no momento da consulta; - **waitingTime**: o tempo de espera do consumidor em primeiro lugar na fila de atendimento, no momento da consulta, ou seja, o maior tempo de espera em fila. ## **Método Reports -> HiChat -> Volumetry** - Objetivo: Volumetria do HiChat. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtchat/volumetry` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Os resultados não serão paginados. ``` X-Pagination-TotalResult: Total de resultados. ``` ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros opcionais:** - ***departmentId:*** o id do departamento que se deseja monitorar; - ***date:*** data do atendimento no formato epoch. Se esse parâmetro estiver vazio, deve retornar a data atual. - ***interval:*** informação do intervalo desejado. São válidos intervalos cravados à partir de “00:00:00” de 15 em 15 minutos, ou seja, são formatos válidos de intervalos: “00:00:00”, “00:15:00”, “10:45:00”, “15:00:00”, “23:45:00” etc. Se esse parâmetro estiver vazio, o intervalo em minutos da API deve corresponder ao último quarto fechado,tendo como referência a data da consulta, exemplo: se a consulta tenha sido feita as 15:02, o intervalo de busca deve considerar 14:45 a 15:00, e assim por diante. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "date": ..., "interval": "...", "departmentId": "...", "departmentName": "...", "averageQueueTime": "...", "averageOperationTime": "...", "averageTotalTime": "...", "quantityReceived": ..., "quantityAttended": ..., "quantityAbandoned": ..., "queueTimeGreater60s": ..., "queueTimeUntil60s": ..., "queueTimeUntil30s": ..., "queueTimeUntil20s": ..., "queueTimeAttendedGreater60s": ..., "queueTimeAttendedUntil60s": ..., "queueTimeAttendedUntil30s": ..., "queueTimeAttendedUntil20s": ..., "connectedOperators": ..., "activeWindows": ... }, ... ] } ``` Caso a chamada tenha sido filtrada por departamento, será exibido apenas o departamento especificado. Cada elemento (item) do corpo possui os seguintes campos: - **date**: a data onde os atendimentos foram finalizados (epoch); - **interval**: identifica o horário de início do intervalo de análise. Ou seja, à partir desse horário, na data especificada, por 15 minutos, foram consolidadas as informações exibidas para os atendimentos finalizados nesse intervalo; - **departmentId**: Id do departamento de chat; - **departmentName**: nome do departamento de chat; - **averageQueueTime**: tempo médio de fila calculado entre todos os atendimentos finalizados neste intervalo. Exemplo: a operação finalizou entre 00:00:00 e 00:00:15 quatro atendimentos, dois sem fila e outros dois que aguardaram 10 minutos cada em fila. O averageQueueTime informado será de “00:05:00” (cinco minutos); - **averageOperationTime**: tempo médio que os consumidores atendidos no período estiveram com o operador. Serão computados apenas atendimentos que foram de fato entregues à operação. Exemplo: a operação finalizou entre “00:00:00” e “00:00:15” quatro atendimentos, dois desses consumidores chegaram a receber atendimento com operadores, tendo cada atendimento durado 10 minutos. Outros dois consumidores abandonaram o atendimento enquanto ainda estavam em fila. O averageOperationTime informado será de “00:10:00”; - **averageTotalTime**: tempo médio total de atendimento, contemplando todos os atendimentos finalizados no intervalo, inclusive os abandonos em fila. Exemplo: a operação finalizou entre “00:00:00” e “00:00:15” quatro atendimentos. O primeiro ficou 10 minutos em fila e abandonou. O segundo ficou 10 minutos em fila, chegou ao operador e recebeu atendimento por mais 10 minutos. O terceiro e o quarto não passaram pela fila, tendo sido atendidos por operadores durante cinco minutos cada. O averageTotalTime informado será de “00:10:00”; - **quantityReceived**: quantidade total de atendimentos que compõe o intervalo (consideramos atendimentos que foram finalizados no intervalo); - **quantityAttended**: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat (consideramos atendimentos que foram finalizados no intervalo); - **quantityAbandoned**: quantidade de atendimentos que foram abandonados em fila durante o intervalo; - **queueTimeGreater60s**: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior a 60 segundos; - **queueTimeUntil60s**: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior 30 segundos e menor ou igual a 60 segundos; - **queueTimeUntil30s**: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior 20 segundos e menor ou igual a 30 segundos; - **queueTimeUntil20s**: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido igual ou inferior a 20 segundos; - **queueTimeAttendedGreater60s**: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior a 60 segundos; - **queueTimeAttendedUntil60s**: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior 30 segundos e menor ou igual a 60 segundos; - **queueTimeAttendedUntil30s**: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior 20 segundos e menor ou igual a 30 segundos; - **queueTimeAttendedUntil20s**: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido igual ou inferior a 20 segundos; - **connectedOperators**: uma fotografia, do início do intervalo, para o número de operadores de chat conectados na ferramenta naquele momento; - **activeWindows**: uma fotografia, do início do intervalo, para o número de janelas de atendimento ativas naquele momento. ## **Método Agent Events** - Objetivo: Busca dos Eventos de operadores. - URL: `https://api.directtalk.com.br/1.10/info/reports/platform/agentevents` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Como essa consulta pode potencialmente retornar muitos registros, os resultados serão sempre paginados. Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes *headers HTTP*: ``` X-Pagination-TotalResult: Total de resultados. X-Pagination-TotalPages: Total de páginas. Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" ``` É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link "Previous" não estará disponível. Outro ponto importante é quanto aos parâmetros. A API irá manter os parâmetros da primeira consulta efetuada. ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros obrigatórios:** Os únicos campos obrigatórios são os que restringem o intervalo de busca de atendimentos - ***startDate:*** data/hora inicial do evento, no formato *epoch*; - ***endDate:*** data/hora final do evento, no formato *epoch*. O intervalo máximo de busca permitido é de 31 dias. O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a requisição for bem sucedida, a resposta será: Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json { [ { "agentName": "...", "agentLogin": "...", "event": "...", "channel": "...", "description": "...", "session": "...", "date": 1 }, ... ] } ``` Cada elemento (item) do corpo possui os seguintes campos: - ***agentName:*** nome do operador; - ***agentLogin:*** login do operador; - ***event:*** ação executada pelo operador; - ***channel:*** canal no qual operador executou a ação; - ***description:*** informação complementar da ação executada pelo operador; - ***session:*** informação de identificaçaõ da sessao - para agrupar ações executadas; - ***date:*** data na qual o operador executou a ação, no formato *epoch*; ### **Exemplo de utilização** Este exemplo realiza uma busca de eventos de operadores no intervalo de tempo entre `13/06/2015 1:46:40 PM` e `13/06/2015 2:53:20 PM`. Além disso, vamos pedir apenas 10 registros por página e assumir que exista uma página número 136. A requisição é a seguinte: ``` https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=136 ``` Resultado possível: ``` 200 OK Content-Type: application/json X-Rate-Limit-Limit: 60 X-Rate-Limit-Remaining: 59 X-Rate-Limit-Reset: 600 X-Pagination-TotalResults: 1035 X-Pagination-TotalPages: 518 Link: ; rel="First", ; rel="Previous", ; rel="Next", ; rel="Last" { [ { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Conectar Canal", "channel":"DTChat", "description":null, "session":"4", "date":1434216932 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Conectar Canal", "channel":"DTMail", "description":null, "session":"5", "date":1434216992 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Solicitou pausa", "channel":"Todos", "description":"pausa exemplo", "session":"4 | 5", "date":1434217232 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Entrou em pausa", "channel":"Todos", "description":"pausa exemplo", "session":"4 | 5", "date":1434217260 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Saiu em pausa", "channel":"Todos", "description":"pausa exemplo", "session":"4 | 5", "date":1434217800 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Solicitou desconexão", "channel":"DTMail", "description":"", "session":"5", "date":1434218100 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Desconectar Canal", "channel":"DTMail", "description":null, "session":"5", "date":1434218105 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Solicitou desconexão", "channel":"DTChat", "description":"", "session":"4", "date":1434218130 }, { "agentName":"José da Silva", "agentLogin":"tst.josesilva", "event":"Desconectar Canal", "channel":"DTChat", "description":null, "session":"4", "date":1434218140 } ] } ``` ## **Método Reports -> HiBot -> Volume e Retenção** - Objetivo: Volume e Retenção do Bot. - URL: `https://api.directtalk.com.br/1.10/info/reports/dtbot/volumeRetention` - Método HTTP: GET - Passagem de parâmetros: via query string ### **Parâmetros de rate limiting** - Limite de requisições: 100 - Janela de tempo: 1 minuto ### **Paginação** Os resultados não serão paginados. ``` X-Pagination-TotalResult: Total de resultados. ``` ### **Utilização** Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação. **Parâmetros Obrigatórios:** - ***startDate:*** data/hora inicial, no formato *epoch*; - ***endDate:*** data/hora final, no formato *epoch*. - ***departmentId:*** o id do departamento que se deseja buscar os dados; - ***groupby:*** tipo de agrupamento que os dados exibidos. Os tipos podem ser: `groupbyHour` - retorna o volume e retenção agrupados por hora. `groupbyDay` - retorna o volume e retenção agrupados por dia. `groupbymonth` - retorna o volume e retenção agrupados por mês. Para os agrupamentos `groupbyHour` e `groupbyday`, o período máximo de datas é de 90 dias. Já para o agrupamento `groupbyMonth` o período máximo de datas é de 12 meses. Se forem passados parâmetros inválidos, a API devolverá um `status code HTTP 400 (Bad Request).` ### **Exemplo de utilização** Este exemplo realiza a busca da quantidade de atendimentos e da quantidade de atendimentos retidos do `Bot` no intervalo de tempo entre `01/05/2018 00:00:00` e `10/06/2015 23:59:59 PM` para o departamento `7f7bec33-1f55-4ced-8f1b-7c204f35e12b` , agrupando o resultado por dia (`groupbyday`) A requisição é a seguinte: ``` https://api.directtalk.com.br/1.10/reports/dtbot/volumeRetention?startdate=1525132800&enddate=1528675199&DepartmentId=7f7bec33-1f55-4ced-8f1b-7c204f35e12b&GroupBy=groupbyDay ``` **Resposta** Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um *status code HTTP* da família 500 (Ex.: 503 *Service Unavailable*), e o corpo da resposta virá no seguinte formato: ``` {"message": "descrição do erro"} ``` Se a operação for corretamente processada a resposta será: ``` 200 OK Content-Type: application/json [ { "date": 1483228800, "volume": 370, "retention": 303, "difference": "82%" }, { "date": 1485907200, "volume": 106, "retention": 89, "difference": "84%" } ... ] ``` Cada elemento (item) do corpo possui os seguintes campos: - **date**: a data correspondente em formato (epoch); - **volume**: a quantidade de atendimentos realizados no bot; - **retention**: a quantidade de atendimentos retidos no bot; - **difference**: a diferença em % da retenção pelo volume; **Artigos relacionados:** [Gestão de usuários de API](https://help.hiplatform.com/docs/gestao-de-usuarios-de-api)