API do chat

Acesse outro artigo

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 Jivo de maneira similar a outros canais.

O mecanismo de webhooks é utilizado para esta integração. O Jivo 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 Jivo 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 Jivo, ou um de nossos apps para Desktop, e clique em Configurações -> Adicionar canais -> API do Chat.

Chat_api_pt_1

Clique em Conectar API do chat.

Chat_api_pt_2

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.

Chat_api_pt_3

Agora você já possuirá sua URL única do Jivo.

Chat_api_pt_4

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:

Pic1

Fluxo principal da integração:

Pic2

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

Ainda tem dúvidas? Nossa equipe de suporte está disponível 24/7 no chat do nosso site e ficará feliz em ajudar você.