LogoLogo
Zenvia Docs
  • Zenvia NLU
  • Boas Práticas
    • Eventos
      • Dicas para criar eventos
      • Eventos Personalizados
        • menu_principal
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • Autosservico
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • sucess_no_friccion
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • horario_atendimento
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • transbordo
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • pesquisa_satisfacao
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • conseguiu_ajudar
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • nivel_confianca
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de eventos
        • chamada_api
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • falha_api
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • primeiro_acesso
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • encerramento
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • estouro_tentativas_else
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • intents
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
        • rechamada
          • Dashboard
          • Fluxograma
          • Builder
          • Lista de Eventos
    • Gestão de NLU
      • Dicas de gestão de NLU
    • Personalizar widget
  • Monitor
    • Dashboard
      • Métricas e indicadores
      • Gráficos
    • Atendimentos
    • Eventos
    • Volumetria
    • Issues
    • Monitoramento de APIs
    • Métricas de avaliação
  • Build
    • Assistentes
      • Edição do Assistente
      • Builder
        • Configurações do nó
        • Componentes
          • Output
            • Texto
            • Texto randômico
            • Texto sequencial
            • Base de conhecimento
            • LivePerson - Conteúdo Estruturado
            • Arquivo
          • Input
            • Pergunta aberta
            • Autocomplete
            • Data
            • Feedback NPS
            • Feedback Custom
            • Lista inline
            • Lista modal
            • Quick Replies
            • Upload de arquivo
            • Upload de arquivo LP
            • Carrossel de Opções
            • Desambiguação
          • Fluxo de Inatividade
          • Variáveis
          • Ações
            • HTTP Request
            • Satisfaction
            • Validar celular
            • Validar CEP
            • Validar CPF
            • Validar CPF/CNPJ
            • Validar CNPJ
            • Validar nome completo
            • Validar e-mail
            • Procurar atendimento
            • Transferência entre skills Liveperson
            • Setar contexto LivePerson
            • Encerrar Atendimento LivePerson
            • Encerrar chat
            • Socket Event
            • Facebook Profile
            • Facebook Transbordo
            • Workplace Profile
            • Iniciar LiveChat
            • Functions
            • Setar NLU
            • Transferência entre assistentes
            • Contact Return
            • Intent Feedback
          • Eventos
    • Functions
    • Atributos
  • CONNECT
    • APIs
      • Agent connector API
      • Outbound
        • Outbound WhatsApp
        • Outbound Zenvia
        • Outbound Wavy
        • Outbound LivePerson
        • Outbound Infobip
        • Outbound RCS
      • Eventos
      • Atendimentos
      • LGPD
    • Canais
      • Capabilities
      • Instagram
      • Google Business Messages
      • Bot API
      • Facebook
        • Integração Messenger via Zenvia NLU
        • Integração Messenger via Liveperson
      • Google RCS
      • Microsoft Teams
      • Whatsapp
        • Zenvia
        • Blip
        • Wavy
        • Infobip
        • Liveperson
      • Widget
      • Workplace
    • Telegram
    • Contingência
    • LiveChat
      • Transbordo ALTU Connector API
        • Transbordo Tech4Humans
      • Transbordo LivePerson
      • Transbordo Zendesk Ticket
      • Transbordo Zendesk Chat
      • Transbordo Salesforce
  • TRAIN
    • Primeiros passos
    • Visão Geral
    • Configuração do NLU
    • Avaliação de Mensagens
    • Análise e ajustes
  • Mais
    • Release
      • Controle de Versão
      • 27/10/2021
      • 06/10/2021
      • 22/09/2021
      • 09/09/2021
      • 11/08/2021
      • 28/07/2021
      • 14/07/2021
      • 30/06/2021
      • 16/06/2021
      • 01/06/2021
      • 18/05/2021
      • 04/05/2021
      • 20/04/2021
      • 06/04/2021
      • 23/03/2021
      • 09/03/2021
      • 23/02/2021
      • 09/02/2021
      • 26/01/2021
      • 12/01/2021
      • 22/12/2020
      • 08/12/2020
      • 24/11/2020
      • 10/11/2020
      • 27/10/2020
      • 13/10/2020
      • 29/09/2020
      • 15/09/2020
      • 01/09/2020
      • 18/08/2020
      • 03/08/2020
      • 21/07/2020
      • 08/07/2020
      • 30/06/2020
      • 04/06/2020
      • 22/05/2020
      • 14/05/2020
      • 29/04/2020
      • 01/04/2020
      • 24/03/2020
      • 16/03/2020
    • Glossário
Powered by GitBook
On this page
  • Overview
  • Autenticação
  • Eventos
  • Actions que o Zenvia NLU envia para a plataforma de Livechat:
  • Actions que a plataforma de Livechat envia para o Zenvia NLU:
  • Envio de Status LiveChat
  • Estrutura
  • Atributos:
  • Importante
  • Reabertura de atendimento
  • Requisitos
  • Configuração da API de Outbound
  • LivePerson V1
  • LivePerson V2
  • Zenvia

Was this helpful?

  1. CONNECT
  2. APIs

Agent connector API

PreviousAPIsNextOutbound

Last updated 2 years ago

Was this helpful?

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

  • A autenticação do envio e recebimento de eventos será feita via . 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:

Autenticação

  • 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

  • timestamp: UNIX timestamp do momento de envio do evento

Evento enviado do ALTU 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",
   "parameters":{
      "contact":{
         "id": "contact.id",
         "name":"contact.name",
         "email":"contact.email",
         "phone":"contact.phone",
         "cpf":"contact.cpf",
         "channel: "widget"
         "extra":{},
      "extraInfo":{
         
      }
   },
   "timestamp":1597256758383
}
  • action: OPEN_CONVERSATION (solicitação de atendimento)

  • conversationId: ID único gerado pelo ALTU que representa a sessão de Livechat.

  • requestId: ID único que representa o evento.

  • identifier: Id único que identifica o usuário no ALTU

  • skillId (opcional): id da habilidade do agente que atenderá o usuário. Id pode ser número ou string.

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

      • extra (opcional): objeto que engloba o contact_info, atributo que envia informações extras do atendimento durante o transbordo.

    • extraInfo: informações extras do atendimento

  • timestamp: UNIX timestamp do momento de envio do evento

Evento enviado do LiveChat para o ALTU para indicar que um agente aceitou uma solicitação de atendimento.

Payload:

{
  "action": "ACCEPT_CONVERSATION",
  "conversationID": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
  "parameters": {
    "agent": {
      "id": 12,
      "name": "Mary Kate"
    }
  },
  "timestamp": 1597257441698
}
  • 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

{
   "action":"ACCEPT_CONVERSATION",
   "conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "requestId":"0d0c341a-87d0-11ea-dcca-0242ac130003",
   "parameters":{
      "status":"accepted",
      "contact":{
         "id":12345,
         "name":"Sem nome",
         "email":"",
         "phone":"11998631234",
         "cpf":""
      }
   },
   "timestamp":1597257441698
}
  • action: ACCEPT_CONVERSATION (aceite do atendimento)

  • conversationId: identificador da sessão atual, referente à conversa reaberta.

  • requestId: identificador único que representa o evento.

  • parameters:

    • status: accepted

    • contact:

      • id: identificador 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)

  • timestamp: UNIX timestamp do momento de envio do evento

Evento enviado do Livechat para o ALTU para indicar que não há agente disponível para atender a chamada (ex: fora do horário de atendimento)

Payload:

{
    action: 'REJECT_CONVERSATION',
    conversationId: '1be5e1d3-d949-44ab-86a7-6d032b0cd17e"',
    reason: 'any_reason',
    timestamp: 1597257441698
}
  • action: REJECT_CONVERSATION

  • conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION

  • reason: campo para enviar motivo da conversa não ter sido aceita pelo agente

  • timestamp: UNIX timestamp do momento de envio do evento

Para reabertura de atendimento:

Evento disparado pelo ALTU para a plataforma de Livechat, quando há algum erro ao tentar reabrir a conversa

Payload:

{
   "action":"REJECT_CONVERSATION",
   "conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "requestId":"0d0c341a-dcca-11ea-87d0-0242ac130003",
   "parameters":{
      "status":"contact_in_conversation",
      "reason":"The contact is already in an conversation"
   },
   "timestamp":1597257441698
}
  • action: REJECT_CONVERSATION

  • conversationId: identificador passado no REOPEN_CONVERSATION.

  • requestId: identificador único que representa o evento.

  • parameters:

    • status: códigos variam de acordo com a causa da rejeição, sendo os status:

      • contact_not_found: não foi possível encontrar o atendimento com o conversationId informado.

      • invalid_channel: o atendimento está em um canal que não oferece suporte à reabertura.

      • invalid_integration: o atendimento está em um canal válido, em uma integração que não oferece suporte à reabertura.

      • integration_not_found: houve um erro ao tentar acessar mais detalhes da integração vinculada ao atendimento.

      • bad_integration_config: foi possível obter detalhes da integração, mas os campos na configuração da reabertura estão vazios.

      • contact_in_conversation: o atendimento já está em uma conversa.

      • message_not_sent: houve um erro ao enviar a mensagem para o broker.

    • reason: explicação do porquê a tentativa de reabertura falhou.

  • timestamp: UNIX timestamp do momento de envio do evento.

Evento do ALTU para o Livechat e vice-versa para enviar uma mensagem do usuário para o agente e vice-versa.

ALTU para Live chat (Usuário para agente)

Payload:

{
   "action":"SEND_MESSAGE",
   "conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
   "identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
   "parameters":{
      "contact":{
         "id":12345,
         "name":"John Doe",
         "email":"john.doe@gmail.com",
         "phone":"11998631234",
         "cpf":"12345678909",
         "channel": "whatsapp"
      },
      "messages":[
         "Gostaria de contestar uma compra realizada em meu cartão"
      ],
      "type":"information"
   },
   "timestamp":1597257441698
}
  • action: SEND_MESSAGE

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

{
   "action":"SEND_MESSAGE",
   "conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
   "identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
   "parameters":{
      "contact":{
         "id":12345,
         "name":"John Doe",
         "email":"john.doe@gmail.com",
         "phone":"11998631234",
         "cpf":"12345678909"
      },
      "location":{
         "latitude":-22.4207974,
         "longitude":-45.469118
      }
   },
   "timestamp":1597257441698
}

O atributo location será composto por latitude e um longitude , e seus valores serão numéricos.

Quando for enviada a localização o atributo "messages" não será enviado.

Evento utilizado para salvar um arquivo que será enviado posteriormente. Após ser salvo, o arquivo ficará disponível por até 24h.

Payload:

{
   "action":"UPLOAD_FILE",
   "conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "file":{
      "contentType":"image/jpeg|image/png|application/pdf",
      "buffer":"<Buffer ..."
   },
   "timestamp":1597257441698
}
  • action: UPLOAD_FILE

  • conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION

  • file:

    • contentType: Tipo do arquivo

    • buffer: Buffer do arquivo

  • timestamp: UNIX timestamp do momento de envio do evento

Response:

Status Code: 200

{
  "fileId": "6671950e-a933-4bec-9070-dc71cf464c1f",
  "requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
  "message": "OK"
}
  • fileId: ID do arquivo que deve ser utilizado no SEND_FILE e GET_FILE.

  • requestId: ID único que representa o evento.

Evento do ALTU para o Livechat e vice-versa para enviar um arquivo do usuário para o agente e vice-versa.

ALTU para Livechat (usuário para agente)

Payload:

{
   "action":"SEND_FILE",
   "conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
   "identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
   "parameters":{
      "contact":{
         "id":12345,
         "name":"John Doe",
         "email":"john.doe@gmail.com",
         "phone":"11998631234",
         "cpf":"12345678909"
         "channel: "widget"
      },
      "file":{
         "id":"6671950e-a933-4bec-9070-dc71cf464c1f",
         "name":"cachorro.jpg",
         "contentType":"image/jpeg",
         "type":"jpg",
         "size":5855,
         "caption":"Um cachorro"
      }
   },
   "timestamp":1597257441698
}
  • action: SEND_FILE

  • conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION

  • requestId: ID único que representa o evento.

  • identifier: Id único que identifica o usuário no ALTU

  • 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

    • file:

      • name: nome do arquivo

      • contentType: o tipo MIME do arquivo

      • type: extensão do arquivo

      • size: tamanho do arquivo (em bytes)

      • caption: descrição do arquivo

  • timestamp: UNIX timestamp do momento de envio do evento

Livechat para ALTU (agente para usuário)

Payload:

{
   "action":"SEND_FILE",
   "conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
   "parameters":{
      "agent":{
         "id":12,
         "name":"Mary Kate"
      },
      "file":{
         "id":"6671950e-a933-4bec-9070-dc71cf464c1f"
      }
   },
   "timestamp":1597257441698
}
  • action: SEND_FILE

  • 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

      • file:

        • id: ID do arquivo que é retornado após a chamada da action UPLOAD_FILE.

  • timestamp: UNIX timestamp do momento de envio do evento

Busca um arquivo através do id informado no evento UPLOAD_FILE. Essa chamada pode ser feita do ALTU para o Livechat e vice-versa.

ALTU para Livechat (usuário para agente)

Payload:

{
  "action": "GET_FILE",
  "fileId": "6671950e-a933-4bec-9070-dc71cf464c1f",
  "requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
  "timestamp": 1597257441698
}
  • action: GET_FILE

  • fileId: ID do arquivo recebido no evento UPLOAD_FILE

  • requestId: ID único que representa o evento.

  • timestamp: UNIX timestamp do momento de envio do evento.

Response:

Status Code: 200

{
  "file": {
    "contentLength": 59662,
    "contentType": "image/png",
    "type": "png",
    "buffer": {
      "type": "Buffer",
      "data": [...]
    }
  },
  "requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
  "message": "OK"
}
  • file

    • contentLength: Tamanho do arquivo.

    • contentType: Tipo do arquivo.

    • type: Extensão do arquivo.

    • buffer: Buffer do arquivo.

  • requestId: ID único que representa o evento.

Livechat para o ALTU (agente para usuário)

Payload:

{
  "action": "GET_FILE",
  "fileId": "6671850e-a933-4bec-9070-dc71cf464c1f",
  "timestamp": 1597445441898
}
  • action: GET_FILE

  • fileId: ID do arquivo recebido no evento

  • timestamp: UNIX timestamp do momento de envio do evento.

Evento enviado para encerrar um atendimento, seja do lado do agente (Livechat) ou usuário (ALTU)

ALTU para Livechat (usuário para agente)

Payload:

{
    action: "CLOSE_CONVERSATION",
    conversationId: "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
    identifier: "6422fa06-dce1-11ea-87d0-0242ac130003",
    requestId: "6422fa06-dce1-11ea-87d0-0242ac130003",
    timestamp: 1597257441698,
}
  • action: CLOSE_CONVERSATION

  • conversationId: ID da sessão enviado pelo ALTU no evento de OPEN_CONVERSATION

  • requestId: ID único que representa o evento.

  • identifier: Id único que identifica o usuário no ALTU

  • timestamp: UNIX timestamp do momento de envio do evento

Livechat para ALTU (agente para usuário)

Payload:

{
    action: 'CLOSE_CONVERSATION',
    conversationId: '1be5e1d3-d949-44ab-86a7-6d032b0cd17e"',
    reason: 'any_reason',
    timestamp: 1597257441698
}
  • action: CLOSE_CONVERSATION

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

{
    "action": "ACCEPT_CONVERSATION",
    "conversationId": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
    "requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
    "parameters": {
        "status": "accepted",
        "contact": {
            "id": 12345,
            "channel": "whatsapp",
            "name": "John Doe",
            "email": "john.doe@gmail.com",
            "phone": "11998631234",
            "cpf": "12345678909"
} },
    "timestamp": 1597257441698
}

Atributos:

  • action: fixo com o valor ACCEPT_CONVERSATION

  • conversationId: mesmo do pedido de reabertura

  • parameters:

    • status: message_sent

    • contact: dados do atendimento

  • timestamp: momento da requisição.

REJECT_CONVERSATION (ALTU → Live chat)

Exemplo de payload que o ALTU enviará para o Live Chat quando o pedido de reabertura é negado.

{
    action: 'REJECT_CONVERSATION',
    conversationId: "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
    requestId: "6422fa06-dce1-11ea-87d0-0242ac130003",
    parameters: {
        status: "any_status",
        reason: "any_reason"
    },
    timestamp: 1597257441698,
}

Atributos:

  • action: fixo com o valor REJECT_CONVERSATION

  • conversationID: mesmo do pedido de reabertura

  • parameters:

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

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

Caso o payload gerado via JWT não seja válido.

Status Code: 401

{
	"requestId": "8eb4c2ac-dd60-11ea-87d0-0242ac130003",
	"message": "Unauthorized"
}
  • requestId: ID único que o ALTU gera que identifica o evento recebido

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

Caso o Altu receba algum evento que esteja mal formatado ou com algum parâmetro obrigatório faltando.

Status Code: 400

{
	"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
	"message": "missing conversationId"
}
  • requestId: ID único que o ALTU gera que identifica o evento recebido

  • message: Mensagem indicando o que está errado no evento recebido

Caso o dado solicitado não for encontrado, como um arquivo por exemplo, na action GET_FILE.

Status Code: 404

{
	"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
	"message": "not found"
}
  • requestId: ID único que o ALTU gera que identifica o evento recebido

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

Caso o Altu não consiga processar a requisição por algum motivo não esperado.

Status Code: 500

{
	"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
	"message": "Unexpected error. Please contact support."
}
  • 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.

Requisitos

    • 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

Configuração da 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

Eventos enviados e recebidos em um exemplo de reabertura de Live Chat:

A autenticação é feita via :‌

extraInfo: informações extras, citado em

A reabertura acontece por meio do envio de uma mensagem , e segue alguns padrões:

Integração do WhatsApp pelos LivePerson ou Zenvia

Um template de mensagem () específico para esse tipo de ocasião:

API de habilitada e configurada

Os campos para habilitar a possibilidade de reabertura de conversa estão dentro das configurações da integração com o , após habilitar a API de

Quando a integração é feita pelo Zenvia, é necessário informar o ID do template HSM (criado conforme as regras mencionadas acima)

https://agent.altubots.com/altu-connector/{slug}/{livechatId}
JWT
Iniciar LiveChat
JWT
Iniciar Live Chat
Iniciar LiveChat
outbound
brokers
HSM
Outbound
canal
Outbound
broker
Fluxo de eventos em um atendimento Live Chat
Fluxo de reabertura de atendimento em Live Chat