Introduction
What it is
This document describes the set of APIs called "Chat with Customer", which supports functionality for private
private interaction between salespeople and sales channel customers.
This tool aims to provide potential buyers (customers) with additional information about products,
helping them to make more assertive decisions and reducing uncertainty in the purchasing process.
From the moment the customer opens a Chat about the product with the salesperson, this communication channel
remains open for the exchange of messages, even after the customer has placed an order.
The sellers are responsible for publishing the products that will be sold through the sales channels.
The sales channels are the e-commerce platforms that offer and sell the products, such as Magalu, Netshoes and others.
The image below shows the scope (dotted box) that will be covered.
Currently only the "Magalu - Magazine Luiza" sales channel will be available, so the functionality will only be available to sellers who contract Magalu's Marketplace service. New sales channels may be added in the future.
If you already integrate with Magalu via the old APIs (Integracommerce), your client already has the scopes
for Q&A. However, you still need users' consent, so implement the
authentication and authorization.
If you don't have integration with the old APIs, just follow the [application creation] request process (https://developers.magalu.com/docs/first_steps/create_an_application/create_application/).
Required scopes
The following scopes may be required to use the APIs:
| Value |
Description |
services:conversations-seller:read |
Enables the use of the reading APIs. |
services:conversations-seller:write |
Allows use of the write/update APIs. |
Solution domains
| Entity |
Description |
| Conversation |
Object in which contains the information of the conversation initiated by the customer. |
| Message |
Message sent by the customer or seller. |
| MinimalMessage |
Basic information of a message. |
| Owner |
Information about the user who sent the message. Used to identify those responsible. |
| User |
Detailed information about the users involved in the conversation (Seller or Customer). |
| Custom Field |
Dynamic value map which can be used to shape business needs. |
| BlockRule |
Details of the block made in a moderation. |
| Moderation |
All messages are subject to moderation, thus eliminating the possibility of offensive messages and fraud attempts through social engineering. |
| WebhookEvent |
Event to be sent via webhook. |
Basic structure of fields
Conversation
| Field |
Type |
Description |
| id |
String |
Unique identifier of the conversation. |
| display_name |
String |
Conversation description. |
| owner |
Owner |
Responsible for the conversation. Usually refers to to_user. |
| from_user |
User |
User who originated the conversation. |
| to_user |
User |
Recipient. |
| unread_from_count |
Integer |
Number of messages not read by the creator of the conversation (client). |
| unread_to_count |
Integer |
Number of messages not read by the recipient (seller). |
| status |
String |
Status of the conversation, can take the values: OPENED, CLOSED |
| last_message |
MinimalMessage |
Description of the query object. |
| is_new_to |
Boolean |
Indicates whether the conversation is new to the recipient. |
| tags |
List |
Context information about the conversation object. |
| created_at |
String |
Date/time (ISO 8601, e.g. yyyy-mm-ddthh-mm-ssz) of record creation. |
| updated_at |
String |
Date/time (ISO 8601) when the record was last changed. |
Message
| Field |
Type |
Description |
| id |
String |
Unique identifier of the message. |
| external_id |
String |
External identifier of the message. |
| from_user |
User |
User who originated the message. |
| to_user |
User |
Recipient. |
| content |
String |
Message text. |
| atttachments |
List of URLs |
List of URLs for attachments. |
| read_by |
List of Strings |
List of IDs of users who have read the message. |
| moderation |
Moderation |
Object that indicates the moderation status. It can indicate that the message sent was approved or not. |
| when_at |
String |
Date/time (ISO 8601) when the message was sent. |
| custom_fields |
CustomField list |
Additional fields in the format {"name": "field name", "value": "field value"}. |
| metadata |
Dictionary |
Source system metadata. |
MinimalMessage
| Field |
Type |
Description |
| id |
String |
Unique identifier of the message. |
| external_id |
String |
External identifier of the message. |
| from_user |
User |
User who originated the message. |
| content |
String |
Message text. |
| when_at |
String |
Date/time (ISO 8601) when the message was sent. |
Owner
| Field |
Type |
Description |
| name |
String |
First and last name of the user who made the interaction. |
| external_id |
String |
Unique identifier of the user in the system that originated the event. |
User
| Field |
Type |
Description |
| id |
String |
User's unique identifier. |
| external_id |
String |
User's external identifier. (ref_key) |
| full_name |
String |
User/seller's full name. |
| full_name_normalized |
String |
Full name without spaces and special characters. |
| type |
String |
User type, can take the values: CUSTOMER and SELLER. |
| owner |
Owner |
Filled in when the seller creates a message. |
CustomField
| Field |
Type |
Description |
| name |
String |
Field name (max 100 characters) |
| value |
String |
Field value. (max 1500 characters) |
BlockRule
| Field |
Type |
Description |
| reason |
String |
Reason for block. |
| tags |
List of Strings |
Tags registered for the block, for example: CPF, PIX, email. |
Moderation
| Field |
Type |
Description |
| status |
String |
First and last name of the user who made the interaction. Can take one of the following values: NOT_MODERATED, WAITING_MODERATION, REJECTED, APPROVED. |
| when_at |
String |
Date/time (ISO 8601) when moderation was recorded. |
| block_rules |
BlockRule list |
Details of blocked rules, if status is REJECTED. |
WebhookEvent
| Field |
Type |
Description |
| data.domain |
String |
Domain that generated the event, can take the values: conversation and message. |
| data.status |
String |
Event status: NEW, UPDATED. |
| detail.conversation_id |
String |
Identifier of the conversation that generated the event. Also filled in for message events, since a message belongs to a conversation. |
| detail.message_id |
String |
Identifier of the message that generated the event. Only filled in for events originating from messages. |