API Chat (v1.0) – Status do atendimento


Endereço base

Todos os endereços referenciados neste documento tem como base a seguinte URL :

https://api.directtalk.com.br/1.0/chat

A API do Chat é servida somente sob HTTPS. Para garantir a privacidade das informações, HTTP não criptografado não é suportado.

Autenticação/Autorização

As requisições para a API do Chat são protegidas utilizando Autenticação básica . Em resumo, a HiPlatform irá fornecer um usuário e uma senha exclusivamente para o uso da API, de forma que todas as requisições realizadas devem fornecer estas credenciais.

O cadastro é feito na tela Gestão de usuários de API. Saiba mais

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

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

O consumo do limite pode variar conforme o escopo 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.

Escopos de rate limiting

Nome Limite de requisições Janela de tempo (em minutos) Variável pela rota/query string
Padrão 10 1 Sim

Importante:

  • Certifique-se de checar o escopo de rate limiting no resumo de cada operação.
  • O ratelimiting é por “chatid”

Paginação

Determinadas operações podem potencialmente retornar muitos registros. Nestes casos os resultados serão sempre paginados e os seguintes parâmetros opcionaissão suportados através de query string :

  • pageNumber: Número da página desejada. 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;

Para auxiliar na navegação nos resultados retornados, as operações que requerem paginação devolverão 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.0/chat/...\>; rel="First", 
      <https://api.directtalk.com.br/1.0/chat/...\>; rel="Previous", 
      <https://api.directtalk.com.br/1.0/chat/...\>; rel="Next", 
      <https://api.directtalk.com.br/1.0/chat/...\>; rel="Last"

É importante notar que a existência dos links 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.

Importante: Certifique-se de checar a paginação no resumo de cada operação.

Retornos comuns para todas as operações em caso de erro

Cabeçalhos
Header Valor
Content-Type application/json
Códigos HTTP
HTTP status code Descrição
400 Erro no “formato” da requisição conforme o requisito de cada operação.
401 O header authorization está ausente ou seu conteúdo não pode ser validado contra o serviço de autenticação.
403 As credenciais existem mas são inválidas para uso da API.
429 A cota de consumo foi excedida na janela atual, conforme descrito na seção sobre cotas de consumo.
500 Erro interno não especificado.
Corpo
	{
		"messages": [
						"descrição do erro",
						"descrição do erro",
						"..."
					]
	}

Sub-Recursos


Atendimentos

Consultar o status de um atendimento


Resumo
Informação Valor
Método HTTP GET
URL /status/{id}
Escopo de rate limiting Padrão
Paginação Não se aplica

REQUISIÇÃO

Parâmetros obrigatórios
  • id: Identificador do atendimento.
Formato
  • id informado deve ser um GUID válido.

RESPOSTA

Cabeçalhos em caso de erro (além dos comuns a todas as operações)
Header Valor
HTTP status code 404 (atendimento não existe)
Cabeçalhos em caso de sucesso
Header Valor
HTTP status code 200
Corpo em caso de sucesso
	{
		"id":"...",
		"status": "..."
	}
  • id: GUID que representa o identificador do atendimento.
  • status: Status do atendimento
    • READY: Atendimento iniciado/em andamento
    • PREPARING: Estados intermediários, ou seja, ainda não caiu para o operador. Ex: Fila, associação com operador, criação do atendimento e etc.
    • FINISHED: atendimento encerrado, fila cheia e fora de horário