Versão 1.9 - API INFO

24 Minutes to read

Print
Dark
Light
PDF

Versão 1.9 - API INFO

24 Minutes to read

Print
Dark
Light
PDF

Article Summary

Share feedback

Thanks for sharing your feedback!

API INFO – Versão 1.9

API de integração da Hi Platform#
Versão 1.9

Endereço base
URL: https://api.directtalk.com.br/1.9/

Autenticação/Autorização

A Hi Platform irá fornecer um usuário e uma senha de acesso exclusivo para o uso da API. A autenticação da API será feita utilizando o protocolo Basic .

Vamos descrever brevemente o como autenticar usando o protocolo Basic.

Considere hipoteticamente que o usuário da API passado é

e a senha é

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

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.9/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: https://api.directtalk.com.br/1.9/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\; rel="First",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\; rel="Previous",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\; rel="Next",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000\; 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: DTChat, DTMail, DTPhone, DTBot. 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

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:

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
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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

cuja data de entrada no sistema está no intervalo de tempo entre

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.9/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: https://api.directtalk.com.br/1.9/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=1\; rel="First",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=135\; rel="Previous",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=137\; rel="Next",
https://api.directtalk.com.br/1.9/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=518\; 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.9/info/contacts/{id}/detail
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

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

id: id do atendimento;

Resposta

Se a requisição for bem sucedida, a resposta será:

Se a operação for corretamente processada a resposta será a seguinte:

200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
//Resposta para os canais chat e bot
"customer": {
"email": "teste@teste.com"
},
"propeties": [
{
"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"
}
]
}
200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
//Resposta para o canal email
"subject": "teste anexo2",
"account": "mdirecttalk41@gmail.com 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"
},
"propeties": [
{
"key": "retention",
"value": "True"
}
],
"startDate": 1536858065,
"endDate": 1536858840,
"state": "Na fila",
"messages": [
{
"sender": "customer@customerdomain.com",
"date": 1536858065,
"text": "<div dir="ltr">anexos\r\n"
}, {
"sender": "operador",
"date": 1536858065,
"text": "<div dir="ltr">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"
}
]
}

Cada elemento (item) do corpo possui os seguintes campos:

IMPORTANTE: A propriedade messages só estará disponível para atendimentos do** Hi Chat, Hi Bot e Hi Mail.**

sender: quem enviou a mensagem;
date: data da mensagem epoch;
text: texto da mensagem;

Método Contacts -> Attachments

Objetivo: Artigos acessados no HiBot.
URL: https://api.directtalk.com.br/1.9/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: 60
Janela de tempo: 10 minutos

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:

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.9/info/reports/dtbot/articlehits
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

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: https://api.directtalk.com.br/1.9/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\; rel="First",
https://api.directtalk.com.br/1.9/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\; rel="Previous",
https://api.directtalk.com.br/1.9/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\; rel="Next",
https://api.directtalk.com.br/1.9/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000\; 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.

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

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:

Se a operação for corretamente processada a resposta será:

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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.9/info/reports/dtbot/volumetry
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

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: https://api.directtalk.com.br/1.9/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\; rel="First",
https://api.directtalk.com.br/1.9/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\; rel="Previous",
https://api.directtalk.com.br/1.9/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\; rel="Next",
https://api.directtalk.com.br/1.9/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000\; 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.

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

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:

Se a operação for corretamente processada a resposta será:

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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.9/info/reports/dtbot/evaluation
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

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

Resposta

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.9/info/reports/dtchat/queue
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 1
Janela de tempo: 15 segundos

Paginação

Não existe paginação para esse método.

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

Resposta

Se a operação for corretamente processada a resposta será:

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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.9/info/reports/dtchat/volumetry
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

Paginação

Os resultados não serão paginados.

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

Resposta

Se a operação for corretamente processada a resposta será:

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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.9/info/reports/platform/agentevents
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

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: https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\; rel="First",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\; rel="Previous",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\; rel="Next",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000\; 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

Resposta

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
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
[
{
"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

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.9/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: https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=1\; rel="First",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=135\; rel="Previous",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=137\; rel="Next",
https://api.directtalk.com.br/1.9/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=518\; 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.9/info/reports/dtbot/volumeRetention
Método HTTP: GET
Passagem de parâmetros: via query string

Parâmetros de rate limiting

Limite de requisições: 60
Janela de tempo: 10 minutos

Paginação

Os resultados não serão paginados.

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

o período máximo de datas é de 90 dias. Já para o agrupamento

o período máximo de datas é de 12 meses.

Se forem passados parâmetros inválidos, a API devolverá um

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.9/reports/dtbot/volumeRetention?startdate=1525132800&enddate=1528675199&DepartmentId=7f7bec33-1f55-4ced-8f1b-7c204f35e12b&GroupBy=groupbyDay

Resposta

{"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

Was this article helpful?

What's Next

WebView Hi Bot – Android (Kotlin)