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