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