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


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

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

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\>; rel="First", 
      <https://api.directtalk.com.br/1.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.4/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.4/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 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: DTChatDTMailDTPhoneDTBot. 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\>; rel="First", 
      <https://api.directtalk.com.br/1.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.4/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.4/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",
                "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\>; rel="First", 
      <https://api.directtalk.com.br/1.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.4/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.4/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 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\>; rel="First", 
      <https://api.directtalk.com.br/1.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.4/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.4/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 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.