API do chat

Incluso gratuitamente nos planos
VIP

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 tipoCampos adicionais obrigatóriosTipo
videofile, file_name, file_sizevideo
audiofile, file_name, file_sizeaudio
voicefile, file_name, file_sizevoice message
photofile, file_name, file_sizeimage
stickerfile, file_name, file_sizesticker
documentfile, file_name, file_sizefile (link to file)
locationlatitude, longitudegeo-location

Campos de mensagem multimídia opcionais estão listados abaixo:

Campo de mensagem multimídiaDescrição
string fileurl http(s) de arquivo
string thumburl http(s) para imagem em miniatura(w320px)
string emojipossível substituição de mídia por um caractere unicode
number file_sizetamanho do arquivo em bytes, inteiro positivo
string file_namenome do arquivo definido pelo usuário
number durationduração do fluxo em segundos, inteiro positivo
number widthlargura em pixels, inteiro positivo
number heightaltura em pixels, inteiro positivo
string textmensagem de texto ou comentário
string performerautor (compositor, executante, etc.)
string titletítulo
number latitudelatitude real
number longitudelongitude 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.

Artigos relacionados
Está com dúvidas?
Pergunte-nos pelo chat, estamos sempre disponíveis para ajudar!