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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.altu.d1.cx/connect/apis/agent-connector-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.