API para bots

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.

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

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

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

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

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

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

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

Exemplo

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

Tipos de mensagem

TEXTO

Parâmetros de mensagem

Exemplo

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

MARKDOWN

Parâmetros de mensagem

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

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
}