Introdução
O que é
Este documento descreve o conjunto de APIs chamado de “Chat com Cliente”, qual suporta a funcionalidade para a interação de forma privada entre vendedores e os clientes da plataforma Eu Preciso.
Essa ferramenta visa fornecer aos potenciais compradores (clientes) informações adicionais sobre os produtos, ajudando-os a tomar decisões mais assertivas e reduzindo as incertezas no processo de compra.
A partir do momento que o cliente abre um Chat sobre o produto com o vendedor, este canal de comunicação fica aberto para a troca de mensagens, mesmo após a efetivação de um pedido pelo cliente.
Os vendedores são responsáveis pela publicação dos produtos que serão comercializados na plataforma.
Escopos necessários
Para a utilização das APIs os seguintes escopos poderão ser necessários:
| Valor | Descrição |
|---|---|
conversations-seller:read | Permite a utilização das APIs de leitura. |
conversations-seller:write | Permite a utilização das APIs de escrita/atualização. |
Domínios da solução
| Entidade | Descrição |
|---|---|
Conversation | Objeto no qual contém as informações da conversa iniciada pelo cliente. |
Message | Mensagem enviada pelo cliente ou pelo seller. |
MinimalMessage | Informações básicas de uma mensagem. |
Owner | Informação do usuário que enviou a mensagem. Utilizado para identificação dos responsáveis. |
User | Informações detalhadas sobre os usuários envolvidos na conversa (Seller ou Cliente). |
Custom Field | Mapa de valores dinâmicos no qual pode ser utilizado para moldar as necessidades de negócios. |
BlockRule | Detalhes do bloqueio efetuado em uma moderação. |
Moderation | Todas as mensagens são submetidas a moderação, eliminando assim a possibilidade de mensagens ofensivas e tentativas de fraudes por meios de engenharia social. |
WebhookEvent | Evento a ser enviado via webhook. |
Estrutura básica dos campos
Conversation
| Campo | Tipo | Descrição |
|---|---|---|
id | String | Identificador único da conversa. |
display_name | String | Descrição da conversa. |
from_user | User | Usuário que originou a conversa. |
to_user | User | Destinatário. |
unread_from_count | Inteiro | Quantidade de mensagens não lidas pelo criador da conversa (cliente). |
unread_to_count | Inteiro | Quantidade de mensagens não lidas pelo destinatário (seller). |
status | String | Status da conversa, pode assumir os valores: OPENED, CLOSED |
last_message | MinimalMessage | Descrição referente ao objeto de dúvida. |
is_new_to | Boleano | Indica se a conversa é nova para o destinatário. |
tags | Lista | Informações de contexto sobre o objeto da conversa. |
created_at | String | Data/hora (ISO 8601, ex: yyyy-mm-ddthh-mm-ssz) de criação do registro. |
updated_at | String | Data/hora (ISO 8601) da última alteração do registro. |
Message
| Campo | Tipo | Descrição |
|---|---|---|
id | String | Identificador único da mensagem. |
from_user | User | Usuário que originou a mensagem. |
to_user | User | Destinatário. |
content | String | Texto da mensagem. |
read_by | Lista de Strings | Lista de IDs de usuários que leram a mensagem. |
moderation | Moderation | Objeto que indica o status da moderação. Pode indicar que a mensagem enviada foi aprovada ou não. |
when_at | String | Data/hora (ISO 8601) de quanto a mensagem foi enviada. |
custom_fields | Lista de CustomField | Campos adicionais no formato {“name”: “field name”, “value”: “field value”}. |
metadata | Dicionário | Metadados do sistema de origem. |
MinimalMessage
| Campo | Tipo | Descrição |
|---|---|---|
id | String | Identificador único da mensagem. |
from_user | User | Usuário que originou a mensagem. |
content | String | Texto da mensagem. |
when_at | String | Data/hora (ISO 8601) de quanto a mensagem foi enviada. |
Owner
| Campo | Tipo | Descrição |
|---|---|---|
name | String | Nome e sobrenome do usuário que fez a interação. |
external_id | String | Identificador único do usuário no sistema que originou o evento. |
User
| Campo | Tipo | Descrição |
|---|---|---|
id | String | Identificador único do usuário. |
full_name | String | Nome de exibição do usuário/seller. |
type | String | Tipo do usuário, pode assumir os valores: CUSTOMER e SELLER. |
CustomField
| Campo | Tipo | Descrição |
|---|---|---|
name | String | Nome do campo. (max 100 caracteres) |
value | String | Valor do campo. (max 1500 caracteres) |
BlockRule
| Campo | Tipo | Descrição |
|---|---|---|
reason | String | Motivo do bloqueio. |
tags | Lista de Strings | Tags registradas para o bloqueio, por exemplo: CPF, PIX, email. |
Moderation
| Campo | Tipo | Descrição |
|---|---|---|
status | String | Nome e sobrenome do usuário que fez a interação. Pode assumir um dos valores: NOT_MODERATED, WAITING_MODERATION, REJECTED, APPROVED. |
when_at | String | Data/hora (ISO 8601) de quando a moderação foi registrada. |
block_rules | Lista de BlockRule | Detalhes das regras bloqueadas, caso o status seja REJECTED. |
WebhookEvent
| Campo | Tipo | Descrição |
|---|---|---|
data.domain | String | Domínio que gerou o evento, pode assumir os valores: conversation e message. |
data.status | String | Status do Evento: NEW, UPDATED. |
detail.conversation_id | String | Identificador da conversa que gerou o evento. Também é preenchido para eventos de mensagem, já que uma mensagem pertence a uma conversa. |
detail.message_id | String | Identificador da mensagem que gerou o evento. Preenchido somente para eventos originados por mensagens. |