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

 API de integração da Hi Platform

Versão 1.5

Endereço base

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

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 é 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.5/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.5/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: estará disponível para atendimentos do HiBot e HiChat.

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

Método Contacts -> Details ->Attachments

• Objetivo: Realizar o download de um anexo.
• URL: https://api.directtalk.com.br/1.5/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

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;
• attachmendId: 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:

200 OK
Content-Disposition: attachment; filename="filename.jpg"

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.5/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.5/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.

Método Agent Events

• Objetivo: Busca dos Eventos de operadores.
• URL: https://api.directtalk.com.br/1.5/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.5/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.5/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.5/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.5/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 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>
{
    [
        {
            "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.5/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.5/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=1\>; rel="First", 
      <https://api.directtalk.com.br/1.5/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.5/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.5/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			    		}
    ]
}

Artigos relacionados:

Gestão de usuários de API