Pular para o conteúdo principal

Chat com Cliente

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.

Desenho componentes do sistemao

Escopos necessários

Para a utilização das APIs os seguintes escopos poderão ser necessários:

ValorDescrição
services:conversations-seller:readPermite a utilização das APIs de leitura.
services:conversations-seller:writePermite a utilização das APIs de escrita/atualização.

Domínios da soluçāo

EntidadeDescrição
ConversationObjeto no qual contém as informações da conversa iniciada pelo cliente.
MessageMensagem enviada pelo cliente ou pelo seller.
MinimalMessageInformações básicas de uma mensagem.
OwnerInformação do usuário e enviou a mensagem. Utilizado para identificação dos responsáveis.
UserInformações detalhadas sobre os usuários envolvidos na conversa (Seller ou Cliente).
Custom FieldMapa de valores dinâmicos no qual pode ser utilizado para moldar as necessidades de negócios.
BlockRuleDetalhes do bloqueio efetuado em uma moderação.
ModerationTodas as mensagens são submetidas a moderação, eliminando assim a possibilidade de mensagens ofensivas e tentativas de fraudes por meios de engenharia social.
WebhookEventEvento a ser enviado via webhook.

Estrutúra básica dos campos

Conversation

CampoTipoDescrição
idStringIdentificador único da conversa.
display_nameStringDescrição da conversa.
ownerOwnerResponsável pela conversa. Normalmente faz referência ao to_user.
from_userUserUsuário que originou a conversa.
to_userUserDestinatanatário.
unread_from_countInteiroQuantidade de mensagens não lidas pelo criador da conversa (cliente).
unread_to_countInteiroQuantidade de mensagens não lidas pelo destinatário (seller).
statusStringStatus da conversa, pode assumir os valores: OPENED, CLOSED
last_messageMinimalMessageDescrição referente ao objeto de dúvida.
is_new_toBoleanoIndica se a conversa é nova para o destinatário.
tagsListaInformações de contexto sobre o objeto da conversa.
created_atStringData/hora (ISO 8601, ex: yyyy-mm-ddthh-mm-ssz) de criação do registro.
updated_atStringData/hora (ISO 8601) da última alteração do registro.

Message

CampoTipoDescrição
idStringIdentificador único da mensagem.
external_idStringIdentificador externo da mensagem.
from_userUserUsuário que originou a mensagem.
to_userUserDestinatanatário.
contentStringTexto da mensagem.
atttachmentsLista de URLsLista de URLs para anexos.
read_byLista de StringsLista de IDs de usuários que leram a mensagem.
moderationModerationObjeto que indica o status da moderação. Pode indicar que a mensagem enviada foi aprovada ou não.
when_atStringData/hora (ISO 8601) de quanto a mensagem foi enviada.
custom_fieldsLista de CustomFieldCampos adicionais no formato {"name": "field name", "value": "field value"}.
metadataDicionárioMetadados do sistema de origem.

MinimalMessage

CampoTipoDescrição
idStringIdentificador único da mensagem.
external_idStringIdentificador externo da mensagem.
from_userUserUsuário que originou a mensagem.
contentStringTexto da mensagem.
when_atStringData/hora (ISO 8601) de quanto a mensagem foi enviada.

Owner

CampoTipoDescrição
nameStringNome e sobrenome do usuário que fez a interação.
external_idStringIdentificador único do usuário no sistema que originou o evento.

User

CampoTipoDescrição
idStringIdentificador único do usuário.
external_idStringIdentificador externo do usuário. (ref_key)
full_nameStringNome completo do usuário/seller.
full_name_normalizedStringNome completo sem espaços e caracteres especiais.
typeStringTipo do usuário, pode assumir os valores: CUSTOMER e SELLER.
ownerOwnerPreenchido na criação de uma mensagem pelo seller.

CustomField

CampoTipoDescrição
nameStringNome do campo. (max 100 caracteres)
valueStringValor do campo. (max 1500 caracteres)

BlockRule

CampoTipoDescrição
reasonStringMotivo do bloqueio.
tagsLista de StringsTags registradas para o bloqueio, por exemplo: CPF, PIX, email.

Moderation

CampoTipoDescrição
statusStringNome e sobrenome do usuário que fez a interação. Pode assumir um dos valores: NOT_MODERATED, WAITING_MODERATION, REJECTED, APPROVED.
when_atStringData/hora (ISO 8601) de quanto a moderação foi registrada.
block_rulesLista de BlockRuleDetalhes das regras bloqueadas, caso o status seja REJECTED.

WebhookEvent

CampoTipoDescrição
data.domainStringDomínio que gerou o evento, pode assumir os valores: conversation e message.
data.statusStringStatus do Evento: NEW, UPDATED.
detail.conversation_idStringIdentificador da conversa que gerou o evento. Também é preenchido para eventos de mensagem, já que uma mensagem pertence a uma conversa.
detail.message_idStringIdentificador da mensagem que gerou o evento. Preenchido somente para eventos originados por mensagens.