A autenticação do envio e recebimento de eventos será feita via JWT. Esse processo será detalhado na conclusão do desenvolvimento
Todo evento enviado e recebido deve ter no corpo um JSON com o seguinte formato:
{
"action":"Tipo do evento",
"conversationID":"Id único que identifica a conversa de live chat",
"identifier":"Id único que identifica a usuário no ALTU",
"parameters":{
...
},
"timestamp":"Horário do envio do evento em formato UNIX timestamp"
}
Envie também dados do usuário para o agente, saiba como configurar em:
Assine o JWT com HS256 usando a chave de acesso (access_key);
Para o campo iat, especifique a hora Unix atual, e para o campo exp, especifique a hora exatamente 60 segundos depois, que é quando o JWT irá expirar;
É fundamental que o tempo de expiração seja de no máximo 60 segundos (exp).
Eventos
Todo evento deve possuir um atributo action que identifica o propósito do que está sendo enviado/solicitado.
Actions que o Zenvia NLU envia para a plataforma de Livechat:
OPEN_CONVERSATION : solicitação de atendimento
contact.extra: objeto que engloba o atributo contact_infoque é usado para enviar informações extras do atendimento durante o transbordo
extraInfo: informações extras do atendimento que serão enviadas durante o transbordo e serão disponibilizados no Widget (ficha) do atendimento para o Agente
SEND_MESSAGE : envio de mensagem do usuário para o agente
UPLOAD_FILE : evento usado para salvar um arquivo
SEND_FILE: envio de arquivo do usuário para o agente através do ID recebido no evento UPLOAD_FILE
GET_FILE : evento enviado para buscar os dados de um arquivo através do ID recebido no evento UPLOAD_FILE
CLOSE_CONVERSATION: encerramento de atendimento por parte do usuário.
ACCEPT_CONVERSATION: evento que sinaliza a aprovação do ALTU para a reabertura de atendimento
REJECT_CONVERSATION : evento que sinaliza algum erro no pedido de reabertura de atendimento
Actions que a plataforma de Livechat envia para o Zenvia NLU:
ACCEPT_CONVERSATION : deve ser enviado quando um agente aceita a solicitação de um atendimento
REJECT_CONVERSATION: deve ser enviado quando não há agentes disponíveis para realizar o atendimento
SEND_MESSAGE : envio de mensagem do agente para o usuário
SEND_FILE: envio de arquivo do agente para o usuário
GET_FILE : evento enviado para buscar os dados de um arquivo através do ID recebido no evento SEND_FILE
CLOSE_CONVERSATION : encerramento de atendimento por parte do agente
CLOSE_CONVERSATION : quando se trata de reabertura de atendimento, esse evento será disparado quando o cliente responder o outbound fora do tempo de tolerância, ou seja, maior que o expirationTime
REOPEN_CONVERSATION: solicitação de reabertura de um atendimento por parte do agente
Eventos enviados e recebidos em um exemplo de atendimento de Livechat:
Evento enviado do Zenvia NLU para a plataforma de Livechat para solicitar a abertura de um novo atendimento.
action: OPEN_CONVERSATION (solicitação de atendimento)
conversationId: ID único gerado pelo Zenvia NLU que representa a sessão de live chat.
requestId: ID único que representa o evento.
identifier: Id único que identifica o usuário no Zenvia NLU
skillId (opcional): id da habilidade do agente que atenderá o usuário. Id pode ser número ou string.
agent (opcional): ID do agente que atenderá o usuário. Id pode ser número ou string.
parameters:
contact:
id: ID do atendimento no Zenvia NLU
name (opcional, default: "Sem Nome"): nome do usuário
email (opcional): email do usuário
phone (opcional): telefone do usuário
cpf (opcional): cpf do usuário
channel: canal do atendimento (whatsapp, widget, messenger, etc)
history(opcional): Últimas 100 mensagens do histórico de mensagens trocadas entre o usuário e o(s) assistente(s) a partir do evento new_dialog do atendimento atual
Valores que podem ser adicionados: default, debugger, whatsapp, apple, widget, api, facebook, workplace e rcs
action: ACCEPT_CONVERSATION (aceite do atendimento)
conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION
parameters:
agent:
id: ID do agente que atendeu a chamada
name (opcional): nome do agente que atendeu a chamada
timestamp: UNIX timestamp do momento de envio do evento
Para reabertura de atendimento:
Evento enviado pelo ALTU para a plataforma de Livechat, quando a reabertura da conversa passou por todos os requisitos e está aguardando a interação do usuário
conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION
parameters:
contact:
id: ID do atendimento no ALTU
name (opcional, default: "Sem Nome"): nome do usuário
email (opocional): email do usuário
phone (opcional): telefone do usuário
cpf (opcional): cpf do usuário
channel: canal do atendimento (whatsapp, widget, messenger, etc)
messages: array de mensagens que o usuário está enviando para o agente
type (opcional): Tipos disponíveis:
“information”: envio de mensagens classificadas como informativas. Um exemplo, é o envio de mensagens enquanto o agente não atende o usuário no Livechat.
No widget, a mensagem é exibida em uma estrutura diferente das demais mensagens da troca, nos outros canais é enviada como texto.
timestamp: UNIX timestamp do momento de envio do evento
Live chat para ALTU (Agente para usuário)
Payload:
{
"action":"SEND_MESSAGE",
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
"parameters":{
"agent":{
"id":12,
"name":"Mary Kate"
},
"messages":[
"Olá!",
"Aguarde um momento, por favor..."
]
},
"timestamp":1597257441698
}
action: SEND_MESSAGE
conversationId: ID da sessão enviado pelo Altu no evento de OPEN_CONVERSATION
parameters:
agent:
id: ID do agente que atendeu a chamada
name (opcional): nome do agente que atendeu a chamada
messages: array de mensagens que o agente está enviando para o usuário
timestamp: UNIX timestamp do momento de envio do evento
Compartilhar Localização
A localização será enviada no evento SEND_MESSAGE e estará dentro do atributo "parameters":
conversationId: ID da sessão enviado pelo Altu no evento de OPEN_CONVERSATION
reason: campo para enviar motivo da conversa ter sido encerrada pelo agente
timestamp: UNIX timestamp do momento de envio do evento
Para reabertura de atendimento:
A estrutura é a mesma do ALTU para Livechat, e será enviado quando o usuário responder o outbound fora do tempo de tolerância, ou seja, maior que o expirationTime
Evento enviado pelo agente para reabrir um atendimento com um determinado usuário.
Live chat para ALTU (agente para usuário)
Exemplo de payload a ser enviado do Live Chat para o ALTU
{
"action": "REOPEN_CONVERSATION",
"conversationId": "700bf535-9f1c-491d-8ab3-09ee82d0825a",
"parameters": {
"expirationTime": "30",
"message": "Mensagem a ser enviada para o usuário para a reabertura da conversa"
},
"timestamp": 1597257441698,
}
Atributos:
action: fixo com o valor REOPEN_CONVERSATION
conversationId: ID da conversa tida anteriormente que deseja ser reaberta
parameters:
expirationTime: Tempo em minutos em que o pedido de reabertura será válido
message: mensagem que será enviada ao usuário no pedido de reabertura.
timestamp: momento da requisição.
ALTU para Live chat (usuário para agente)
Exemplo de payload que o ALTU enviará para o Live Chat ao conseguir enviar o HSM ao usuário.
status: keyword sistêmica indicando o motivo da rejeição. Será um dos seguintes valores:
Atendimento não existente (contact_not_found)
Canal inválido (invalid_channel)
Integração mal configurada (bad_integration_config)
Qualquer erro retornado pelo broker ao tentar enviar o HSM (message_not_sent).
Atendimento em andamento (contact_in_conversation)
reason: descrição do motivo do pedido de reabertura ter sido rejeitado.
Envio de Status LiveChat
Durante um LiveChat, uma mensagem enviada pelo usuário será instantaneamente marcada como “Enviada”, após o agente visualizá-la. O payload abaixo deverá ser disparado e permitirá atualizar no widget o status para “Lida”.
Funcionalidade disponível apenas para o canal Widget.
conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION
parameters:
status: até o momento somente o status “read”, indicando leitura da mensagem pelo agente, será processado pelo Zenvia NLU.
timestamp: UNIX timestamp do momento de envio do evento
Importante
O recebimento de um evento deve ser sempre respondido com o http code 200 OK, por ambos os lados. No body do response o Zenvia NLU irá indicar se o evento recebido foi processado corretamente ou não:
requestId: ID único que o ALTU gera que identifica o evento recebido
message: Mensagem que indica o sucesso/erro do recebimento
Para saber mais como usa-lo em um assistente:
Reabertura de atendimento
Essa funcionalidade possibilita que um agente em atendimento de Live chat possa reabrir um atendimento para tratar algum assunto pendente com o usuário.
A reabertura acontece por meio do envio de uma mensagem outbound, e segue alguns padrões:
Requisitos
Integração do WhatsApp pelos brokersLivePerson ouZenvia
Um template de mensagem (HSM) específico para esse tipo de ocasião:
Esse template HSM deve ter apenas UMA variável
Quando for possível nomear a variável, como é o caso da Zenvia, ela deve ter o nome de message
Os campos para habilitar a possibilidade de reabertura de conversa estão dentro das configurações da integração com o canal, após habilitar a API de Outbound
LivePerson V1
Para a V1 da LivePerson, basta inserir o nome do template HSM criado (conforme os requisitos mencionados acima)
LivePerson V2
Já na V2, é necessário inserir o ID do template HSM criado (conforme os requisitos já mencionados), bem como a skill (habilidade) configurada no template.
Zenvia
Quando a integração é feita pelo broker Zenvia, é necessário informar o ID do template HSM (criado conforme as regras mencionadas acima)
Eventos enviados e recebidos em um exemplo de reabertura de Live Chat: