Versão 1.4 - API de integração da Hi Platform

 API de integração da Hi Platform

Versão 1.4

Endereço base

• URL: https://api.directtalk.com.br/1.4/

Autenticação/Autorização

A DirectTalk 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 é 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. 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 DirectTalk, 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 DirectTalk.

Método Contacts

• Objetivo: Busca de atendimentos.
• URL: https://api.directtalk.com.br/1.4/info/contacts
• 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 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.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000&gt;; rel="First",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000&gt;; rel="Previous",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000&gt;; rel="Next",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000&gt;; 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 resultado 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"}]

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
<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;

Exemplo de utilização

Este exemplo realiza uma busca de atendimentos feitos no DTChat 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.4/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.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=1&gt;; rel="First",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=135&gt;; rel="Previous",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=137&gt;; rel="Next",
<https://api.directtalk.com.br/1.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=518&gt;; 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",
                "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.4/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 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
<headers de rate limiting conforme descrito nas seções anteriores>
{
[
{
"customer": {
"key_name": "key_value",
},
{
"propeties": [
{
"key": "ip",
"value": "1.1.1.1"
},
{
"key": "departamento",
"value": "Sim"
},
{
"key": "nome_usuario",
"value": "RICARDO DE CASTRO"
},
{
"key": "departmentId",
"value": "149d168d-bf1d-4c26-a9d1-6884092cdf74"
},
{
"key": "knowledgeBaseId",
"value": "889e8cdf-0fb7-45e1-90fd-970b040dcf0c"
},
{
"key": "ipCity",
"value": "Ma Yau Tong - Hong Kong"
},
{
"key": "browserVersion",
"value": "59.0.3071"
},
{
"key": "retention",
"value": "True"
}
 ...
{
"messages": [
{
"sender": "...",
"date": "..."
"text": "..."
},
...
]
},
...
]
}

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

customer: correspondem as todas as chaves de identificação cadastradas no site (nome da chave / valor da chave)

propeties: correspondem as chaves de identificação(nome da chave/ valor da chave), dados de conexão (ip, ipcity, browserVersion), dados do departamento (department_id) e se o atendimento foi retido ou não no bot. (retention = true/false)

messages: só estará disponível para atendimentos do DTBot.

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

Método Reports -> DTBot -> ArticleHits

• Objetivo: Artigos acessados no DTBot.
• URL: https://api.directtalk.com.br/1.4/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.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000&gt;; rel="First",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000&gt;; rel="Previous",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000&gt;; rel="Next",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000&gt;; 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 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
<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 -> DTBot -> Volumetry

• Objetivo: Volumetria do DTBot.
• URL: https://api.directtalk.com.br/1.4/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.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000&gt;; rel="First",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000&gt;; rel="Previous",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000&gt;; rel="Next",
<https://api.directtalk.com.br/1.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000&gt;; 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 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
<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 -> DTChat -> 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.4/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.

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
<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 -> DTChat -> Volumetry

• Objetivo: Volumetria do DTChat.
• URL: https://api.directtalk.com.br/1.4/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.

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
<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": ...,
            "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;
• 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.

Artigos relacionados:

Gestão de usuários de API