API para bots

Incluso gratuitamente nos planos

VIPPRO

Nossa API para bots permite que você conecte plataformas de bots a quaisquer conversas no JivoChat: chat no site, mensagens instantâneas e redes sociais. Ao adicionar um bot, todas as conversas serão primeiramente enviadas ao provedor de bot para processamento.

Se você possui um bot próprio e gostaria de conectá-lo ao JivoChat, por favor envie-nos um email para gerar seu ID de provedor.

Troca de dados

O iniciador da troca é o JivoChat. Isso acontece quando há uma mensagem de entrada de um cliente. Eventos são trocados com provedores de bots usando o mecanismo webhooks. Todos os eventos do JivoChat são enviados ao endpoint do provedor e, em resposta, o provedor envia eventos ao endpoint do JivoChat.

Todos os eventos do JivoChat e do provedor de bot são enviados como requisições HTTPS usando o método POST no formato application/JSON. O tempo limite da solicitação é de 3 segundos e o número de novas tentativas é 2 até que uma resposta regular bem-sucedida seja recebida. Caso contrário, o cliente é transferido para um operador. Isso dá 9 segundos para atualizar o software no servidor, o que é suficiente na maioria dos casos.

A URL de endpoint do provedor de bot é formada a seu critério. O endpoint do JivoChat é configurado no seguinte formato: bot.jivosite.com/webhooks/{id_provedor}, no qual o id_provedor é um identificador único de provedor de bot, gerado e enviado para cada provedor de maneira separada.

Códigos de resposta

A tabela abaixa lista os possíveis códigos de reposta do JivoChat e do provedor de bot.

Códigos de resposta	Descrição
200 OK	Sucesso, resposta padrão
400 Bad Request	Formato de solicitação inválido. Você deve verificar os campos de solicitação para conformidade com o formato da API
401 Unauthorized	Erro de autorização
403 Forbidden	Acesso negado
404 Not Found	Endpoint formado incorretamente
405 Method Not Allowed	Este método ou evento não é compatível
429 Too Many Request	Solicitações excedidas por unidade de tempo
500 Internal Server Error	Erro de processamento de solicitação
502 Bad Gateway	Servidor está sobrecarregado
503 Service Unavailable	Servidor não disponível
504 Gateway Timeout	Falha ao realizar o pedido

Em caso de emergência, recomenda-se que as informações sobre o erro sejam transmitidas no corpo de resposta no seguinte formato:

{
  "error" :
    {
      "code": "<código do erro>",
      "message": "<mensagem de erro legível por humanos>"
    }
}

Códigos de erro

Código	Descrição
invalid_client	Erro de autenticação do token do cliente. Retornado com o código HTTP 401 não autorizado
unauthorized_client	A autorização falhou pelo cabeçalho Autorização
invalid_request	A solicitação não contém um parâmetro obrigatório, um valor de parâmetro não suportado foi usado, há uma duplicata do parâmetro, vários conjuntos de credenciais foram incluídos, ou outros erros de solicitação

Autenticação

A autenticação do cliente do provedor do bot, a partir do qual a API é acessada, é realizada por meio de um token gerado pelo provedor do bot. O cliente recebe o token do provedor do bot e o insere nas configurações do canal do bot conectado no JivoChat. Todas as solicitações do JivoChat para o provedor do bot e vice-versa ocorrem usando esse token, que é passado na URL da solicitação. Formato:

POST https://{bot_endpoint}/token
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/{id_provedor}/{token}
Content-Type: application/json

...

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

POST https://bot.jivosite.com/webhooks/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json

Autorização

Além da autenticação, você pode usar opcionalmente uma medida de segurança adicional na forma de um token de autorização, que é emitido pelo provedor do bot para o JivoChat e tem uma vida útil limitada. Para fazer isso, o JivoChat primeiro recebe um token de acesso temporário em troca de uma chave secreta e do id_cliente, após o qual é transmitido cada vez que o provedor do bot é acessado e de volta no cabeçalho Autorização. Exemplo:

POST https://bot-provider-endpoint.com/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

...

POST https://bot.jivosite.com/providers/Ee0CRkyDAp/zhFZipzT:8560a55a9af37d68782b3234a84f344c592ab766
Content-Type: application/json
Authorization: 92753d11-4aef-459a-8d45-1c1faabb6e36

Tipos de evento

Tipo de mensagem	Caminho	Descrição
CLIENT_MESSAGE	JivoChat API → Bot-Provider	Evento de uma nova mensagem do cliente para a qual o provedor do bot precisa fornecer opções de resposta
BOT_MESSAGE	Bot-Provider → JivoChat API	Resposta do bot à mensagem de um cliente
INVITE_AGENT	Bot-Provider → JivoChat API	Transferência de conversa para o operador, se o bot não tiver opções de resposta
AGENT_JOINED	JivoChat API → Bot-Provider	Um operador conectou-se à conversa por iniciativa do provedor do bot ou de um cliente
AGENT_UNAVAILABLE	JivoChat API → Bot-Provider	Evento informando que no momento não há operadores disponíveis no aplicativo para receber um chat

CLIENT_MESSAGE

Caso: o operador do bot está conectado ao canal de comunicação -> o cliente escreve uma mensagem -> o JivoChat envia a mensagem para o provedor do bot -> a mensagem é processada e a resposta é retornada dependendo do cenário.

Parâmetros do Evento

Nome	Tipo	Descrição
id	String	Identificador exclusivo de evento, usado para registro e depuração
client_id	String	Identificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_id	String	Identificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
message	Message	Mensagem do cliente

Exemplo

{
  event: "CLIENT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123",
  message: {
    type: "TEXT",
    text: "Olá! Quanto é o valor da entrega?",
    timestamp: 1583910736
  }
}

BOT_MESSAGE

Caso: o cliente escreve uma mensagem -> o JivoChat faz o proxy da mensagem para o provedor do bot -> a mensagem é processada -> o bot responde com a mensagem preparada -> a mensagem é enviada ao cliente.

Parâmetros do Evento

Nome	Tipo	Descrição
id	String	Identificador exclusivo de evento, usado para registro e depuração
chat_id	String	Identificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
message	Message	Mensagem do bot

Exemplo

{
  event: "BOT_MESSAGE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  message: {
    type: "BUTTONS",
      title: "Você gostaria de receber a entrega na região de São Paulo?",
      text: "Você gostaria de receber a entrega na região de São Paulo? Sim / Não"
      timestamp: 1583910736,
      buttons: [
        {
          text: "Sim",
          id: 1,
        }, {
          text: "Não",
          id: 2
        }
      ]
  }
}

INVITE_AGENT

Caso: o cliente escreve uma mensagem -> o JivoChat faz proxy da mensagem para o provedor do bot -> a mensagem é processada -> o bot não tem uma resposta preparada -> o diálogo é transferido para o operador.

Parâmetros do Evento

Nome	Tipo	Descrição
id	String	Identificador exclusivo de evento, usado para registro e depuração
client_id	String	Identificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_id	String	Identificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente

Exemplo

{
  event: "INVITE_AGENT",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_JOINED

Parâmetros do Evento

Nome	Tipo	Descrição
id	String	Identificador exclusivo de evento, usado para registro e depuração
client_id	String	Identificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_id	String	Identificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente

Exemplo

{
  event: "AGENT_JOINED",
  id: "123e4567-e89b-12d3-a456-426655440000",
  client_id: "1234",
  chat_id: "213123"
}

AGENT_UNAVAILABLE

Caso: o provedor do bot transfere o chat para o operador, mas não há operadores disponíveis no aplicativo, então de acordo com o script do bot, ele envia uma mensagem pedindo ao usuário que deixe seus dados de contato.

Parâmetros do Evento

Nome	Tipo	Descrição
id	String	Identificador exclusivo de evento, usado para registro e depuração
chat_id	String	Identificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
client_id	String	Identificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente

Exemplo

{
  event: "AGENT_UNAVAILABLE",
  id: "123e4567-e89b-12d3-a456-426655440000",
  chat_id: "213123",
  client_id: "213123"
}

Tipos de mensagem

Tipo de mensagem	Descrição
TEXT	Mensagem de texto simples
MARKDOWN	Mensagem de texto formatada em Markdown
BUTTONS	Botões de opções de resposta

TEXTO

Parâmetros de mensagem

Nome	Tipo	Descrição
text	String	Mensagem de texto
button_id	String (opcional)	ID do botão clicado pelo usuário
timestamp	String	Data e hora da criação da mensagem, unix

Exemplo

{
  type: "TEXT",
  text: "Olá! Qual é sua rotina nos finais de semana?",
  button_id: "123",
  timestamp: 1583910736
}

MARKDOWN

Parâmetros de mensagem

Nome	Tipo	Descrição
content	String	Mensagem no formato Markdown. Na primeira versão: link, negrito, itálico
text	String	Feedback de texto para canais de comunicação que não suportam esse tipo de mensagem, caso contrário a mensagem não será enviada ao cliente
button_id	String optional	ID do botão clicado pelo usuário
timestamp	String	Data e hora da criação da mensagem, unix

Exemplo

{
  type: "MARKDOWN",
  content: "Para desativar **notificações PUSH**, siga as etapas descritas em nossas [instruções](https://site.com/page_url)",
  text: "Para desativar **notificações PUSH**, siga as etapas descritas em nossas instruções https://site.com/page_url",
  timestamp: 1583910736
}

BUTTONS

Parâmetros de mensagem

Nome	Tipo	Descrição
buttons	Array	Conjunto de botões com respostas preparadas. Máximo de 3 botões
title	String	Título de texto para os botões
text	String	Feedback de texto para canais de comunicação que não suportam esse tipo de mensagem, caso contrário a mensagem não será enviada ao cliente
button.text	String	Texto da resposta preparada
button.id	String	ID da resposta preparada
timestamp	String	Data e hora da criação da mensagem, unix

Exemplo

{
  type: "BUTTONS",
  title: "Poderia informar o serviço de entrega desejado?"
  text: "Poderia informar o serviço de entrega desejado? PEC e Sedex estão disponíveis",
  buttons: [
    {
      text: "PEC",
      id: "1"
    },
    {
      text: "Sedex",
      id:"2"
    }
  ],
  timestamp: 1583910736
}

JivoChat Profissional

4 vezes mais chats a partir de
€ 12 por mês