Pular para o conteúdo principal

Chat API

O Tovie DialogStudio fornece uma API Rest para integração com aplicativos de terceiros. Por exemplo, você pode utilizá-la para implementar um chat em um aplicativo móvel ou um jogo.

dica
A API Rest é uma forma generalizada de transferir dados para serviços de terceiros por meio de solicitações HTTP.

A API permite conversar com bots ou agentes.

Conectando o canal da Chat API​

  1. Acesse as configurações dos Canais do seu chatbot e escolha Chat API.
  2. Preencha o campo Nome do canal.
  3. Você pode deixar o campo Token do bot vazio, e o Tovie DialogStudio o gerará para você.
  4. Ative o botão de alternância Desativar entrada de texto quando usar botões se quiser impedir que os clientes insiram mensagens de texto ao usar botões no script.
  5. Clique em Conectar e aguarde o status Canal conectado.

Token do bot​

dica
O token de que você precisa para que a Chat API funcione será gerado automaticamente.

Para obtê-lo, clique em Copiar token ou abra as configurações do canal e copie o token do campo Token.

Métodos API​

dica
Uma descrição detalhada da Chat API: métodos, parâmetros de solicitação, formatos de resposta, exemplos, erros retornados

Enviando solicitações de cliente para o chat​

Os métodos a seguir são usados para enviar solicitações do cliente:

dica
Você pode enviar consultas de texto ou eventos no aplicativo de chat.

ID de conexão​

O corpo de solicitações para POST /chatapi/{token} pode conter uma propriedade cid opcional — uma string arbitrária que determina a conexão atual com o aplicativo de chat.

Esta string pode ser usada posteriormente para buscar eventos no chat, a fim de filtrar apenas os eventos que ocorreram durante essa conexão.

Procurando eventos assíncronos no chat​

Por meio do método GET /chatapi/{token}/events, você pode receber eventos assíncronos que ocorreram no chat, como:

  • Uma resposta de um agente.
  • Alteração do estado de um widget em outra página do navegador.
  • Uma solicitação de cliente enviada em outra página.
  • Uma resposta do bot a uma solicitação de outra página.
cuidado
Este método implementa a estratégia longa de sondagem. Se nenhum evento for encontrado, o método será bloqueado enquanto estiver aguardando o próximo evento.
O comprimento da resposta do método está limitado a 250 mensagens. Se precisar processar mais eventos do que isso, use o método para buscar o histórico de mensagens de chat.

Filtragem de eventos​

Este método aceita um parâmetro all que determina se todos os eventos no canal devem ser retornados ou só as respostas de agentes (o comportamento padrão).

cuidado
Se o cliente tiver várias conversas simultaneamente e todos os eventos no canal forem devolvidos, podem ser devolvidos eventos duplicados se o parâmetro cid não estiver aprovado.

O parâmetro ts define a hora a partir da qual os eventos devem ser filtrados. Quando omitido, todos os eventos desde a última solicitação ao servidor serão retornados.

Buscando o histórico de mensagens de chat​

O método GET /chatapi/{token}/client/{clientId}/history permite receber o histórico de mensagens com o cliente durante o período de tempo especificado ou todo o tempo disponível.

Salvando e carregando o estado do aplicativo de chat​

Os métodos a seguir permitem salvar e carregar o estado do aplicativo de chat durante a conversa com o cliente:

dica
Um objeto arbitrário é aprovado no corpo da solicitação de método POST. Solicitações subsequentes ao método GET retornarão este objeto como está. O conteúdo não é verificado.