This document provides a comprehensive guide to using the Message, Review, and Question features developed for the Akinon Seller Center. It includes request and response examples for Omnitron, Commerce, and Project Zero products.
Different endpoints are used depending on the platform. Below are the specific URLs for making requests from Omnitron, Commerce, and Project Zero. Requests sent from Omnitron are sent by sellers, while requests sent from Commerce and Project Zero are sent by users.
For requests made from Omnitron, use the following URLs:
The number “1” that appears after remote in the URL represents the channel ID.
For requests made from Commerce, use the following URLs:
https://{commerce_url}/users/conversations/
For requests made from Project Zero, use the following URLs:
https://{storefront_url}/users/conversations/
https://{storefront_url}/users/messages/
Conversations created from Omnitron are used by sellers to inform users about various topics (e.g., when an ordered product is out of stock).
To delve into the concepts and methods more deeply:
Conversation
Conversation is the structure where communication between a user and a seller is established. For a message to be sent, the creation of a Conversation is initially expected. With conversation, messages between users and sellers can be created within this communication and these messages can be listed and filtered as desired.
Creating conversation objects allows for communication about products and orders—such as messages, questions, and reviews—as well as messaging and commenting independent of any specific product or order.
Different types of Conversations can be created, including:
Asking a question unrelated to a product or order,
Asking a question about a specific product or order,
Asking the status of an order,
Leaving a review on a purchased product or store, etc.
When creating a conversation object, the expected fields are as follows:
Required fields:
user
datasource
conversation_type
user_type
message_content
content_type
content_id
Optional fields:
subject
item_content
item_id
conversation
Briefly explaining these fields,
user and datasource are used to determine which user and seller (datasource) the conversation is between,
conversation_type indicates the type of communication (question, message, review),
message_content specifies the message content to be sent,
user_type distinguishes whether the user is registered in the system.
content_type tracks the sender of the message, which can either be a datasource (seller) or a user object, and content_id holds the ID of this object.
subject field, which is optional, serves as the subject heading.
item_content and item_id indicate which product or order item the communication relates to. item_content contains an object, while item_id holds the corresponding ID.
conversation field is used when adding a new message to an existing conversation by making a request to a previously created conversation. This field is relevant only when a new message is being added.
It's important to note that fields like user_type, content_type, content_id, and message_content are not stored within the conversation object itself. These fields are used when the conversation is created along with the initial message.
The following sections of this document provide examples of how to create Conversations and Messages for these various scenarios.
Order or Product Based Conversation
POST Create an Order/Product-Based Conversation
Path:/api/v1/remote/1/conversations/
To initiate conversation about a product;
item_content should be set to product, and item_id should be the ID of that object.
To initiate conversation about an order;
item_content should be set to orderitem, and item_id should be the ID of that object.
Example Request for Creating Product Based Conversation
When a request is successful, the response will include details such as the conversation type, the users and sellers (datasource) involved, and the related object, as shown below:
{
"id": 1,
"datasource": 1,
"user": 545382,
"subject": null,
"item_content": "orderitem",
"item_id": 1,
"conversation_type": "message",
"message_content": "hello this is the first message",
"user_type": "guest",
"content_id": 1,
"content_type": "user"
}
Example Response (400 Bad Request)
If a conversation already exists, any further messages should be sent within that existing conversation. If an attempt is made to create a duplicate conversation, the following response will be returned:
["Conversation already exists"]
POST Create an Order/Product-Based Message
To send a message to the seller regarding a product or order, the conversation_type parameter value is set to message.
Additionally, the request body must include the item_id and item_content parameters of the relevant product or order.
{
"id": 1,
"conversation_type": "question",
"user_type": "registered",
"message_content": "Hello, this is a question.",
"datasource": "1",
"content_type": "user",
"content_id": "545383",
"user": "545383"
}
POST Create a Review without Order/Product
Path:/users/conversations/
Unlike the methods mentioned above, for type of conversations review, the path /users/conversations/ is used instead of /api/v1/remote/1/conversations/. Since sellers cannot reply to reviews on a product or order, it is expected that such requests will come only from the endpoint used by users.
To leave a review directly to the store without referencing any product or order, conversation_type parameter value is set to review.
{
"id": 1,
"conversation_type": "review",
"user_type": "registered",
"message_content": "Hello, this is a review.",
"datasource": "1",
"content_type": "user",
"content_id": "545383",
"user": "545383"
}
If a request is sent from Omnitron to respond to a review with the conversation_type set to review, the following error message is received:
{"non_field_errors": ["DataSource can't reply to a review."]}
Adding New Messages to Conversation
If a message needs to be added to an existing conversation, the “id” value from the response returned for all created conversations above should be set in the conversation parameter in the body of the request, as shown in the example request below. The endpoints and other body parameters vary according to the methods as given above.
Below is an example request and response for the second message added to a conversation with "id": 9 by the user.
{
"id": 9,
"datasource": 1,
"user": 545383,
"item_id": 1,
"conversation_type": "review",
"message_content": "This is the second message.",
"user_type": "registered",
"content_id": 545383
}
Listing and Filtering Conversations
There are two endpoints available for listing conversation objects, one for commerce users and another for sellers. Both endpoints use the same filtering options.
Commerce users should send their requests to /users/conversations/.
Sellers should access the endpoint through /api/v1/remote/1/conversations/ via Omnitron.
GET Listing All Conversations
Example Request (Commerce)
Here is an example request for a commerce user to list their messages:
Below is an example request from a user for listing results filtered by both the data_source_id and conversation_type parameters for a specific seller, with conversation_type set to question.
Below is an example request from a seller for listing results filtered by both the data_source_id and conversation_type parameters for a specific seller, with conversation_type set to question.
Apart from these actions for conversations, there are no other actions such as deletion.
Messages
Messages are the entities contained within conversations. As noted in the conversation section, a message cannot be created without first creating a conversation object.
While there are two distinct endpoints for creating conversations, only one endpoint is used for creating messages: /api/v1/remote/1/messages/. It is also possible to send messages through conversation endpoints, as illustrated in the conversation section.
When sending a request to the endpoint, the following mandatory fields must be included:
{
"conversation": 9,
"message_content": "hello this is the first question",
"user_type": "guest",
"content_id": 545383,
"content_type": "user"
}
If content_type is set to datasource, a notification email will be sent to the user.
If a commerce user who is not found within the conversation attempts to request a conversation unrelated to them, the response returned will be as follows:
{"detail": "Bu işlemi yapmak için izniniz bulunmuyor."}
Public Questions & Reviews
This section contains the endpoints where content such as questions or reviews for sellers or products can be publicly published.
The following filters can be used to obtain more specific results when filtering conversations.
