API INFO – Versão 1.8


Versão 1.8


Endereço base

Autenticação / Autorização

Uma plataforma Hi irá fornecer um usuário e uma senha 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 utilizando o protocolo Basic.

Considère hipoteticamente Que o Usuário da API Passado e usuarioApiEA Senha E 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](https://pt.wikipedia.org/wiki/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 cabeçalho HTTP Authorization . O valor do cabeçalho é uma junção do esquema de autenticação (no caso Basic ) com o token anterior, por um espaço em branco. Exemplo:

Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==

Caso o protocolo de status seja inválido, o acesso será negado e um código de status HTTP 401 (Não autorizado) será devolvido. Caso, tente acessar com um usuário e senha da Plataforma Hi , mas que não seja um usuário da API o acesso será negado e um código de status HTTP 403 (Proibido) será devolvido.

Cotas de consumo

O cliente que usa essa API está sujeito a um limite na quantidade de requisições que podem ser enviadas em um 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 tipo de solicitação) cada usuário tem o direito a um número fixo de requisições. Passado o tempo especificado, o limite é restauriado.

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 : requisições para a API, ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição para a mesma depois desse valor retornado 0, uma API retornará o código de status HTTP 429 (Too many connections.) .
  • X-Rate-Limit-Reset : devolve o número de segundos da janela atual.

API: informações #

Objetivo: Prover as informações de plataforma de soluções da plataforma Hi.

Contato

Parâmetros de limitação de taxa

  • 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.8/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First",
<https://api.directtalk.com.br/1.8/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous",
<https://api.directtalk.com.br/1.8/info/contacts?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next",
<https://api.directtalk.com.br/1.8/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: uma página atual para a primeira, então o link “Anterior” não está disponível.

Outro ponto importante é quanto aos parâmetros. Uma API irá manter os seus resultados da primeira consulta controlada.

Utilização

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

Parâmetros obrigatórios:

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

  • startDate: dados / hora inicial do atendimento, sem formato epoch ;
  • endDate: data / hora final do atendimento, nenhuma format epoch;

O horário máximo de viagem é de 31 dias. O resutado de sessions será sempre ordenado pelos dados que separam o intervalo se refere.

Parâmetros opcionais:

  • canal: canal de comunicação onde o atendimento ocorreu. Valores Possíveis para ESSE campo:HiChat,HiMail,HiPhone,HiBot. Se o pedido não for especificado, serão devolvidos os pedidos de todos os canais na consulta;
  • pageNumber: número da página que é necessário para essa requisição. Se este parâmetro não foi para o passado ou para maior do que uma quantidade de páginas disponíveis, será assumida a página 1 da página 1;
  • pageSize : uma quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se este parâmetro não for passado, será assumido o valor 1000;
  • dateInfo: parâmetro que informa sobre qual é o dado que deve ser fornecido com as datas startDate e endDate dizem respeito. Esse parâmetro tem duas opções:onSystem(dados de acesso ao sistema) econtactFinished(dados que o atendimento foi finalizado). Se esse parâmetro não for passado, será assumido o valorcontactFinished.
  • identificações: chaves de identificação foram usadas como filtro. Somente atendimentos que possuírem as chaves informadas serão retornados. Deve 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.

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma requisição para o bem sucedido, uma resposta será:

Se uma 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 usuário que atendeu o cliente;
  • groupName: nome do grupo ao qual o operador pertence;
  • canal: canal no qual o atendimento foi feito;
  • departmentName: nome do departamento não qualificado ou atendimento feito;
  • onSystemDate: data de entrada do atendimento sem 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 que ficou em fila;
  • agentServingTime: tempo em segundos que o operador ficou atendendo ao cliente;
  • contactTotalTime: duração total do atendimento em segundos;
  • estado de contato: estado no qual o atendimento se encontra;
  • contactStateDetail: descrição mais completa do estado;
  • classificações: lista de medidas atribuídas ao atendimento;
  • mailQueue: campo específico para atendimentos de email . Informa por qual-fila de e-mail o atendimento está atualmente;
  • mailStartQueue: campo específico para atendimentos de email . Informa por qual fila de email ou atendimento entrou;
  • origem: origem do atendimento;
  • identificações: lista de chaves utilizadas para atendimento;
  • formAnswers: lista de perguntas e respostas derivadas do formulário de classificação do atendimento.
  • classificações: lista com as avaliações do atendimento;

Exemplo de uso

Este exemplo apresenta uma busca de empreendimentos HiChatfeitos com dados de entrada no sistema está no intervalo de tempo entre 13/06/2015 1:46:40 PM13/06/2015 2:53:20 PM. Além disso, vamos pedir apenas 10 registros por página e número de página.

Uma requisição é a seguinte:

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.8/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=1\>; rel="First", 
      <https://api.directtalk.com.br/1.8/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.8/info/contacts?startDate=1434214000&endDate=1434218000&channel=DTChat&dateInfo=onSystem&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.8/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

Parâmetros de limitação de taxa

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

Utilização

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

Parâmetros obrigatórios:

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

  • id: id do atendimento;

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma requisição para o bem sucedido, uma resposta será:

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

200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
    //Resposta para os canais chat e bot
    "customer": {
        "email": "teste@teste.com"
    },
    "propeties": [
        {
            "key": "ip",
            "value": "200.86.120.53"
        },
        {
            "key": "knowledgeBaseId",
            "value": "0adbd202-d12d-4543-b0a9-8c2df45228d5"
        },
        {
            "key": "ipCity",
            "value": "Sao Paulo - Brazil"
        },
        {
            "key": "browserVersion",
            "value": "61.0.3163"
        },
        {
            "key": "departmentId",
            "value": "06e006fb-5fec-4d5c-a733-16b8b14bc50a"
        },
        {
            "key": "platform",
            "value": "Windows"
        },
        {
            "key": "nome_usuario",
            "value": "Teste"
        },
        {
            "key": "browser",
            "value": "Chrome"
        },
        {
            "key": "email",
            "value": "teste@teste.com"
        },
        {
            "key": "retention",
            "value": "True"
        }
    ],
    "startDate": "1536858065",
    "endDate": "1536858065",
    "origin": "DTBot",
    "state": "Em andamento",
    "messages": [
        {
            "sender": "DTBot",
            "date": 1507666554,
            "text": "Olá! Bem-vindo, como posso te ajudar?"
        },
        {
            "sender": "Teste",
            "date": 1507666556,
            "text": "Bom dia"
        }
    ],
    "attachments": [
        {
		"id": "8b5831c1-f111-46e5-a86f-6540792e092a",
		"size": "5000",
		"name": "file.jpg"
	    }
	 ]
}
200 OK
Content-Type: application/json
<headers de rate limiting conforme descrito nas seções anteriores>
{
    //Resposta para o canal email
    "subject": "teste anexo2",
    "account": "mdirecttalk41@gmail.com <mdirecttalk41@gmail.com>",
    "rule": "Regra Padrão",
    "id": 595811,
    "events": [
        {
            "date": 1536858065,
            "message": "Mensagem enviada pelo cliente"
        },
        {
            "date": 1536858824,
            "message": "Mensagem incluída no sistema"
        },
        {
            "date": 1536858840,
            "message": "Mensagem movida para a fila Fila Padrão pela regra Regra Padrão"
        }
    ],
    "customer": {
        "email": "customer@customerdomain.com"
    },
    "propeties": [
        {
            "key": "retention",
            "value": "True"
        }
    ],
    "startDate": 1536858065,
    "endDate": 1536858840,
    "state": "Na fila",
    "messages": [
        {
            "sender": "customer@customerdomain.com",
            "date": 1536858065,
            "text": "<div dir=\"ltr\">anexos</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"
        }
    ]
}

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

IMPORTANTE: As mensagens de propriedade estão disponíveis para atendimentos do HiChat , HiBot e HiMail .

  • remetente: quem enviou uma mensagem;
  • data: data da mensagem epoch ;
  • texto: texto da mensagem;

Método Contacts -> Anexos

Parâmetros de limitação de taxa

  • 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 figado Algum Problema para Processar a requisição, Sera devolvido hum status HTTP Código da Família 500 (Ex .: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma operação para o processo de processamento de um código de acesso http 200. Através do cabeçalho de resposta da requisição há um valor da chave Conteúdo-Disposição do arquivo, como no exemplo abaixo: Content-Disposition: attachment; filename = “filename.jpg”

Relatórios de Método -> HiBot -> ArticleHits

Parâmetros de limitação de taxa

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

Paginação

Os resultados serão sempre paginados.

Para auxiliar a navegação nos resultados, em todas as requisições são devolvidos os seguintes cabeçalhos HTTP :


X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.                                                            Link: <https://api.directtalk.com.br/1.8/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First",
<https://api.directtalk.com.br/1.8/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous",
<https://api.directtalk.com.br/1.8/info/reports/dtbot/articlehits?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next",
<https://api.directtalk.com.br/1.8/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: uma página atual para a primeira, então o link “Anterior” não está disponível.

Outro ponto importante é quanto aos parâmetros. Uma API irá manter os seus resultados da primeira consulta controlada.

Utilização

Todas as classes 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, sem 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 é necessário para essa requisição. Se este parâmetro não foi para o passado ou para maior do que uma quantidade de páginas disponíveis, será assumida a página 1 da página 1;
  • pageSize : uma quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se este parâmetro não for passado, será assumido o valor 1000;

O horário máximo de busca é de 90 dias. O resultado será sempre calculado pelos dados da consulta periódica se refere.

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma 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;
  • data: dados do agrupamento no formato epoch ;
  • quantidade: inteiro, quantidade de acessos;
  • pergunta: string, nome da questão;
  • categoria: string, nome da categoria;
  • departamento: departamento, com id e nome;

Relatórios de Método -> HiBot -> Volumetria

Parâmetros de limitação de taxa

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

Paginação

Os resultados serão sempre paginados.

Para auxiliar a navegação nos resultados, em todas as requisições são devolvidos os seguintes cabeçalhos HTTP :


X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.8/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&DepartmentId={Id}&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.8/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&DepartmentId={Id}&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.8/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&DepartmentId={Id}&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.8/info/reports/dtbot/volumetry?startDate=1442007534&endDate=1442007534&DepartmentId={Id}&pageNumber=10&pageSize=1000\>; rel="Last"
      <https://api.directtalk.com.br/1.8/info/reports/dtbot/volumetry?startDate=1544572800&endDate=1544659199&DepartmentId={Id}

É importante notar que a existência de cada link está sujeita ao contexto atual. Por exemplo: uma página atual para a primeira, então o link “Anterior” não está disponível.

Outro ponto importante é quanto aos parâmetros. Uma API irá manter os seus resultados da primeira consulta controlada.

Utilização

Todas as classes 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 é necessário para essa requisição. Se este parâmetro não foi para o passado ou para maior do que uma quantidade de páginas disponíveis, será assumida a página 1 da página 1;
  • pageSize : uma quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se este parâmetro não for passado, será assumido o valor 1000;
  • groupBy: tipo de agrupamento que será aplicado. ‘day’ indica que o choque deve ser por dia. ‘hora’ indica que a mudança deve ser por hora. Este parâmetro não é para o passado, o padrão é ‘day’.

O horário máximo de viagem é de 30 dias. O resutado de sessions será sempre ordenado pelos dados que separam o intervalo se refere.

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma 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:

  • data : data / hora conforme a quebra escolhida, sem formato epoch ;
  • condição : condição
  • dialogCount : quantidade de diálogos
  • interactionCount : quantidade de interações
  • answerCount : quantidade de respostas
  • answerPercentage : percentual de respostas
  • transferCount : quantidade de transfers
  • transferênciaPercentagem : percentual de transferências
  • retentionCount : quantidade de retenções
  • retençãoPercentação : percentual de retenções
  • transferByEvasionCount : quantidade de transferências por evasivas
  • TransferirByEvasionPercentage : 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
  • simContagem : 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 resultados incorretas
  • notAnsweredCount : fonte sem resposta

Relatórios de Método -> HiChat -> Fila

Parâmetros de limitação de taxa

  • 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 classes devem ser autenticadas conforme explicado na seção de autenticação.

Parâmetros opcionais:

  • departamentoId: o id do departamento (guid) que se deseja acompanhar;

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma 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 um dado tenha sido filtrado 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 conversações em fila do chat deste departamento, no momento da consulta;
  • waitingTime : o ritmo de espera do Consumidor em Primeiro lugar na fila de atendimento, nenhum momento da consulta, OU SEJA, o Maior Tempo de espera em fila.

Relatórios de Método -> HiChat -> Volumetria

Parâmetros de limitação de taxa

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

Paginação

Resultados não serão paginados.


X-Pagination-TotalResult: Total de resultados.

Utilização

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

Parâmetros opcionais:

  • departmentId: o id do departamento que se deseja monitorar;
  • data: dados do atendimento no formato epoch. O que deve ser usado vazio, deve ser um dado atual.
  • intervalo: informação do intervalo desejado. São válidos intervalos cravados a partir de “00:00:00” de 15 em 15 minutos, ou seja, são os formatos válidos de intervalos: “00:00:00”, “00:15:00”, “10:45: 00, 15:00:00, 23:45:00 etc. etc. A consulta foi feita com 15:02, o intervalo de uma busca é considerada às 14:45 às 15:00, e assim por diante.

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma 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 um dado tenha sido filtrado por departamento, será exibido apenas o departamento especificado. Cada elemento (item) do corpo possui os seguintes campos:

  • data : um dado onde os atendimentos foram finalizados (época);
  • intervalo : identificar o horário de início do intervalo de análise. Ou seja, ao fim do horário, nos dados editados, por 15 minutos, foram consolidadas como informações para os procedimentos finais nesse intervalo;
  • departmentId : Id do departamento de chat;
  • departmentName : nome do departamento de chat;
  • averageQueueTime : ritmo medio de fila calculado between de Todos os atendimentos finalizados Neste Intervalo. Exemplo: a operação finalizada entre 00:00:00 e 00:00:15 quatro atendimentos, dois sem fila e outros dois que aguardavam 10 minutos cada em fila. O averageQueueTime informado será de “00:05:00” (cinco minutos);
  • averageOperationTime : tempo médio que os satisfatórios atendentes no período estiveram com o operador. Serão computados apenas atendimentos que eram de fato entregues à operação. Exemplo: a operação finalizada entre “00:00:00” e “00:00:15”, quatro atendimentos, dois tipos de restaurantes foram atendidos, tendo cada atendimento durado 10 minutos. Outros dois consumidores abandonaram o serviço como 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 finalizada 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 eo quarto não foram pela fila, tendo sido atendidos por quarto ao longo de três minutos cada. O averageTotalTime informado será de “00:10:00”;
  • quantityReceived: atendimentos com status FINALIZADO e NÃO ATENDIDOS 
  • quantityAttended: atendimentos com status FINALIZADO 
  • quantityAbandoned: atendimentos com status NÃO ATENDIDO
  • queueTimeGreater60s : quantidade de atendimentos na fila com o tempo de espera superior a 60 segundos;
  • queueTimeUntil60s : quantidade de atendimentos na fila com o tempo de espera até  60 segundos;
  • queueTimeUntil30s : quantidade de atendimentos na fila com o tempo de espera até 30segundos;
  • queueTimeUntil20s : quantidade de atendimentos na fila com o tempo de espera até  20 segundos;
  • connectedOperators: quantidade de operadores conectados no período filtrado
  • ActiveWindows : quantidade de janelas ativas no período filtrado

Cenários que podem ocorrer no contexto do que é FINALIZADO e NAO ATENDIDO:

  • FINALIZADO: 
    usuário terminou a conversa
    desconectado pelo operador
    timeout de reload
    timeout de mensagem
    Desconectado pelo Sistema
    Usuário transferido para outro departamento
    Usuário de longa duração em espera desconectado pelo sistema
    usuário de longa duração em espera desconectado pelo operador
    Sessão do usuário de longa duração expirada enquanto estava em espera espera
  • NÃO ATENDIDO: (cenários que se enquadram neste estado)
    Consumidor perdeu conexão na fila
    Consumidor abandonou a fila
    Operadores sairam do sistema com fila
    Consumidor abandonou a fila
    Consumidor perdeu conexão na escolha do operador
    Usuário deslogado durante escolha de operador por não haver mais operadores logados
    Fila cheia

Eventos de agentes

Parâmetros de limitação de taxa

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

Paginação

Como é que uma consulta pode ter muitos registros, os processos serão sempre paginados.

Para auxiliar a navegação nos resultados, em todas as requisições são devolvidos os seguintes cabeçalhos HTTP :


X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://api.directtalk.com.br/1.8/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=1&pageSize=1000\>; rel="First", 
      <https://api.directtalk.com.br/1.8/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=3&pageSize=1000\>; rel="Previous", 
      <https://api.directtalk.com.br/1.8/info/reports/platform/agentevents?startDate=1442007534&endDate=1442007534&pageNumber=5&pageSize=1000\>; rel="Next", 
      <https://api.directtalk.com.br/1.8/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: uma página atual para a primeira, então o link “Anterior” não está disponível.

Outro ponto importante é quanto aos parâmetros. Uma API irá manter os seus resultados da primeira consulta controlada.

Utilização

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

Parâmetros obrigatórios:

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

  • startDate: data / hora inicial do evento, nenhum formato epoch ;
  • endDate: data / hora final do evento, nenhuma format epoch .

O horário máximo de viagem é de 31 dias. O resutado de sessions será sempre ordenado pelos dados que separam o intervalo se refere.

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

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma requisição para o bem sucedido, uma resposta será:

Se uma 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 do usuário;
  • canal: canal no qual operou uma ação;
  • descrição: informação complementar da acção no escritório;
  • sessão: informação de identificação da sessão – para agrupar ações executadas;
  • data: dados na qual o operador executou uma ação, não formato epoch ;

Exemplo de uso

Este exemplo permite uma busca de eventos de operadores no intervalo de tempo entre 13/06/2015 1:46:40 PM13/06/2015 2:53:20 PM. Além disso, vamos pedir apenas 10 registros por página e número de página.

Uma requisição é a seguinte:

https://api.directtalk.com.br/1.8/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.8/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=1\>; rel="First", 
      <https://api.directtalk.com.br/1.8/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=135\>; rel="Previous", 
      <https://api.directtalk.com.br/1.8/info/reports/platform/agentevents?startDate=1434214000&endDate=1434218000&pageSize=10&pageNumber=137\>; rel="Next", 
      <https://api.directtalk.com.br/1.8/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 } ] }

Relatórios de Método -> HiBot -> Volume e Retenção

Parâmetros de limitação de taxa

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

Paginação

Resultados não serão paginados.


X-Pagination-TotalResult: Total de resultados.

Utilização

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

Parâmetros Obrigatórios:

  • startDate: data / hora inicial, sem 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. Os tipos podem ser:groupbyHour– retorna o volume e a perda agrupados por hora. groupbyDay– retorna volume e degress agrupados por dia. groupbymonth– retorna volume e abandono agrupados por mês.

Para os agrupamentos groupbyHourgroupbyday, o período máximo de dados é de 90 dias. Já para o agrupamento groupbyMontho período máximo de dados é de 12 meses.

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

Exemplo de uso

Este exemplo é uma pesquisa sobre a quantidade de atendimentos e a quantidade de atendimentos Botsem intervalo de tempo entre 01/05/2018 00:00:0010/06/2015 23:59:59 PMpara o departamento 7f7bec33-1f55-4ced-8f1b-7c204f35e12b, agrupando o resultado por dia ( groupbyday)

Uma requisição é a seguinte:

Resposta

Se o servidor tiver problemas para processar uma requisição, será devolvido um código de estado HTTP da família 500 (Ex: 503 Service Unavailable ), e o corpo da resposta virá no seguinte formato:

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

Se uma 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:

  • data : um dado correspondente em formato (época);
  • volume : uma quantidade de atendimentos realizados no bot;
  • retenção : uma quantidade de atendimentos retidos no bot;
  • diferença : a diferença em% da retração pelo volume;