> For the complete documentation index, see [llms.txt](https://docs.altu.d1.cx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.altu.d1.cx/connect/apis/agent-connector-sdk.md).

# 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}>&#x20;
* A autenticação do envio e recebimento de eventos será feita via [JWT](https://jwt.io/). 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:

{% content-ref url="/pages/-MYKG\_e7m0SmB9XWqm84" %}
[Iniciar LiveChat](/build/assistentes/builder/componentes/actions/start_live_chat.md)
{% endcontent-ref %}

## Autenticação <a href="#autenticacao" id="autenticacao"></a>

A autenticação é feita via [JWT](https://jwt.io/):‌

* 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);&#x20;
* 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 <a href="#eventos" id="eventos"></a>

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_info`que é 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 NL&#x55;**:**

* **`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](/files/UpFV35N0tY3UXu01FFY9)

{% tabs %}
{% tab title="OPEN\_CONVERSATION + HISTÓRICO" %}
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](/build/assistentes/builder/componentes/actions/start_live_chat.md)
* **timestamp:** UNIX timestamp do momento de envio do evento
  {% endtab %}

{% tab title="OPEN\_CONVERSATION" %}
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&#x20;
* **timestamp:** UNIX timestamp do momento de envio do evento
  {% endtab %}

{% tab title="ACCEPT\_CONVERSATION" %}
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
  {% endtab %}

{% tab title="REJECT\_CONVERSATION" %}
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:&#x20;

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.
  {% endtab %}

{% tab title="SEND\_MESSAGE" %}
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.

{% hint style="info" %}
Quando for enviada a localização o atributo "messages" não será enviado.
{% endhint %}
{% endtab %}

{% tab title="UPLOAD\_FILE" %}
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.

{% endtab %}

{% tab title="SEND\_FILE" %}
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
  {% endtab %}

{% tab title="GET\_FILE" %}
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.
  {% endtab %}

{% tab title="CLOSE\_CONVERSATION" %}
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&#x20;
* **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`
{% endtab %}

{% tab title="REOPEN\_CONVERSATION" %}
Evento enviado pelo agente para reabrir um atendimento com um determinado usuário.<br>

#### **Live chat para ALTU (agente para usuário)**

Exemplo de payload a ser enviado do Live Chat para o ALTU<br>

```
{
    "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ári&#x6F;**.**<br>

```
{
    "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.<br>

#### REJECT\_CONVERSATION (ALTU → Live chat)

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

```
{
    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.
    {% endtab %}
    {% endtabs %}

## 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”.&#x20;

{% hint style="info" %}
Funcionalidade disponível apenas para o canal Widget.
{% endhint %}

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

{% tabs %}
{% tab title="Sucesso" %}
Status Cod&#x65;**: `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
  {% endtab %}

{% tab title="Não autorizado" %}
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
  {% endtab %}

{% tab title="Inválido" %}
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

{% endtab %}

{% tab title="Dado não encontrado" %}
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
  {% endtab %}

{% tab title="Erro Inesperado" %}
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
  {% endtab %}
  {% endtabs %}

Para saber mais como usa-lo em um assistente:

{% content-ref url="/pages/-MYKG\_e7m0SmB9XWqm84" %}
[Iniciar LiveChat](/build/assistentes/builder/componentes/actions/start_live_chat.md)
{% endcontent-ref %}

## 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](/connect/apis/outbound.md), e segue alguns padrões:

### Requisitos

* Integração do **WhatsApp** pelos [brokers](/mais/glossario.md) **LivePerson ou** **Zenvia**&#x20;
* Um template de mensagem ([HSM](/mais/glossario.md)) **específico** para esse tipo de ocasião:&#x20;
  * Esse template HSM deve ter **apenas UMA variável**&#x20;
  * Quando for possível nomear a variável, como é o caso da Zenvia, ela deve ter o nome de `message`
* API de [Outbound ](/connect/apis/outbound.md)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](https://docs.altu.com.br/connect/canais), após habilitar a API de [Outbound](https://docs.altu.com.br/connect/apis/outbound)

### LivePerson V1

Para a V1 da LivePerson, basta inserir o **nome do template HSM** criado (conforme os requisitos mencionados acima)

![](/files/-MgClXQJzIsPYz5XV-fy)

### 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.&#x20;

![](/files/-MgCsrK95Lg4IF8p6w5Y)

### Zenvia

Quando a integração é feita pelo [broker ](/mais/glossario.md)Zenvia, é necessário informar o **ID do template** HSM (criado conforme as regras mencionadas acima)

![](/files/-MgCtWuuoYQIxQg_3kXZ)

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

![Fluxo de reabertura de atendimento em Live Chat](/files/gBIfkqK6QlmWlrMPevKr)