API do chat
O canal Webhook permite que você organize o processamento de requisições de clientes a partir de qualquer fonte: aplicativos móveis, desktop ou um widget totalmente customizado em um site. Operadores recebem chamados no aplicativo JivoChat de maneira similar a outros canais.
O mecanismo de webhooks é utilizado para esta integração. O JivoChat fornece um enpoint para receber status de canais e para transmitir mensagens de clientes, e em um sistema integrado, deve existir um endpoint para transmitir a resposta do operador para o cliente.
O endpoint do JivoChat contém uma string aleatória para proteção contra ataques de força bruta, assim como o identificador do canal: JIVO_PUBLIC_ID.
Para gerar seu endpoint único, acesse o aplicativo web do JivoChat, ou um de nossos apps para Desktop, e clique em Configurações -> Adicionar canais -> API do Chat.
Clique em Conectar API do chat.
Insira um nome identificador para o canal, a URL do seu servidor, ative ou não a opção de códificação em blocos ("chunked encoding"), selecione quais operadores da conta receberão chats do canal e clique em Adicionar canal quando estiver pronto.
Agora você já possuirá sua URL única do JivoChat.
Pronto! Agora tudo que você precisa fazer é conferir abaixo o restante do nosso tutorial para compreender como trabalhar com o endpoint gerado.
Princípio geral de trabalho:
Fluxo principal da integração:
Título: JivoSite-Webhooks Channel
API do Cliente->JivoSite: Status do Canal HTTP GET
JivoSite-> API do Cliente: Online (1)
API do Cliente ->Usuário: Mostrar janela customizada do chat
Usuário -> API do Cliente: Enviar Mensagem do Usuário
API do Cliente ->JivoSite: Mensagem do Usuário HTTP POST
JivoSite->Operador: Mensagem do Usuário
Operador->JivoSite: Mensagem do Operador
JivoSite-> API do Cliente: Mensagem do Operador HTTP POST
API do Cliente ->Usuário: Mostrar Mensagem do Operador
Descrição do protocolo
API do cliente->JivoSite: Status do Chat
GET https://wh.jivosite.com/<string aleatória>/JIVO_PUBLIC_ID/status
A resposta padrão é 200 OK, com o corpo sendo um número inteiro:
0 – chat não disponível. Os operadores estão offline ou o chat foi removido do site
1 - chat disponível. Há operadores online
Se não houver um canal no JivoSite com o JIVO_PUBLIC_ID, o servidor retornará um HTTP com o status 404.
Se a resposta for irregular, recomendamos notificar nossa equipe de suporte imediatamente.
API do Cliente->JivoSite: Mensagem do Usuário
POST https://wh.jivosite.com/<string aleatória >/JIVO_PUBLIC_ID
{
"sender" :
{
"id" : "12345",
"name" : "John Doe",
"photo" : "https://examplo.com.br/foto.jpg",
"url" : "https://site.com.br/exemplo/pagina.html",
"phone" : "12345678901",
"email" : "john@doe.сom",
"invite" : "Olá! Como posso ajudar?"
},
"message" :
{
"type" : "text",
"id" : "customer_message_id",
"text" : "Mensagem de texto do usuário"
}
}
sender.id - (é obrigatório uma string ou um número inteiro) identificador do consumidor na API do Cliente. Se este campo estiver vazio/ausente, a mensagem não será transmitida.
sender.name, phone, email – campos opcionais (string). Se o JivoChat recebê-los, irá mostrar as informações recebidas para o operador. Caso contrário, as informações do cliente no chat aparecerão como Anônimas. Esses valores podem ser alterados durante uma conversa.
sender.photo - link opcional para a imagem de perfil de um cliente. O link deve começar com "http: //" ou "https: //". O tamanho recomendado para a imagem é de 128 * 128 px png | jpg | gif. O aplicativo tentará exibir essas imagens, mas a exatidão da exibição não é garantida.
sender.invite - texto opcional de convite. Funciona similarmente à função "Convite em nome de um operador" (ação dos convites proativos) no widget. A lógica de exibição do convite é implementada no chat pelo lado da API do Cliente., enquanto o texto do convite pode ser enviado ao campo sender.invite para que os operadores possam visualizá-lo e compreender o contexto no qual o cliente os contatou.
message.id - identificador de mensagem na API do Cliente.Não é visível em nenhum lugar exceto nos logs. Será usado em versões futuras para o funcionamento da notificação de entrega / leitura de mensagens.
message.type - (obrigatório) - "text" (texto) constante. Não temos suporte para outros tipos de mensagens ainda, mas serão adicionados no futuro.
message.text - (obrigatório para type == text) – string de mensagem do cliente com até 1000 caracteres. Se houver mais de 1000 caracteres, iremos cortar a mensagem.
A resposta padrão é 200 OK. Se o código da resposta for diferente de 200, recomendamos notificar nossa equipe imediatamente.
Se não houver um canal no JivoSite com o JIVO_PUBLIC_ID, o servidor retornará um HTTP com status 404.
JivoSite->API do Cliente: Mensagem do Operador
POST <API do Cliente HTTPS-endpoint URL>/JIVO_PUBLIC_ID
{
"sender" : {
"name" : "Nome do Operador",
"photo" : "URL da Foto do Operador"
},
"recipient" : {
"id" : "12345"
},
"message" : {
"type" : "text",
"id" : "jivo_message_id",
"text" : "Texto da Mensagem do Operador"
}
}
sender.name – nome do operador que escreveu a mensagem.
sender.photo – link da imagem – avatar do operador.
**recipient.id8* – identificador do cliente na API do Cliente. Iremos recebê-lo da mensagem de entrada e o enviaremos de volta sem alterações.
message.id – identificador da mensagem no JivoSite. Será usado futuramente para o funcionamento da notificação de entrega / leitura de mensagens.
A resposta padrão é 200 OK.
Corpo de resposta em formato JSON:
{ "result" : "ok" }
ou
{
"error" :
{
"code" : <código do erro>,
"message" : "< mensagem de erro legível>"
}
}
Uma mensagem de erro será mostrada ao operador na conversa dentro do JivoSite. Pode ou não ser mostrada dependendo do código do erro.
Notificação de registro de mensagem
Para a notificação de um conjunto de mensagens, é utilizada uma mensagem com a indicação de tipo:
type (tipo): "typein" – o início de um conjunto de mensagens.
type (tipo): "typeout" – o fim de um conjunto de mensagens.
Outros campos na mensagem com este tipo são ignorados.
Funciona de forma idêntica em ambas as direções, do JivoSite para a API do Cliente e da API do Cliente para o JivoSite.
Mensagens multimídia
Mensagens multimídia são transmitidas da mesma forma que mensagens de texto, porém possuem um tipo ("type") especial e campos adicionais. A composição dos campos obrigatórios e o valor do campo tipo ("type") para cada tipo de mídia suportada estão listados abaixo.
| Valor do campo tipo | Campos adicionais obrigatórios | Tipo |
|---|---|---|
| video | file, file_name, file_size | video |
| audio | file, file_name, file_size | audio |
| voice | file, file_name, file_size | voice message |
| photo | file, file_name, file_size | image |
| sticker | file, file_name, file_size | sticker |
| document | file, file_name, file_size | file (link to file) |
| location | latitude, longitude | geo-location |
Campos de mensagem multimídia opcionais estão listados abaixo:
| Campo de mensagem multimídia | Descrição |
|---|---|
| string file | url http(s) de arquivo |
| string thumb | url http(s) para imagem em miniatura(w320px) |
| string emoji | possível substituição de mídia por um caractere unicode |
| number file_size | tamanho do arquivo em bytes, inteiro positivo |
| string file_name | nome do arquivo definido pelo usuário |
| number duration | duração do fluxo em segundos, inteiro positivo |
| number width | largura em pixels, inteiro positivo |
| number height | altura em pixels, inteiro positivo |
| string text | mensagem de texto ou comentário |
| string performer | autor (compositor, executante, etc.) |
| string title | título |
| number latitude | latitude real |
| number longitude | longitude real |
Re-enviar mensagens
Eventos, no formato de solicitações http(s), são enviados ao servidor da API do Cliente 3 vezes à cada 3 segundos até que uma resposta positiva válida seja recebida. Isso gera 6 segundos para atualizar o software no servidor, o que é suficiente na maioria dos casos. Se o servidor estiver indisponível, um evento de erro será retornado após 9 segundos. Estas configurações padrões permitem que você receba rapidamente uma resposta do remetente. No caso de um timeout ou erro na API do Cliente, o operador verá uma mensagem de erro no chat.
Chunked-request
O JivoSite pode enviar pedidos à API do Cliente com o campo Content-Length e no Chunked encoding.
