API Chat Mobile


Beta

Essa é uma API beta para integração de clientes externos com o HiChat. 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 eventos de mensagem ou finalização de 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 eventos 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 para criação do atendimento: 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

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: {endereço variável correspondente ao local no qual o atendimento foi criado}/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 completa 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 {URL devolvida no *header* Location da criação do atentimento}/events
Authorization: {dados-de-autenticação}
Content-Type: application/json
Accept: application/json

Caso não exista evento para ser baixado, 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: <{URL devolvida no *header* Location da criação do atentimento}/events?ack={ack}>; rel="ack"

Caso existam eventos de 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: <{URL devolvida no *header* Location da criação do atentimento}/events?ack={ack}>; rel="ack"
[  
   {  
        "date":{data-eventos-epoch-milisegundos},
        "message":"{mensagem}",
        "senderName":"{nome-do-remetente}",
        "kind":"message",
   },
   ...
]

Quando o atendimento for finalizado, 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: <{URL devolvida no *header* Location da criação do atentimento}/events?ack={ack}>; rel="ack"
[  
   {  
        "date":{data-eventos-epoch-milisegundos},
        "reason":"FINISHED",
        "kind":"finished",
   }
]
  • 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 descreve o tipo do evento. Atualmente existem dois tipos de evento: message e finished, no futuro novos tipos serão adicionados, de forma que os clientes devem ignorar eventos com kind cujos tipos são desconhecidos. Isso evitará que o cliente tenha problemas 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 {URL devolvida no *header* Location da criação do atentimento}/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 {URL devolvida no *header* Location da criação do atentimento}/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:

Nome do HeaderValor
X-Rate-Limit-LimitLimite total de requisições na janela de 10 minutos
X-Rate-Limit-RemainingNúmero de requisições que ainda podem ser feitas na janela atual
X-Rate-Limit-ResetNúmero de segundos restantes na janela atual

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 é enviado um evento de finalização conforme descrito na seção “Recebendo eventos”. 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.