Zenvia Docs

Agent connector API

O Agent Connector API permite que plataformas externas realizem atendimentos de Live Chat no Zenvia NLU.

Overview

Esta API consiste no envio e recebimento de eventos, através de chamadas http.

  • O Zenvia NLU enviará eventos para o Live Chat através de chamadas POST ao webhook configurado na integração

  • O Live Chat enviará eventos para o Zenvia NLU por meio de chamadas POST ao endpoint https://agent.altubots.com/altu-connector/{slug}/{livechatId}

  • 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:

Iniciar LiveChat

Autenticação

A autenticação é feita via JWT:‌

  • Para cada request deve ser gerado um token novo onde a chave é usada para encriptar o token de acesso;

  • O Token de acesso (access_token) e a Chave de acesso (access_key) são obtidos na integração cadastrada no Zenvia NLU.

{
  "alg": "RS256",
  "typ": "JWT"
}
.
{
  "access_token": "pDD8w6VeTjnk03MxGqwSsEneuaykfkVvfpfUnus2",
  "iat": 1653066200,
  "exp": 1653066260
}

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

Payload:

{
    "action": "OPEN_CONVERSATION",
    "conversationId": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
    "requestId": "0d0c341a-dcca-11ea-87d0-0242ac130003",
    "identifier": "6422fa06-dce1-11ea-87d0-0242ac130003",
    "skillId": "teste_liveChat",
    "agent": "dr9383jjcdl0839",
    "parameters": {
        "contact": {
            "id": "contact.id",
            "name": "contact.name",
            "email": "contact.email",
            "phone": "contact.phone",
            "cpf": "contact.cpf",
            "channel: "widget"
            "extra": {},
            "history": [
                {
                    "id": null,
                    "time": "2021-02-18T20:12:20.191Z",
                    "sender": "user",
                    "message": "Oi",
                    "assistant_id": 1
                },
                {
                    "id": null,
                    "time": "2021-02-18T20:12:21.557Z",
                    "sender": "bot",
                    "message": [
                        {
                            "default": {
                                "text": "Olá contact.name, seja bem-vindo! Em que posso te ajudar?",
                                "type": "text"
                            }
                        }
                    ],
                    "assistant_id": 1
                }
            ]
        },
        "extraInfo": {}
    },
    "timestamp": 1597256758383
}

  • 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

    • extraInfo: informações extras, citado em Iniciar Live Chat

  • timestamp: UNIX timestamp do momento de envio do evento

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.

Estrutura

{
  "action": "SEND_STATUS",
  "conversationID": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
  "parameters": {
    "status": "read"
  },
  "timestamp": 1597257441698
}

Atributos:

  • action: SEND_STATUS

  • 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:

Status Code: 200

{
	"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
	"message": "OK"
}

  • requestId: ID único que o Zenvia NLU gera que identifica o evento recebido

  • message: Mensagem que indica o sucesso/erro do recebimento

Para saber mais como usa-lo em um assistente:

Iniciar LiveChat

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 brokers LivePerson ou Zenvia

  • 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

  • API de Outbound habilitada e configurada

Configuração da API de Outbound

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:

PreviousAPIsNextOutbound

Last updated