API HI CHAT MOBILE BETA

# API Chat Mobile Beta

Essa é uma API beta para integração de clientes externos com o DT Chat. O fato da API ser beta significa que as operações aqui descritas:

• Provavelmente sofrerão mudança
• Ainda não contemplam a totalidade das funcionalidades
• Contém bugs e comportamentos não previstos

Resumo

Em sua versão atual a API contempla três operações RESTful, uma para iniciar o atendimento, uma para receber mensagens e outra para enviar mensagens

Para realizar um atendimento o client deverá:

1. Chamar a operação de incio de atendimento enviando os dados da pesquisa inicial
2. Chamar a operação de busca de mensagens recebidas em intervalos de tempos determinados pelos headers da resposta
3. Chamar a operação de envio de mensagens quando o usuário enviar uma mensagem

Passo-a-passo

Antes de iniciar o atendimento você precisará saber:

1. O endereço do endpoint da API, o endereço padrão é: https://chat-api.directtalk.com.br/chat
2. O id do departamento
3. O id da pesquisa inicial
4. O id de cada um dos campos da pesquisa inicial
5. Usuário e senha de acesso à API

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 é restaurado.

• X-Rate-Limit-Limit : informa o total de requisições permitidas dentro de uma janela de X minutos. (600 requisições)
• X-Rate-Limit-Remaining : requisições para aAPI, ainda são permitidas dentro da janela de X minutos corrente. (10 minutos)
• X-Rate-Limit-Reset : devolve o número de segundos da janela atual.

Iniciando o atendimento

POST https://chat-api.directtalk.com.br/chat
Authorization: {dados-de-autenticação}
Content-Type: application/json
Accept: application/json

{
    "name": "{nome-do-cliente}",
    "origin": "{origem-do-atendimento}",
    "departmentId": {id-departamento},
    "initialSurvey": {
        "id": {id-pesquisa},
        "answers": [
            {
            "questionId": {id-pergunta},
            "answer": "{resposta}"
            },
            {
            "questionId": {id-pergunta},
            "answer": "{resposta}"
            },
            ...
        ]
    }
}

O campo origin é um campo string, obrigatório, que serve para identificar a origem do atendimento.

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

201 Created
X-Rate-Limit-Limit: {quota-total} 
X-Rate-Limit-Remaining: {quota-restante} 
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}
Location: https://chat-api.directtalk.com.br/chat/{id-atendimento}
{
    "state" : "{READY|WAITING}"
}

Se o campo state voltar com o estado READY, o atendimento será encaminhando para um atendente imediatamente e a troca de mensagens poderá ser iniciada.

Se o campo state voltar com o estado WAITING, o atendimento ficará na fila de espera para ser encaminhado para um atendente, o cliente pode enviar mensagens normalmente e as mensagens serão exibidas para o cliente assim que esse receber o atendimento.

Em ambos os casos o restante do atendimento acontecerá através do URL devolvido no hedear Location da resposta acima.

Se o atendimento não puder ser criado por indisponibilidade de operadores, horário de atendimento, fila cheia ou qualquer outro motivo “temporário”, a resposta será:

200 OK
X-Rate-Limit-Limit: {quota-total}
X-Rate-Limit-Remaining: {quota-restante}
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}
{
    "state" : "TEMPORARILY_UNAVAILABLE"
    "message": "mensagem"
}

Nesse caso o campo message poderá conter uma mensagem para o usuário, indicando o motivo do atendimento não ter sido criado e solicitando que entre em contato mais tarde.

Recebendo eventos

Para iniciar o recebimento de eventos, o cliente deverá enviar a requisição abaixo para o URL devolvido pela requisição de início de atendimento acrescida do sufixo /events

GET https://chat-api.directtalk.com.br/chat/{id-atendimento}/events
Authorization: {dados-de-autenticação}
Content-Type: application/json
Accept: application/json

Caso não exista mensagem para ser baixada, a resposta será:

204 No Content
X-Rate-Limit-Limit: {quota-total}
X-Rate-Limit-Remaining: {quota-restante}
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}
Link: ; rel="ack"

Caso exista mensagem, a resposta será:

200 OK
X-Rate-Limit-Limit: {quota-total}
X-Rate-Limit-Remaining: {quota-restante}
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}
Link: ; rel="ack"
[  
   {  
        "date":{data-eventos-epoch-milisegundos},
        "message":"{mensagem}",
        "senderName":"{nome-do-remetente}",
        "kind":"{tipo-do-evento}",
   },
   ...
]

• Mensagens enviadas pelo próprio usuário não aparecerão na resposta.
• As mensagens são enviadas para o cliente em “pacotes de eventos”, o cliente confirma o recebimento do pacote através do ACK, conforme descrito em maiores detalhes abaixo.
• O campo kind descreveo tipo do evento, atualmente o único evento existente é do tipo message, no futuro novos tipos serão adicionados, os clientes devem ignorar eventos com kind te tipos desconhecidos, isso evitará que o cliente tenha probelmas quando novos eventos forem adicionados.
• Todas as datas estão expressas em milisegundos a partir de 01/01/1970 às 00:00:00, esse formato é conhecido como epoch ou unix time, alguns sistemas usam essa representação em segundos. No entanto, essa api utiliza em milisegundos, cuidado para não se confundir. Mais informações sobre unix time: https://pt.wikipedia.org/wiki/Era_Unix

Para buscar novas mensagens o cliente deve enviar uma nova requisição para o URL informado no header Link com rel=”ack”, mais informação sobre esse header pode ser encontrada na RFC5226. O papel do ACK é confirmar o recebimento das mensagens pelo cliente.

GET https://chat-api.directtalk.com.br/chat/{id-atendimento}/events?ack={ack}
Authorization: {dados-de-autenticação}
Content-Type: application/json
Accept: application/json

Enviando mensagens

Para enviar uma mensagem deve ser feito um POST conforme exemplo abaixo:

POST https://chat-api.directtalk.com.br/chat/{id-atendimento}/messages
Authorization: {dados-de-autenticação}
Content-Type: application/json
Accept: application/json

{
    "message": "conteudo da mensagem"
}

Em caso de sucesso, a respostas será:

204 No Content
X-Rate-Limit-Limit: {quota-total}
X-Rate-Limit-Remaining: {quota-restante}
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}

Limites de Requisições (Rate Limit)

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, é fundamental para garantir a qualidade do serviço.

A cada dez minutos o cliente tem direito a fazer um determinado número de requisições. Passado esse tempo, o limite é reiniciado.

O consumo do limite deve ser acompanhado pelos seguintes http headers:

Requisições enviadas após o limite ter sido atingido serão respondidas da seguinte forma:

429 Too Many Requests
X-Rate-Limit-Limit: {quota-total}
X-Rate-Limit-Remaining: 0
X-Rate-Limit-Reset: {segundos-restantes-na-janela-atual}

Nessa situação o cliente deve aguardar até o horário informado no header X-Rate-Limit-Reset e reenviar a requisição.

As operações dessa API estão divididas em dois grupos que possuem controles de limites independentes:

1. operações que acontecem no escopo do atendimento, são as operações executadas em URIs iniciados com /chat/{id-atendimento};
2. operações que acontecem no escopo geral, que são todas as outras operações.

As requisições do primeiro grupo possuem limites independentes para cada atendimento ou seja, requisições enviadas para um determinado atendimento não afetam o limite de outro atendimento.

As requisições do segundo grupo possuem limite único.

Autenticação

A autenticação é feita através do header http Authorization, esse header deve ter a seguinte forma:

Authorization: Basic {base64-string}

O valor de {base64-string} pode ser obtido executando a função base64 na string {usuário-da-api}:{senha-da-api}, exemplo: se o usuário for “usuario” e a senha for “senha”, devemos executar base64(usuario:senha), portanto o header ficaria assim:

Authorization: Basic dXN1YXJpbzpzZW5oYQ==

Esse mecanismo é conhecido como HTTP Basic Authorization.

Duração e finalização do atendimento

Por enquanto não existe operação para finalizar o atendimento pelo lado do cliente. O atendimento será finalizado sempre que:

• o limite definido na configuração do “Tempo de inatividade” ou “Time-out de mensagem” for atingido; ou
• o atendimento for explicitamente encerrado pelo operado

Quando o atendimento é finalizado, chamadas para recebimento ou envido de mensagens passam a devolver 404 Not Found. A aplicação cliente pode reiniciar o atendimento submetendo um novo request na API de inicio de atendimento, podendo inclusive tornar invisível ao consumidor o fato do atendimento ter sido encerrado.

Artigos relacionados:

Gestão de usuários de API