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. |