API para bots

Leia outro artigo

Nossa API para bots permite que você conecte plataformas de bots a quaisquer conversas no Jivo: 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 Jivo, por favor envie-nos um email para gerar seu ID de provedor.

Troca de dados

O iniciador da troca é o Jivo. 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 Jivo são enviados ao endpoint do provedor e, em resposta, o provedor envia eventos ao endpoint do Jivo.

Todos os eventos do Jivo 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 Jivo é 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 Jivo 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 Jivo. Todas as solicitações do Jivo 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 Jivo e tem uma vida útil limitada. Para fazer isso, o Jivo 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 Jivo 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 → Jivo API Resposta do bot à mensagem de um cliente
INVITE_AGENT Bot-Provider → Jivo API Transferência de conversa para o operador, se o bot não tiver opções de resposta
AGENT_JOINED Jivo API → Bot-Provider Um operador conectou-se à conversa por iniciativa do provedor do bot ou de um cliente
AGENT_UNAVAILABLE Jivo 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 Jivo 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 Jivo. 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 Jivo 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 Jivo 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 Jivo. 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

Caso: o cliente escreve uma mensagem -> o Jivo 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 -> o operador entra no chat.

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 Jivo. 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 Jivo. 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<button> 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
}

Ainda tem dúvidas? A nossa equipa de atendimento está disponível 24/7 no chat do nosso site e ficará feliz em ajudá-lo.