# Conversation & Messages 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:** * https\://{omnitron\_url}/api/v1/remote/1/conversations/ * https\://{omnitron\_url}/api/v1/remote/1/messages/ {% hint style="warning" %} The number “1” that appears after remote in the URL represents the **channel ID**. {% endhint %} **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/ {% hint style="warning" %} Conversations created from Omnitron are used by sellers to inform users about various topics (e.g., when an ordered product is out of stock). {% endhint %} 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** ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef2f7f5f4dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "message", "user_type": "guest", "message_content": "Hello, this is the first message.", "datasource": "1", "content_type": "user", "content_id": "1", "user": "545382", "item_id": "1", "item_content": "product" }' ``` **Example Request for Creating Order Based Conversation** ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaeff27f54dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTdAecMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "message", "user_type": "guest", "message_content": "Hello, this is the first message.", "datasource": "1", "content_type": "user", "content_id": "1", "user": "545382", "item_id": "1", "item_content": "orderitem" }' ``` **Example Response (200 OK)** 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: ```json { "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. **Example Request** ```curl curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef2f7f5f4dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "message", "user_type": "guest", "message_content": "Hello, this is the first message.", "datasource": "1", "content_type": "user", "content_id": "1", "user": "545382", "item_id": "1", "item_content": "product" }' ``` **Example Response** ```json { "id": 1, "datasource": 1, "user": 545382, "subject": null, "item_content": "product", "item_id": 1, "conversation_type": "message", "message_content": "Hello, this is the first message.", "user_type": "guest", "content_id": 1, "content_type": "user" } ``` #### `POST` Create an Order/Product-Based Question To ask a question regarding the product or order, the **conversation\_type** parameter value is set to **question**. Additionally, the request body must include the **item\_id** and **item\_content** parameters of the relevant product or order. **Example Request** ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef2f7f5f4dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "question", "user_type": "guest", "message_content": "Hello, this is the first message.", "datasource": "1", "content_type": "user", "content_id": "1", "user": "545382", "item_id": "1", "item_content": "product" }' ``` **Example Response** ```json { "id": 1, "datasource": 1, "user": 545382, "subject": null, "item_content": "product", "item_id": 1, "conversation_type": "question", "message_content": "Hello, this is the first message.", "user_type": "guest", "content_id": 1, "content_type": "user" } ``` #### `POST` Create an Order/Product-Based Review To leave a review to the product or order, the **conversation\_type** parameter value is set to **review**. Additionally, the request body must include the **item\_id** and **item\_content** parameters of the relevant product or order. **Example Request** ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef2f7f5f4dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "review", "user_type": "guest", "message_content": "Hello, this is the first message.", "datasource": "1", "content_type": "user", "content_id": "1", "user": "545382", "item_id": "1", "item_content": "product" }' ``` **Example Response** ```json { "id": 1, "datasource": 1, "user": 545382, "subject": null, "item_content": "product", "item_id": 1, "conversation_type": "review", "message_content": "Hello, this is the first message.", "user_type": "guest", "content_id": 1, "content_type": "user" } ``` ### Conversation without Order or Product In addition to the actions mentioned above, users can also communicate with the seller without referencing any specific product or order. #### `POST` Create a Message without Order/Product **Path:** `/users/conversations/` To send a message directly to the store without referencing any product or order, `conversation_type` parameter value is set to `message`. **Example Request** ```json curl --location 'https://{commerce_url}/users/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef27f5ffdg4dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAdffecfMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "message", "user_type": "registered", "message_content": "Hello, this is a message.", "datasource": "1", "content_type": "user", "content_id": "545383", "user": "545383" }' ``` **Example Response** ```json { "id": 1, "datasource": 1, "user": 545383, "subject": null, "conversation_type": "message", "message_content": "Hello, this is a message.", "user_type": "registered", "content_id": 545383, "content_type": "user" } ``` #### `POST` Create a Question without Order/Product Path: `/users/conversations/` To ask a question directly to the store without referencing any product or order, `conversation_type` parameter value is set to `question`. **Example Request** ```json curl --location 'https://{commerce_url}/users/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "question", "user_type": "registered", "message_content": "Hello, this is a question.", "datasource": "1", "content_type": "user", "content_id": "545383", "user": "545383" }' ``` **Example Response** ```json { "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`. **Example Request** ```json curl --location 'https://{commerce_url}/users/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaefh27f54dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMgcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "review", "user_type": "registered", "message_content": "Hello, this is a review.", "datasource": "1", "content_type": "user", "content_id": "545383", "user": "545383" }' ``` **Example Response** ```json { "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: ```json {"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. **Example Request** ```json curl --location 'https://{commerce_url}/users/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef2d7f54dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2fwTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "review", "conversation": 9, "user_type": "registered", "message_content": “This is the second message.", "datasource": "1", "content_type": "user", "content_id": "545383", "user": "545383", "item_id": "1", "item_content": "product" }' ``` **Example Response** ```json { "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: ```json curl --location 'https://{commerce_url}/users/conversations/' \ --header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d' ``` **Example Response** ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 1, "user": { "id": 545382, "first_name": "", "last_name": "", "email": "akinon@hotmail.com", "phone": null, "gender": null }, "datasource": { "pk": 1, "name": "Test Shop", "slug": "test-shop", "title": "Test shopping", "supplier_code": "ard-123", "address": null, "email": null, "phone_number": null, "fax_number": null, "kep_address": null, "mersis_number": null, "trade_association": null, "extras": {}, "price_list": 1, "stock_list": 1, "is_active": true }, "item_object": { "pk": 1, "name": "Q800T QLED 8K Smart TV", "sku": "328187", "absolute_url": "/product/1/" }, "message_set": [ { "id": 1, "message_content": "hello this is the second message", "user_type": "registered", "content_object": { "id": 545382, "first_name": "", "last_name": "", "email": "akinon@hotmail.com", "phone": null, "gender": null } }, ... ], "conversation_type": "review", "last_message_date": "2023-07-19T10:25:40.208173Z" }, .... ] } ``` **Example Request (Omnitron)** Here is an example request for a seller to list their messages via Omnitron: ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \ --header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d' ``` **Example Response** ```json { "count": 12, "next": "https://{omnitron_url}/api/v1/remote/1/conversations/?page=2", "previous": null, "results": [ { "id": 2, "user": { "id": 545383, "first_name": "", "last_name": "", "email": "", "phone": null, "gender": null }, "datasource": { "pk": 2, "name": "Sin's Shop", "slug": "sin-shop", "title": "Sin's shopping", "supplier_code": "sin-123", "address": null, "email": null, "phone_number": null, "fax_number": null, "kep_address": null, "mersis_number": null, "trade_association": null, "extras": {}, "price_list": null, "stock_list": null, "is_active": true }, "item_object": null, "message_set": [ { "id": 9, "message_content": "hello this is the first message", "user_type": "guest", "content_object": { "id": 545383, "first_name": "", "last_name": "", "email": "", "phone": null, "gender": null } }, ... ] } ``` #### `GET` Listing Specific Conversations When listing specific conversations, you can use filter parameters to refine your search. The available filters are: * modified\_date * created\_date * user\_id * product * order\_item * item\_type * data\_source\_id * data\_source * product\_base\_code * conversation\_type * user\_\_first\_name * user\_\_last\_name * order\_number **Example Request (Commerce)** Below is an example request from a user for listing results filtered by the data\_source\_id parameter for a specific seller. ```json curl --location 'https://{commerce_url}/users/conversations/?data_source_id=1' \ --header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d' ``` **Example Response** ```json { "count": 5, "next": null, "previous": null, "results": [ { "id": 1, "user": { "id": 545382, "first_name": "", "last_name": "", "email": "akinon@akinon.com", "phone": null, "gender": null }, "datasource": { "pk": 1, "name": Test Shop", "slug": "test-shop", "title": "Test shopping", "supplier_code": "ard-123", "address": null, "email": null, "phone_number": null, "fax_number": null, "kep_address": null, "mersis_number": null, "trade_association": null, "extras": {}, "price_list": 1, "stock_list": 1, "is_active": true }, "item_object": { "pk": 1, "name": "Q800T QLED 8K Smart TV", "sku": "328187", "absolute_url": "/product/1/" }, "message_set": [ { "id": 1, "message_content": "hello this is the second message", "user_type": "registered", "content_object": { "id": 545382, "first_name": "", "last_name": "", "email": "akinon@akinon.com", "phone": null, "gender": null } }, ... ], "conversation_type": "review", "last_message_date": "2023-07-19T10:25:40.208173Z" }, .... ] } ``` **Example Request - 2 (Commerce)** 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**. ```json curl --location 'https://{commerce_url}/users/conversations/?data_source_id=1&conversation_type=question' \ --header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d' ``` **Example Request - 3 (Omnitron)** 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**. ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/?data_source_id=1&conversation_type=question' \ --header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d' ``` {% hint style="warning" %} Apart from these actions for conversations, there are no other actions such as deletion. {% endhint %} ### 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: * message\_content * conversation * content\_type * content\_id * user\_type **Example Request** ```json curl --location 'https://{omnitron_url}/api/v1/remote/1/messages/' \ --header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \ --header 'Content-Type: application/json' \ --header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \ --data '{ "conversation_type": "question", "user_type": "guest", "message_content": "Your question has been answered by the seller.", "datasource": "1", "content_type": "user", "content_id": "545383", "user": "545383", "conversation": "9" }' ``` **Example Response** ```json { "conversation": 9, "message_content": "hello this is the first question", "user_type": "guest", "content_id": 545383, "content_type": "user" } ``` {% hint style="warning" %} If **content\_type** is set to **datasource**, a notification email will be sent to the user. {% endhint %} {% hint style="warning" %} 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."} ``` {% endhint %} ### 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. * modified\_date * created\_date * user\_id * product * order\_item * item\_type * data\_source\_id * data\_source * product\_base\_code #### `GET` Listing Public Questions **Example Request** ```json curl --location 'https://{storefront_url}/public-questions/' \ --header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu' ``` **Example Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 11, "user": 1, "datasource": { "pk": 1, "name": "Test Shop", "slug": "test-shop", ... }, "item_object": null, "message_set": [ { "id": 7, "message_content": "hello this is the first question", "user_type": "registered", "content_object": { "id": 1, ... } } ], "conversation_type": "question", "last_message_date": null } ] } ``` #### `GET`Listing Public Reviews **Example Request** ```json curl --location 'https://{storefront_url}/public-reviews/' \ --header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu' ``` **Example Response** ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 12, "user": 2, "datasource": { "pk": 1, "name": "Test Shop", "slug": "test-shop", ... }, "item_object": null, "message_set": [ { "id": 10, "message_content": "this is the first review from commerce", "user_type": "registered", "content_object": { "id": 2, ... } }, { "id": 17, "message_content": "this is the second review", "user_type": "registered", "content_object": { "id": 2, ... } }, ], "conversation_type": "review", "last_message_date": null } ] } ```