Versão 1.10 - API de integração Hi Platform

API de integração da Hi Platform
Versão 1.10

Endereço base

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

Autenticação/Autorização

A Hi Platform irá fornecer um usuário e uma senha de acesso exclusivo
para o uso da API. Saiba mais.
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 Hi Platform, mas que não seja um usuário da API o acesso será negado e um status code HTTP 403 (Forbidden) será devolvido.

Cotas de consumo

O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como Rate Limiting e é fundamental para garantir a qualidade do serviço.

A cada 'X' minutos (variável conforme o método solicitado) o cliente tem direito a fazer um determinado número de requisições (também variável conforme o método solicitado). Passado o tempo especificado, o limite é reiniciado.

O consumo do limite pode variar conforme o método solicitado e deve ser acompanhado pelos seguintes http headers:

• X-Rate-Limit-Limit: informa o total de requisições permitidas dentro de uma janela de X minutos.
• X-Rate-Limit-Remaining: informa quantas requisições para API ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a API retornará o HTTP status code 429 (Too many connections.).
• X-Rate-Limit-Reset: devolve o número de segundos disponíveis na janela atual.

#API: Info#

Objetivo: Prover informações provenientes dos canais de atendimentos das soluções da Hi Platform.

Método Contacts

• Objetivo: Busca de atendimentos.
• URL: https://api.directtalk.com.br/1.10/info/contacts
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Como a consulta de atendimentos pode potencialmente retornar muitos registros, os resultados serão sempre paginados.

Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes headers HTTP:

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.10/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=10&pageSize=1000\>; rel="Last"

É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira,
então o link "Previous" não estará disponível.

Outro ponto importante é quanto aos parâmetros. A API irá manter os parâmetros da primeira consulta efetuada.

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros obrigatórios:

Os únicos campos obrigatórios são os que restringem o intervalo de busca de atendimentos

• startDate: data/hora inicial do atendimento, no formato epoch;
• endDate: data/hora final do atendimento, no formato epoch.

O intervalo máximo de busca permitido é de 31 dias.
O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere.

Parâmetros opcionais:

• channel: canal de comunicação onde o atendimento ocorreu. Valores possíveis para esse campo: HiChat, HiMail, HiPhone, HiBot, HiInbox. Caso esse parâmetro não seja especificado, serão devolvidos atendimentos de todos os canais na consulta;
• pageNumber: número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1;
• pageSize: quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000;
• dateInfo: parâmetro que informa sobre qual data o intervalo definido pelos parâmetros obrigatórios startDate e endDate dizem respeito. Esse parâmetro tem duas opções: onSystem (data de entrada do atendimento no sistema) e contactFinished (data que o atendimento foi finalizado). Se esse parâmetro não for passado, será assumido o valor contactFinished.
• identifications: chaves de identificação a serem utilizadas como filtro. Somente atendimentos que possuírem uma das chaves informadas serão retornados. Deverá ser informado no formato JSON, seguindo o exemplo: [{"key":"Consumidor_Chat","value":"Brás Cubas"},{"key":"email","value":"teste@teste.com"}]
• departmentId: id do departamento a ser usado como filtro;

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

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

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
    [
        {
            "protocolNumber": "...",
            "agentName": "...",
            "agentLogin": "...",
            "groupName": "...",
            "channel": "...",
            "departmentName": "...",
            "onSystemDate": 1,
            "contactStartedDate": 1,
            "contactFinishedDate": 1,
            "customerInQueueTime": 1,
            "agentServingTime": 1,
            "contactTotalTime": 1,
            "contactState": "...",
            "contactStateDetail": "...",
            "classifications": [
                 "...",
                 "...",
            ],
            "mailQueue":  "...",
            "mailStartQueue":  "...",
            "origin":  "...",
            "identifications": [
                {
                    "key": "...",
                    "value": "..."
                },
                ...
            ],
            "formAnswers": [
                {
                    "question": "...",
                    "answer": "...."
                },
                ...  
            ],
            "ratings": [
                {
                    "question": "...",
                    "answer": "...."
                },
                ...  
            ]
        },
        ...
    ]
}

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

• protocolNumber: identificação do atendimento;
• agentName: nome do operador que atendeu o cliente;
• agentLogin: login do operador que atendeu o cliente;
• groupName: nome do grupo ao qual o operador pertence;
• channel: canal no qual o atendimento foi feito;
• departmentName: nome do departamento no qual o atendimento foi feito;
• onSystemDate: data de entrada do atendimento no sistema no formato epoch;
• contactStartedDate: data na qual o operador começou a atender, no formato epoch;
• contactFinishedDate: data na qual o atendimento foi finalizado, no formato epoch;
• customerInQueueTime: tempo em segundos que o consumidor ficou em fila;
• agentServingTime: tempo em segundos que o operador ficou atendendo o cliente;
• contactTotalTime: duração total do atendimento em segundos;
• contactState: estado no qual o atendimento se encontra;
• contactStateDetail: descrição mais completa do estado;
• classifications: lista de classificações atribuídas ao atendimento;
• mailQueue: campo específico para atendimentos de email. Informa por qual fila de email o atendimento está atualmente;
• mailStartQueue: campo específico para atendimentos de email. Informa por qual fila de email o atendimento entrou;
• origin: origem do atendimento;
• identifications: lista de chaves utilizadas para o atendimento;
• formAnswers: lista de perguntas e respostas provenientes do formulário de classificação do atendimento.
• ratings: lista com as avaliações do atendimento do tipo estrela;

Exemplo de utilização

Este exemplo realiza uma busca de atendimentos feitos no HiChat cuja data de entrada no sistema está no intervalo de tempo entre 13/06/2015 1:46:40 PM e 13/06/2015 2:53:20 PM.
Além disso, vamos pedir apenas 10 registros por página e assumir que exista uma página número 136.

A requisição é a seguinte:

https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=136

Resultado possível:

200 OK
Content-Type: application/json
X-Rate-Limit-Limit: 60
X-Rate-Limit-Remaining: 59
X-Rate-Limit-Reset: 600
X-Pagination-TotalResults: 1035
X-Pagination-TotalPages: 518
Link: <https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=1\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=518\>; rel="Last"

{
    [
			{	    			
			    "protocolNumber":"12345678-90",
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "groupName":"Turno da tarde",
			    "channel":"DTChat",
			    "departmentName":"Atendimento Crítico",
			    "onSystemDate":1434216932,
			    "contactStartedDate":1434217049,
			    "contactFinishedDate":1434217667,
			    "customerInQueueTime":117,
			    "agentServingTime":618,
			    "contactTotalTime":735,
			    "contactState":"FINALIZADO",
			    "contactStateDetail":"Consumidor finalizou",
			    "contactSource":"Robô de atendimento",
			    "classifications":["Atraso no pagamento"],
			    "origin":"bot",
			    "identifications": [
					{
						"key": "Consumidor_Chat",
						"value": "Brás Cubas"
					},
					{
						"key": "email",
						"value": "brascubas@mda.com.br"
					}
			    ],
			    "formAnswers": [
					{
						"question": "Informe a Data",
						"answer": "13/06/2015 14:40"
					}
			    ],
			    "ratings": [
					{
						"question": "Avaliação",
						"answer": 7
					}
			    ]
			},
			{	
			    "protocolNumber":"12345678-91",
			    "agentName":"Maria Santos",
			    "agentLogin":"tst.mariasantos",
			    "groupName":"Turno da tarde",
			    "channel":"DTChat",
			    "departmentName":"Sugestões",
			    "onSystemDate":1434216940,
			    "contactStartedDate":1434216940,
			    "contactFinishedDate":1434217093,
			    "customerInQueueTime":0,
			    "agentServingTime":153,
			    "contactTotalTime":153,
			    "contactState":"FINALIZADO",
			    "contactStateDetail":"Operador finalizou",
			    "contactSource":"Site",
			    "classifications":["Melhorias", "Processos"],
			    "origin":"bot",
			    "rating": 9,
			    "identifications": [
					{
						"key": "Consumidor_Chat",
						"value": "Ed Mort"
					},
					{
						"key": "email",
						"value": "edmort@lfv.com.br"
					}
			    ],
			    "formAnswers": [
					{
						"question": "Informe a Data",
						"answer": "13/06/2015 14:39"
					}
			    ],
			    "ratings": []
			}
    ]
}

Método Contacts -> Detail

• Objetivo: Busca detalhes do atendimento.
• URL: https://api.directtalk.com.br/1.10/info/contacts/{id}/detail
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.
IMPORTANTE: essa requisição não deve ser utilizada por atendimentos do canal HiInbox

Parâmetros obrigatórios:

Os únicos campos obrigatórios são os que restringem o intervalo de busca de atendimentos

• id: id do atendimento;

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
    //Resposta para os canais chat e bot
    "customer": {
        "email": "teste@teste.com"
    },
    "properties": [
        {
            "key": "ip",
            "value": "200.86.120.53"
        },
        {
            "key": "knowledgeBaseId",
            "value": "0adbd202-d12d-4543-b0a9-8c2df45228d5"
        },
        {
            "key": "ipCity",
            "value": "Sao Paulo - Brazil"
        },
        {
            "key": "browserVersion",
            "value": "61.0.3163"
        },
        {
            "key": "departmentId",
            "value": "06e006fb-5fec-4d5c-a733-16b8b14bc50a"
        },
        {
            "key": "platform",
            "value": "Windows"
        },
        {
            "key": "nome_usuario",
            "value": "Teste"
        },
        {
            "key": "browser",
            "value": "Chrome"
        },
        {
            "key": "email",
            "value": "teste@teste.com"
        },
        {
            "key": "retention",
            "value": "True"
        }
    ],
    "startDate": "1536858065",
    "endDate": "1536858065",
    "origin": "DTBot",
    "state": "Em andamento",
    "messages": [
        {
            "sender": "DTBot",
            "date": 1507666554,
            "text": "Olá! Bem-vindo, como posso te ajudar?"
        },
        {
            "sender": "Teste",
            "date": 1507666556,
            "text": "Bom dia"
        }
    ],
    "attachments": [
        {
		"id": "8b5831c1-f111-46e5-a86f-6540792e092a",
		"size": "5000",
		"name": "file.jpg"
	    }
	 ],
     "classifications": [ 
        "Melhorias",
        "Processos",
     ] //apenas para HiChat e HiMail
}

200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
    //Resposta para o canal email
    "subject": "teste anexo2",
    "account": "mdirecttalk41@gmail.com <mdirecttalk41@gmail.com>",
    "rule": "Regra Padrão",
    "id": 595811,
    "events": [
        {
            "date": 1536858065,
            "message": "Mensagem enviada pelo cliente"
        },
        {
            "date": 1536858824,
            "message": "Mensagem incluída no sistema"
        },
        {
            "date": 1536858840,
            "message": "Mensagem movida para a fila Fila Padrão pela regra Regra Padrão"
        }
    ],
    "customer": {
        "email": "customer@customerdomain.com"
    },
    "properties": [
        {
            "key": "retention",
            "value": "True"
        }
    ],
    "startDate": 1536858065,
    "endDate": 1536858840,
    "state": "Na fila",
    "messages": [
        {
            "sender": "customer@customerdomain.com",
            "date": 1536858065,
            "text": "<div dir=\"ltr\">anexos</div>\r\n"
        }, {
            "sender": "operador",
            "date": 1536858065,
            "text": "<div dir=\"ltr\">resposta operador</div>\r\n"
        }
    ],
    "attachments": [
        {
            "id": "93dac79e-5f69-44a7-b637-faaaed6b9c2f",
            "size": "1.00 MB",
            "name": "E-book - chatbots o impacto do vendedor online na operação.pdf"
        }
    ],
    "classifications": [ 
        "Atraso no pagamento" 
    ] //apenas para HiChat e HiMail
}

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

IMPORTANTE: A propriedade messages só estará disponível para atendimentos do HiChat, HiBot e HiMail.

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

Método Contacts -> Attachments

• Objetivo: Acessar os anexos dos atendimentos.
• URL: https://api.directtalk.com.br/1.10/info/contacts/{id}/attachments/{attachmentId}
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Parâmetros obrigatórios:

• id: id do atendimento;
• attachmentId: id do anexo;

Resposta
Se o anexo não pertencer ao id de atendimento solicitado, o sistema devolverá uma mensagem informativa com o código de status http 403.
Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

Se a operação for corretamente processada o sistema devolverá um código de status http 200. Através do header de resposta da requisição haverá no valor da chave Content-Disposition o nome do arquivo, como no exemplo abaixo:
Content-Disposition: attachment; filename="filename.jpg"

Método Reports -> HiBot -> ArticleHits

• Objetivo: Artigos acessados no HiBot.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtbot/articlehits
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Os resultados serão sempre paginados.

Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes headers HTTP:

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.10/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/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.
• departmentId: id do departamento que deseja extrair os dados.

Parâmetros opcionais:

• pageNumber: número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1;
• pageSize: quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000;

O intervalo máximo de busca permitido é de 90 dias.
O resultado das consultas será sempre ordenado pela data que o intervalo passado se refere.

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
    [
        {
            "articleId": "...",
            "date": "...",
            "amount": "...",
            "question": "...",
            "category": "...",
            "department":
            {
              "id": "...",
              "name": "..."
            },
        },
        ...
    ]
}

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

• articleId: guid, com o id do artigo;
• date: data do agrupamento no formato epoch;
• amount: inteiro, quantidade de acessos;
• question: string, nome da questão;
• category: string, nome da categoria;
• department: departamento, com id e nome;

Método Reports -> HiBot -> Volumetry

• Objetivo: Volumetria do HiBot.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtbot/volumetry
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Os resultados serão sempre paginados.

Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes headers HTTP:

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.10/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/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;
• departmentId: Id do departamento de bot.

Parâmetros opcionais:

• pageNumber: número da página que deseja obter para essa requisição. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1;
• pageSize: quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000;
• groupBy: tipo de agrupamento que será aplicado. 'day' indica que que a quebra deve ser por dia. 'hour' indica que a quebra deve ser por hora. Se este parâmetro não for passado, o padrão é 'day'.

O intervalo máximo de busca permitido é de 30 dias.
O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere.

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
    [
        {
            "date": "...",
            "condition": "...",
            "dialogCount": "...",
            "interactionCount": "...",
            "answerCount": "...",
            "answerPercentage": "...",
            "transferCount": "...",
            "transferPercentage": "...",
            "retentionCount": "...",
            "retentionPercentage": "...",
            "transferByEvasionCount": "...",
            "transferByEvasionPercentage": "...",
            "totalTimeOfContact": "...",
            "totalAvgTimeOfContact": "...",
            "userCount": "...",
            "newUserCount": "...",
            "newUserPercentage": "...",
            "recurrentUserCount": "...",
            "recurrentUserPercentage": "...",
            "SimultaneousUserCount": "...",
            "yesCount": "...",
            "noCount": "...",
            "likeCount": "...",
            "unlikeCount": "...",
            "withoutInformationCount": "...",
            "wrongAnswerCount": "...",
            "notAnsweredCount": "..."
        },
        ...
    ]
}

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

• date: data/hora conforme a quebra escolhida, no formato epoch;
• condition: condição
• dialogCount: quantidade de diálogos
• interactionCount: quantidade de interações
• answerCount: quantidade de respostas
• answerPercentage: percentual de respostas
• transferCount: quantidade de transferências
• transferPercentage: percentual de transferências
• retentionCount: quantidade de retenções
• retentionPercentage: percentual de retenções
• transferByEvasionCount: quantidade de transferências por evasivas
• transferByEvasionPercentage: percentual de transferências por evasivas
• totalTimeOfContact: tempo total de atendimento
• totalAvgTimeOfContact: tempo médio de atendimento
• userCount: quantidade de usuários
• newUserCount: quantidade de novos usuários
• newUserPercentage: percentual de novos usuários
• recurrentUserCount: quantidade de usuários recorrentes
• recurrentUserPercentage: percentual de usuários recorrentes
• SimultaneousUserCount: quantidade de usuários simultâneos
• yesCount: quantidade de 'sim'
• noCount: quantidade de 'não'
• likeCount: quantidade de 'gostei'
• unlikeCount: quantidade de 'não gostei'
• withoutInformationCount: quantidade de sem informação
• wrongAnswerCount: quantidade de respostas incorretas
• notAnsweredCount: quantidade sem resposta

Método Reports -> HiBot -> Evaluation

• Objetivo: Avaliação do HiBot.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtbot/evaluation
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros obrigatórios:

Os campos obrigatórios restringem o intervalo de busca de volumetria e o tipo de quebra

• startDate: data/hora inicial, no formato epoch;
• endDate: data/hora final, no formato epoch.
• departmentId: id do departamento que deseja extrair os dados.
• groupBy: formato que deseja agrupar os dados. Os formatos válidos p/ este campo são: groupByDay (p/ agrupar por dia) e groupByMonth (p/ agrupar por mês)
• formId: id do formulário que deseja extrair os dados.
• viewMode: formato que deseja listar os dados. Os formatos válidos p/ este campo são: GroupByDate (p/ exibir os dados agrupados somente por dia; neste formato de visualização, o campo de retorno evaluationsByPeriod será alimentado com as informações) e GroupByDateAndEvaluation (p/ exibir os dados agrupados por dia e nota de avaliação; neste formato de visualização, o campo de retorno evaluationsByPeriodAndEvaluation será alimentado com as informações).

O intervalo máximo de busca permitido é de 30 dias.
O resutado das consultas será sempre ordenado pela data que o intervalo passado se refere.

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

Se a operação for corretamente processada a resposta será (exemplo retornando visualização com viewMode: GroupByDate):

200 OK
Content-Type: application/json
{
    "items": [
        {
            "questionName": "Pergunta 1",
            "evaluationValuePeriod": 5.09090909090909,
            "evaluationsByPeriod": [
                {
                    "date": "2018-09-24T00:00:00",
                    "value": 5.625
                },
                {
                    "date": "2018-09-25T00:00:00",
                    "value": 3.66666666666667
                }
            ],
            "evaluationsByPeriodAndEvaluation": null
        }
    ],
    "totalResults": 1,
    "totalPages": 0,
    "pageNumber": 1
}

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

• questionName: texto da questão
• evaluationValuePeriod: média ponderada das avaliações do período
• evaluationsByPeriod: lista com os dados das datas e valores as médias das notas; este campo será populado sempre que o parâmetro viewMode = GroupByDate
• evaluationsByPeriodAndEvaluation: lista os dados das avaliações, agrupados por dia e avaliação; este campo será populado sempre que o parâmetro viewMode = GroupByDateAndEvaluation

Método Reports -> HiChat -> Queue

• Objetivo: Informações em near real time sobre a situação atual das filas de atendimento de chat para os departamentos.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtchat/queue
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

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

X-Pagination-TotalResult: Total de resultados.

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros opcionais:

• departmentId: o id do departamento (guid) que se deseja monitorar;

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
	[
		{
			"departmentId": "...",
			"departmentName": "...",
			"customersInQueue": ...,
			"waitingTime": "..."
		}, 
		...	
	]
}

Caso a chamada tenha sido filtrada por departamento, será exibido apenas o departamento especificado.

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

• departmentId: Id do departamento de chat;
• departmentName: nome do departamento de chat;
• customersInQueue: número de consumidores aguardando na fila do chat deste departamento, no momento da consulta;
• waitingTime: o tempo de espera do consumidor em primeiro lugar na fila de atendimento, no momento da consulta, ou seja, o maior tempo de espera em fila.

Método Reports -> HiChat -> Volumetry

• Objetivo: Volumetria do HiChat.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtchat/volumetry
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Os resultados não serão paginados.

X-Pagination-TotalResult: Total de resultados.

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros opcionais:

• departmentId: o id do departamento que se deseja monitorar;
• date: data do atendimento no formato epoch. Se esse parâmetro estiver vazio, deve retornar a data atual.
• interval: informação do intervalo desejado. São válidos intervalos cravados à partir de “00:00:00” de 15 em 15 minutos, ou seja, são formatos válidos de intervalos: “00:00:00”, “00:15:00”, “10:45:00”, “15:00:00”, “23:45:00” etc. Se esse parâmetro estiver vazio, o intervalo em minutos da API deve corresponder ao último quarto fechado,tendo como referência a data da consulta, exemplo: se a consulta tenha sido feita as 15:02, o intervalo de busca deve considerar 14:45 a 15:00, e assim por diante.

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
<headers de rate limiting e paginação conforme descrito nas seções anteriores>
{
    [
        {
            "date": ...,
            "interval": "...",
            "departmentId": "...",
            "departmentName": "...",
            "averageQueueTime": "...",
            "averageOperationTime": "...",
            "averageTotalTime": "...",
            "quantityReceived": ...,
            "quantityAttended": ...,
            "quantityAbandoned": ...,
            "queueTimeGreater60s": ...,
            "queueTimeUntil60s": ...,
            "queueTimeUntil30s": ...,
            "queueTimeUntil20s": ...,
			"queueTimeAttendedGreater60s": ...,
            "queueTimeAttendedUntil60s": ...,
            "queueTimeAttendedUntil30s": ...,
            "queueTimeAttendedUntil20s": ...,
            "connectedOperators": ...,
            "activeWindows": ...
        },
        ...
    ]
}

Caso a chamada tenha sido filtrada por departamento, será exibido apenas o departamento especificado.
Cada elemento (item) do corpo possui os seguintes campos:

• date: a data onde os atendimentos foram finalizados (epoch);
• interval: identifica o horário de início do intervalo de análise. Ou seja, à partir desse horário, na data especificada, por 15 minutos, foram consolidadas as informações exibidas para os atendimentos finalizados nesse intervalo;
• departmentId: Id do departamento de chat;
• departmentName: nome do departamento de chat;
• averageQueueTime: tempo médio de fila calculado entre todos os atendimentos finalizados neste intervalo. Exemplo: a operação finalizou entre 00:00:00 e 00:00:15 quatro atendimentos, dois sem fila e outros dois que aguardaram 10 minutos cada em fila. O averageQueueTime informado será de “00:05:00” (cinco minutos);
• averageOperationTime: tempo médio que os consumidores atendidos no período estiveram com o operador. Serão computados apenas atendimentos que foram de fato entregues à operação. Exemplo: a operação finalizou entre “00:00:00” e “00:00:15” quatro atendimentos, dois desses consumidores chegaram a receber atendimento com operadores, tendo cada atendimento durado 10 minutos. Outros dois consumidores abandonaram o atendimento enquanto ainda estavam em fila. O averageOperationTime informado será de “00:10:00”;
• averageTotalTime: tempo médio total de atendimento, contemplando todos os atendimentos finalizados no intervalo, inclusive os abandonos em fila. Exemplo: a operação finalizou entre “00:00:00” e “00:00:15” quatro atendimentos. O primeiro ficou 10 minutos em fila e abandonou. O segundo ficou 10 minutos em fila, chegou ao operador e recebeu atendimento por mais 10 minutos. O terceiro e o quarto não passaram pela fila, tendo sido atendidos por operadores durante cinco minutos cada. O averageTotalTime informado será de “00:10:00”;
• quantityReceived: quantidade total de atendimentos que compõe o intervalo (consideramos atendimentos que foram finalizados no intervalo);
• quantityAttended: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat (consideramos atendimentos que foram finalizados no intervalo);
• quantityAbandoned: quantidade de atendimentos que foram abandonados em fila durante o intervalo;
• queueTimeGreater60s: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior a 60 segundos;
• queueTimeUntil60s: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior 30 segundos e menor ou igual a 60 segundos;
• queueTimeUntil30s: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido superior 20 segundos e menor ou igual a 30 segundos;
• queueTimeUntil20s: quantidade de atendimentos que passaram pela fila cujo tempo de espera tenha sido igual ou inferior a 20 segundos;
• queueTimeAttendedGreater60s: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior a 60 segundos;
• queueTimeAttendedUntil60s: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior 30 segundos e menor ou igual a 60 segundos;
• queueTimeAttendedUntil30s: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido superior 20 segundos e menor ou igual a 30 segundos;
• queueTimeAttendedUntil20s: quantidade de atendimentos que efetivamente receberam atendimento por operadores de chat e que passaram pela fila cujo tempo de espera tenha sido igual ou inferior a 20 segundos;
• connectedOperators: uma fotografia, do início do intervalo, para o número de operadores de chat conectados na ferramenta naquele momento;
• activeWindows: uma fotografia, do início do intervalo, para o número de janelas de atendimento ativas naquele momento.

Método Agent Events

• Objetivo: Busca dos Eventos de operadores.
• URL: https://api.directtalk.com.br/1.10/info/reports/platform/agentevents
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Como essa consulta pode potencialmente retornar muitos registros, os resultados serão sempre paginados.

Para auxiliar na navegação nos resultados, em todas as requisições serão devolvidos os seguintes headers HTTP:

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/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.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=136

Resultado possível:

200 OK
Content-Type: application/json
X-Rate-Limit-Limit: 60
X-Rate-Limit-Remaining: 59
X-Rate-Limit-Reset: 600
X-Pagination-TotalResults: 1035
X-Pagination-TotalPages: 518
Link: <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=1\>; rel="First", 
      <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.10/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=518\>; rel="Last"

{
    [
			{	    			
			    "agentName":"José da Silva",
				"agentLogin":"tst.josesilva",
			    "event":"Conectar Canal",
			    "channel":"DTChat",
			    "description":null,
				"session":"4",
			    "date":1434216932			    
			},
			{	    			
			    "agentName":"José da Silva",
				"agentLogin":"tst.josesilva",
			    "event":"Conectar Canal",
			    "channel":"DTMail",
			    "description":null,
			    "session":"5",
			    "date":1434216992			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Solicitou pausa",
			    "channel":"Todos",
			    "description":"pausa exemplo",
			    "session":"4 | 5",
			    "date":1434217232			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Entrou em pausa",
			    "channel":"Todos",
			    "description":"pausa exemplo",
			    "session":"4 | 5",
			    "date":1434217260			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Saiu em pausa",
			    "channel":"Todos",
			    "description":"pausa exemplo",
			    "session":"4 | 5",
			    "date":1434217800			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Solicitou desconexão",
			    "channel":"DTMail",
			    "description":"",
			    "session":"5",
			    "date":1434218100			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Desconectar Canal",
			    "channel":"DTMail",
			    "description":null,
			    "session":"5",
			    "date":1434218105			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Solicitou desconexão",
			    "channel":"DTChat",
			    "description":"",
			    "session":"4",
			    "date":1434218130			    
			},
			{	    			
			    "agentName":"José da Silva",
			    "agentLogin":"tst.josesilva",
			    "event":"Desconectar Canal",
			    "channel":"DTChat",
			    "description":null,
			    "session":"4",
			    "date":1434218140			    
			}
    ]
}

Método Reports -> HiBot -> Volume e Retenção

• Objetivo: Volume e Retenção do Bot.
• URL: https://api.directtalk.com.br/1.10/info/reports/dtbot/volumeRetention
• Método HTTP: GET
• Passagem de parâmetros: via query string

Parâmetros de rate limiting

• Limite de requisições: 100
• Janela de tempo: 1 minuto

Paginação

Os resultados não serão paginados.

X-Pagination-TotalResult: Total de resultados.

Utilização

Todas as chamadas devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros Obrigatórios:

• startDate: data/hora inicial, no formato epoch;
• endDate: data/hora final, no formato epoch.
• departmentId: o id do departamento que se deseja buscar os dados;
• groupby: tipo de agrupamento que os dados exibidos. Os tipos podem ser: groupbyHour - retorna o volume e retenção agrupados por hora. groupbyDay - retorna o volume e retenção agrupados por dia. groupbymonth - retorna o volume e retenção agrupados por mês.

Para os agrupamentos groupbyHour e groupbyday, o período máximo de datas é de 90 dias. Já para o agrupamento groupbyMonth o período máximo de datas é de 12 meses.

Se forem passados parâmetros inválidos, a API devolverá um status code HTTP 400 (Bad Request).

Exemplo de utilização

Este exemplo realiza a busca da quantidade de atendimentos e da quantidade de atendimentos retidos do Bot no intervalo de tempo entre 01/05/2018 00:00:00 e 10/06/2015 23:59:59 PM para o departamento 7f7bec33-1f55-4ced-8f1b-7c204f35e12b , agrupando o resultado por dia (groupbyday)

A requisição é a seguinte:

https://api.directtalk.com.br/1.10/reports/dtbot/volumeRetention?startdate=1525132800&enddate=1528675199&DepartmentId=7f7bec33-1f55-4ced-8f1b-7c204f35e12b&GroupBy=groupbyDay

Resposta

Se o servidor falhar ou tiver algum problema para processar a requisição, será devolvido um status code HTTP da família 500 (Ex.: 503 Service Unavailable), e o corpo da resposta virá no seguinte formato:

{"message": "descrição do erro"}

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

200 OK
Content-Type: application/json
[
    {
        "date": 1483228800,
        "volume": 370,
        "retention": 303,
		"difference": "82%"
    },
    {
        "date": 1485907200,
        "volume": 106,
        "retention": 89,
		"difference": "84%"
    }
    ...
    
]

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

• date: a data correspondente em formato (epoch);
• volume: a quantidade de atendimentos realizados no bot;
• retention: a quantidade de atendimentos retidos no bot;
• difference: a diferença em % da retenção pelo volume;

Artigos relacionados:

Gestão de usuários de API