Versão 1.8 - API INFO

Versão 1.8

Endereço base

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

Autenticação / Autorização

Uma  plataforma HI irá fornecer um usuário e uma senha de acesso exclusivo para uso da API. Saiba mais!

A autenticação da  API será feita usando o protocolo  Básico  .

Vamos descrever rapidamente ou como usar 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 separada por :. No nosso exemplo usuarioApi:senhaApi;
• Codifique o resultado acima usando o formato Base64 . No nosso exemplo ou exemplo de resultado (* token *) dessa operação é dXN1YXJpb0FwaTpzZW5oYUFwaQ==.

O  token deve ser passado em todas as requisições através do  cabeçalho Autorização HTTP . O valor do  cabeçalho é uma junção do esquema de autenticação (no caso  Básico ) 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 contrário, tente acessar com um usuário e senha da  Plataforma Hi , mas que não seja um usuário da  API ou 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 de quantidade de requisitos que pode ser enviado em um período de tempo. Essa prática é conhecida como  Limitar a taxa é 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 requisitos. Passado ou tempo especificado, ou limite é restaurado.

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

• X-Rate-Limit-Limit : informações sobre o total de requisitos permitidos dentro de uma janela de X minutos.
• X-Rate-Limit Resting : requisições para uma API, ainda são permitidas na janela de X minutos atuais. Se uma requisição for a mesma depois do valor retornado 0, uma API retornará o código de status HTTP 429 (Muitas conexões.) .
• X-Rate-Limit-Reset : devolve o número de segundos da janela atual.

# API: informações #

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

Contato

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

Parâmetros de limitação de taxa

• Limite de requisitos: 100
• Janela de tempo: 1 minuto

Paginação

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

Para navegação auxiliar nos resultados, em todas as requisições serão retornados 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/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 presença 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 manterá os 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 formatoepoch ;
• endDate: data / hora final do atendimento, nenhuma formatepoch;

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 datasstartDate eendDate 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 formatoepoch ;
• contactStartedDate: data na qual o operador começou a atender, no formatoepoch ;
• contactFinishedDate: data na qual o atendimento foi finalizado, no formatoepoch ;
• 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 decontato: 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 deemail . Informa por qual-fila dee-mail o atendimento está atualmente;
• mailStartQueue: campo específico para atendimentos deemail . Informa por qual fila deemail 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 PMe 13/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/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.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

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

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 mensagemepoch ;
• texto: texto da mensagem;

Método Contacts -> Anexos

• Objetivo: Artigos acessados no HiBot.
• URL: https://api.directtalk.com.br/1.8/info/contacts/{id}/attachments/{attachmentId}
• Método HTTP: GET
• Passagem de parâmetros: via query string

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

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

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 formatoepoch ;
• endDate: data / hora final, no formatoepoch;
• 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 formatoepoch ;
• 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

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

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 formatoepoch ;
• endDate: data / hora final, no formatoepoch .
• 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

• Objetivo: Informações em tempo real sobre as filas de atendimento de chat para os departamentos.
• URL: https://api.directtalk.com.br/1.8/info/reports/dtchat/queue
• Método HTTP: GET
• Passagem de parâmetros: via query string

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

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

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

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

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 formatoepoch ;
• endDate: data / hora final do evento, nenhuma formatepoch .

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

Exemplo de uso

Este exemplo permite uma busca de eventos de operadores no intervalo de tempo entre 13/06/2015 1:46:40 PMe 13/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

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

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 formatoepoch ;
• endDate: data / hora final, no formatoepoch .
• 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 groupbyHoure groupbyday, 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:00e 10/06/2015 23:59:59 PMpara o departamento 7f7bec33-1f55-4ced-8f1b-7c204f35e12b, agrupando o resultado por dia ( groupbyday)

Uma requisição é a seguinte:

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

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 empreendimentos realizados no bot;
• retenção : uma quantidade de empreendimentos retidos no bot;
• diferença : uma diferença em% de retração pelo volume;

Artigos relacionados:

Gestão de usuários de API