ALTU
Search…
Agent connector API
O Agent Connector API permite que plataformas externas realizem atendimentos de Live Chat no ALTU.

Overview

Esta API consiste no envio e recebimento de eventos, através de chamadas http.
  • O ALTU enviará eventos para o Live Chat através de chamadas POST ao webhook configurado na integração
  • O Live Chat enviará eventos para o ALTU 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:
1
{
2
"action":"Tipo do evento",
3
"conversationID":"Id único que identifica a conversa de live chat",
4
"identifier":"Id único que identifica a usuário no ALTU",
5
"parameters":{
6
...
7
},
8
"timestamp":"Horário do envio do evento em formato UNIX timestamp"
9
}
Copied!
Envie também dados do usuário para o agente, saiba como configurar em:

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 ALTU
1
{
2
"alg": "RS256",
3
"typ": "JWT"
4
}
5
.
6
{
7
"access_token": "pDD8w6VeTjnk03MxGqwSsEneuaykfkVvfpfUnus2",
8
"iat": 1653066200,
9
"exp": 1653066260
10
}
Copied!
  • 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 ALTU 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 ALTU:

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

Fluxo de eventos em um atendimento Live Chat
OPEN_CONVERSATION + HISTÓRICO
OPEN_CONVERSATION
ACCEPT_CONVERSATION
REJECT_CONVERSATION
SEND_MESSAGE
UPLOAD_FILE
SEND_FILE
GET_FILE
CLOSE_CONVERSATION
REOPEN_CONVERSATION
Evento enviado do ALTU para a plataforma de Livechat para solicitar a abertura de um novo atendimento.
Payload:
1
{
2
"action": "OPEN_CONVERSATION",
3
"conversationId": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId": "0d0c341a-dcca-11ea-87d0-0242ac130003",
5
"identifier": "6422fa06-dce1-11ea-87d0-0242ac130003",
6
"skillId": "teste_liveChat",
7
"agent": "dr9383jjcdl0839",
8
"parameters": {
9
"contact": {
10
"id": "contact.id",
11
"name": "contact.name",
12
"email": "contact.email",
13
"phone": "contact.phone",
14
"cpf": "contact.cpf",
15
"extra": {},
16
"history": [
17
{
18
"id": null,
19
"time": "2021-02-18T20:12:20.191Z",
20
"sender": "user",
21
"message": "Oi",
22
"assistant_id": 1
23
},
24
{
25
"id": null,
26
"time": "2021-02-18T20:12:21.557Z",
27
"sender": "bot",
28
"message": [
29
{
30
"default": {
31
"text": "Olá contact.name, seja bem-vindo! Em que posso te ajudar?",
32
"type": "text"
33
}
34
}
35
],
36
"assistant_id": 1
37
}
38
]
39
},
40
"extraInfo": {}
41
},
42
"timestamp": 1597256758383
43
}
Copied!
  • action: OPEN_CONVERSATION (solicitação de atendimento)
  • conversationId: ID único gerado pelo ALTU que representa a sessão de live chat.
  • 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.
  • agent (opcional): ID do agente que atenderá o usuário. Id pode ser número ou string.
  • parameters:
    • contact:
      • id: ID do atendimento no ALTU
      • name (opcional): nome do usuário
      • email (opocional): email do usuário
      • phone (opcional): telefone do usuário
      • cpf (opcional): cpf do usuário
      • history(opcional): histórico de mensagens trocadas entre o usuário e o(s) assistente(s) a partir do evento new_dialog
        • 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
Evento enviado do ALTU para a plataforma de Livechat para solicitar a abertura de um novo atendimento.
Payload:
1
{
2
"action":"OPEN_CONVERSATION",
3
"conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"0d0c341a-dcca-11ea-87d0-0242ac130003",
5
"identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
6
"skillId":"teste_liveChat",
7
"parameters":{
8
"contact":{
9
"id": "contact.id",
10
"name":"contact.name",
11
"email":"contact.email",
12
"phone":"contact.phone",
13
"cpf":"contact.cpf",
14
"extra":{},
15
"extraInfo":{
16
17
}
18
},
19
"timestamp":1597256758383
20
}
Copied!
  • 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): nome do usuário
      • email (opocional): email do usuário
      • phone (opcional): telefone do usuário
      • cpf (opcional): cpf do usuário
      • 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:
1
{
2
"action": "ACCEPT_CONVERSATION",
3
"conversationID": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"parameters": {
5
"agent": {
6
"id": 12,
7
"name": "Mary Kate"
8
}
9
},
10
"timestamp": 1597257441698
11
}
Copied!
  • 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
1
{
2
"action":"ACCEPT_CONVERSATION",
3
"conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"0d0c341a-87d0-11ea-dcca-0242ac130003",
5
"parameters":{
6
"status":"accepted",
7
"contact":{
8
"id":12345,
9
"name":"Sem nome",
10
"email":"",
11
"phone":"11998631234",
12
"cpf":""
13
}
14
},
15
"timestamp":1597257441698
16
}
Copied!
  • 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
  • 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:
1
{
2
"action":"REJECT_CONVERSATION",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"live_chat":{
5
"status":"closed",
6
"reason":"razao"
7
},
8
"timestamp":1597257441698
9
}
Copied!
  • 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:
1
{
2
"action":"REJECT_CONVERSATION",
3
"conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"0d0c341a-dcca-11ea-87d0-0242ac130003",
5
"parameters":{
6
"status":"contact_in_conversation",
7
"reason":"The contact is already in an conversation"
8
},
9
"timestamp":1597257441698
10
}
Copied!
  • 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:
1
{
2
"action":"SEND_MESSAGE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
5
"identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
6
"parameters":{
7
"contact":{
8
"id":12345,
9
"name":"John Doe",
10
"email":"[email protected]",
11
"phone":"11998631234",
12
"cpf":"12345678909"
13
},
14
"messages":[
15
"Gostaria de contestar uma compra realizada em meu cartão"
16
],
17
"type":"information"
18
},
19
"timestamp":1597257441698
20
}
Copied!
  • action: SEND_MESSAGE
  • 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): nome do usuário
      • email (opocional): email do usuário
      • phone (opcional): telefone do usuário
      • cpf (opcional): cpf do usuário
    • 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:
1
{
2
"action":"SEND_MESSAGE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"parameters":{
5
"agent":{
6
"id":12,
7
"name":"Mary Kate"
8
},
9
"messages":[
10
"Olá!",
11
"Aguarde um momento, por favor..."
12
]
13
},
14
"timestamp":1597257441698
15
}
Copied!
  • 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":
1
{
2
"action":"SEND_MESSAGE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
5
"identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
6
"parameters":{
7
"contact":{
8
"id":12345,
9
"name":"John Doe",
10
"email":"[email protected]",
11
"phone":"11998631234",
12
"cpf":"12345678909"
13
},
14
"location":{
15
"latitude":-22.4207974,
16
"longitude":-45.469118
17
}
18
},
19
"timestamp":1597257441698
20
}
Copied!
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:
1
{
2
"action":"UPLOAD_FILE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"file":{
5
"contentType":"image/jpeg|image/png|application/pdf",
6
"buffer":"<Buffer ..."
7
},
8
"timestamp":1597257441698
9
}
Copied!
  • 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
1
{
2
"fileId": "6671950e-a933-4bec-9070-dc71cf464c1f",
3
"requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
4
"message": "OK"
5
}
Copied!
  • 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:
1
{
2
"action":"SEND_FILE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"requestId":"4fcb43c4-dce1-11ea-87d0-0242ac130003",
5
"identifier":"6422fa06-dce1-11ea-87d0-0242ac130003",
6
"parameters":{
7
"contact":{
8
"id":12345,
9
"name":"John Doe",
10
"email":"[email protected]",
11
"phone":"11998631234",
12
"cpf":"12345678909"
13
},
14
"file":{
15
"id":"6671950e-a933-4bec-9070-dc71cf464c1f",
16
"name":"cachorro.jpg",
17
"contentType":"image/jpeg",
18
"type":"jpg",
19
"size":5855,
20
"caption":"Um cachorro"
21
}
22
},
23
"timestamp":1597257441698
24
}
Copied!
  • 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): 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:
1
{
2
"action":"SEND_FILE",
3
"conversationID":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"parameters":{
5
"agent":{
6
"id":12,
7
"name":"Mary Kate"
8
},
9
"file":{
10
"id":"6671950e-a933-4bec-9070-dc71cf464c1f"
11
}
12
},
13
"timestamp":1597257441698
14
}
Copied!
  • 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
      • 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:
1
{
2
"action": "GET_FILE",
3
"fileId": "6671950e-a933-4bec-9070-dc71cf464c1f",
4
"requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
5
"timestamp": 1597257441698
6
}
Copied!
  • 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
1
{
2
"file": {
3
"contentLength": 59662,
4
"contentType": "image/png",
5
"type": "png",
6
"buffer": {
7
"type": "Buffer",
8
"data": [...]
9
}
10
},
11
"requestId": "4fcb43c4-dce1-11ea-87d0-0242ac130003",
12
"message": "OK"
13
}
Copied!
  • 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:
1
{
2
"action": "GET_FILE",
3
"fileId": "6671850e-a933-4bec-9070-dc71cf464c1f",
4
"timestamp": 1597445441898
5
}
Copied!
  • 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:
1
{
2
"action": "CLOSE_CONVERSATION",
3
"conversationId": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"live_chat": {
5
"status": "closed",
6
"reason": "razao"
7
},
8
"requestId": "6422fa06-dce1-11ea-87d0-0242ac130003",
9
"identifier": "6422fa06-dce1-11ea-87d0-0242ac130003",
10
"timestamp": 1597257441698
11
}
Copied!
  • action: CLOSE_CONVERSATION (Encerramento de atendimento)
  • 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
  • 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:
1
{
2
"action":"CLOSE_CONVERSATION",
3
"conversationId":"1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"timestamp":1597257441698
5
}
Copied!
  • action: CLOSE_CONVERSATION (Encerramento de atendimento)
  • conversationId: ID da sessão enviado pelo Altu no evento de OPEN_CONVERSATION
  • 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
1
{
2
"action": "REOPEN_CONVERSATION",
3
"conversationId": "700bf535-9f1c-491d-8ab3-09ee82d0825a",
4
"parameters": {
5
"expirationTime": "30",
6
"message": "Mensagem a ser enviada para o usuário para a reabertura da conversa"
7
},
8
"timestamp": 1597257441698,
9
}
Copied!
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.
1
{
2
"action": "ACCEPT_CONVERSATION",
3
"conversationId": "700bf535-9f1c-491d-8ab3-09ee82d0825a",
4
"parameters": {
5
"status": "message_sent",
6
"contact": {
7
"id": 12345,
8
"phone": "35998631234"
9
}
10
},
11
"timestamp": 1597257441698
12
}
Copied!
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.
1
{
2
"action": "REJECT_CONVERSATION",
3
"conversationId": "700bf535-9f1c-491d-8ab3-09ee82d0825a",
4
"parameters": {
5
"status": "message_not_sent",
6
"reason": "Razão de não ter conseguido enviar o outbound"
7
},
8
"timestamp": 1597257441698
9
}
Copied!
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

1
{
2
"action": "SEND_STATUS",
3
"conversationID": "1be5e1d3-d949-44ab-86a7-6d032b0cd17e",
4
"parameters": {
5
"status": "read"
6
},
7
"timestamp": 1597257441698
8
}
Copied!

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 ALTU.
  • 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 ALTU irá indicar se o evento recebido foi processado corretamente ou não:
Sucesso
Não autorizado
Inválido
Dado não encontrado
Erro Inesperado
Status Code: 200
1
{
2
"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
3
"message": "OK"
4
}
Copied!
  • requestId: ID único que o Altu 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
1
{
2
"requestId": "8eb4c2ac-dd60-11ea-87d0-0242ac130003",
3
"message": "Unauthorized"
4
}
Copied!
  • 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
1
{
2
"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
3
"message": "missing conversationId"
4
}
Copied!
  • 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
1
{
2
"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
3
"message": "not found"
4
}
Copied!
  • 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
1
{
2
"requestId": "9c2da0b8-dce1-11ea-87d0-0242ac130003",
3
"message": "Unexpected error. Please contact support."
4
}
Copied!
  • 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 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:
Fluxo de reabertura de atendimento em Live Chat