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 respostaDescrição
200 OKSucesso, resposta padrão
400 Bad RequestFormato de solicitação inválido. Você deve verificar os campos de solicitação para conformidade com o formato da API
401 UnauthorizedErro de autorização
403 ForbiddenAcesso negado
404 Not FoundEndpoint formado incorretamente
405 Method Not AllowedEste método ou evento não é compatível
429 Too Many RequestSolicitações excedidas por unidade de tempo
500 Internal Server ErrorErro de processamento de solicitação
502 Bad GatewayServidor está sobrecarregado
503 Service UnavailableServidor não disponível
504 Gateway TimeoutFalha 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ódigoDescrição
invalid_clientErro de autenticação do token do cliente. Retornado com o código HTTP 401 não autorizado
unauthorized_clientA autorização falhou pelo cabeçalho Autorização
invalid_requestA 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 mensagemCaminhoDescrição
CLIENT_MESSAGEJivoChat API → Bot-ProviderEvento de uma nova mensagem do cliente para a qual o provedor do bot precisa fornecer opções de resposta
BOT_MESSAGEBot-Provider → JivoChat APIResposta do bot à mensagem de um cliente
INVITE_AGENTBot-Provider → JivoChat APITransferência de conversa para o operador, se o bot não tiver opções de resposta
AGENT_JOINEDJivoChat API → Bot-ProviderUm operador conectou-se à conversa por iniciativa do provedor do bot ou de um cliente
AGENT_UNAVAILABLEJivoChat API → Bot-ProviderEvento 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

NomeTipoDescrição
idStringIdentificador exclusivo de evento, usado para registro e depuração
client_idStringIdentificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_idStringIdentificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
messageMessageMensagem 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

NomeTipoDescrição
idStringIdentificador exclusivo de evento, usado para registro e depuração
chat_idStringIdentificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
messageMessageMensagem 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

NomeTipoDescrição
idStringIdentificador exclusivo de evento, usado para registro e depuração
client_idStringIdentificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_idStringIdentificador 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 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 -> o operador entra no chat.

Parâmetros do Evento

NomeTipoDescrição
idStringIdentificador exclusivo de evento, usado para registro e depuração
client_idStringIdentificador do usuário que envia uma mensagem a um dos canais do cliente do JivoChat. Exclusivo na conta do cliente
chat_idStringIdentificador 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

NomeTipoDescrição
idStringIdentificador exclusivo de evento, usado para registro e depuração
chat_idStringIdentificador da conversa, na qual existe um diálogo entre usuário e operador. Exclusivo na conta do cliente
client_idStringIdentificador 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 mensagemDescrição
TEXTMensagem de texto simples
MARKDOWNMensagem de texto formatada em Markdown
BUTTONSBotões de opções de resposta

TEXTO

Parâmetros de mensagem

NomeTipoDescrição
textStringMensagem de texto
button_idString (opcional)ID do botão clicado pelo usuário
timestampStringData 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

NomeTipoDescrição
contentStringMensagem no formato Markdown. Na primeira versão: link, negrito, itálico
textStringFeedback 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_idString optionalID do botão clicado pelo usuário
timestampStringData 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

NomeTipoDescrição
buttonsArrayConjunto de botões com respostas preparadas. Máximo de 3 botões
titleStringTítulo de texto para os botões
textStringFeedback 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.textStringTexto da resposta preparada
button.idStringID da resposta preparada
timestampStringData 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
}
Está com dúvidas?
Pergunte-nos pelo chat, estamos sempre disponíveis para ajudar!