Versão 1.3 - API de integração da DirectTalk

# API de integração da DirectTalk

## Versão 1.3

Endereço base

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

Autenticação/Autorização

A DirectTalk irá fornecer um usuário e uma senha de acesso exclusivo
para o uso da API. A autenticação da API será feita utilizando o protocolo Basic.

Vamos descrever brevemente o como autenticar usando o protocolo Basic.

Considere hipoteticamente que o usuário da API passado é usuarioApi e a senha é senhaApi.

Primeiro, calcule um token da seguinte forma:

• Concatene o usuario e a senha separado por :. No nosso exemplo usuarioApi:senhaApi;
• Codifique o resultado acima utilizando o formato Base64. No nosso exemplo o exemplo o resultado (token) dessa operação é dXN1YXJpb0FwaTpzZW5oYUFwaQ==.

O token deve ser passado em todas as requisições através do header HTTP Authorization. O valor do header é a junção do esquema de autenticação (no caso Basic) com o token previamente enviado, separados por um espaço em branco. Exemplo:

Authorization: Basic dXN1YXJpb0FwaTpzZW5oYUFwaQ==

Caso o token de autenticação seja inválido, o acesso será negado e um status code HTTP 401 (Unauthorized) será devolvido. Caso, tente acessar com um usuário e senha válidos da DirectTalk, mas que não seja um usuário da API o acesso será negado e um status code HTTP 403 (Forbidden) será devolvido.

Cotas de consumo

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

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

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

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

API: Info

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

Método Contacts

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

Parâmetros de rate limiting

• Limite de requisições: 60
• Janela de tempo: 10 minutos

Paginação

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

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

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: ; rel="First", 
      ; rel="Previous", 
      ; rel="Next", 
      ; 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: DTChat, DTMail, DTPhone. 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.

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

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

Exemplo de utilização

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

A requisição é a seguinte:

https://api.directtalk.com.br/1.2/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: ; rel="First", 
      ; rel="Previous", 
      ; rel="Next", 
      ; rel="Last"

{
    [
            {                   
                "protocolNumber":"12345678-90",
                "agentName":"José da Silva",
                            "agentLogin":"prefixo.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":"prefixo.mariasantos",
                "groupName":"Turno da tarde",
                "channel":"DTChat",
                "departmentName":"Sugestões",
                "onSystemDate":1434216940,
                "contactStartedDate":1434216940,
                "contactFinishedDate":1434217093,
                "customerInQueueTime":0,
                "agentServingTime":153,
                "contactTotalTime":153,
                "contactState":"FINALIZADO",
                "contactStateDetail":"Operador finalizou",
                "contactSource":"Site",
                "classifications":["Melhorias", "Processos"],
                "origin":"bot",
                "origin":"bot",
                "rating": 9,
                "identifications": [
                    {
                        "key": "Consumidor_Chat",
                        "value": "Ed Mort"
                    },
                    {
                        "key": "email",
                        "value": "edmort@lfv.com.br"
                    }
                ],
                "formAnswers": [
                    {
                        "question": "Informe a Data",
                        "answer": "13/06/2015 14:39"
                    }
                ],
                "ratings": []
            }
    ]
}

Artigos relacionados:

Gestão de usuários de API