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 dos canais de venda.
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 pelos canais de vendas.
Os canais de venda são as plataformas de e-commerce que ofertam e realizam as vendas dos produtos como o Magalu, Netshoes e outros.
A imagem abaixo mostra o escopo (caixa pontilhada) que será abordado.
Atualmente estará disponível apenas o canal de vendas "Magalu - Magazine Luiza, logo a funcionalidade estará disponível apenas para os vendedores que contratarem o serviço de Marketplace do Magalu. No futuro novos canais de venda poderão ser adicionados.
Se você já possui integração com o Magalu através das APIs antigas (Integracommerce), seu client já possui os scopes
para Perguntas & Respostas. Porém, ainda é necessário o consentimento dos usuários, para isso implemente o processo de
autenticação e autorização.
Se você não possui integração com as APIs antigas, basta seguir o processo de solicitação de criação de aplicação.

Escopos necessários
Para a utilização das APIs os seguintes escopos poderão ser necessários:
Valor |
Descrição |
services:conversations-seller:read |
Permite a utilização das APIs de leitura. |
services: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 e 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. |
Estrutúra básica dos campos
Conversation
Campo |
Tipo |
Descrição |
id |
String |
Identificador único da conversa. |
display_name |
String |
Descrição da conversa. |
owner |
Owner |
Responsável pela conversa. Normalmente faz referência ao to_user. |
from_user |
User |
Usuário que originou a conversa. |
to_user |
User |
Destinatanatá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. |
external_id |
String |
Identificador externo da mensagem. |
from_user |
User |
Usuário que originou a mensagem. |
to_user |
User |
Destinatanatário. |
content |
String |
Texto da mensagem. |
atttachments |
Lista de URLs |
Lista de URLs para anexos. |
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. |
external_id |
String |
Identificador externo 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. |
external_id |
String |
Identificador externo do usuário. (ref_key) |
full_name |
String |
Nome completo do usuário/seller. |
full_name_normalized |
String |
Nome completo sem espaços e caracteres especiais. |
type |
String |
Tipo do usuário, pode assumir os valores: CUSTOMER e SELLER. |
owner |
Owner |
Preenchido na criação de uma mensagem pelo 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 quanto 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. |