Skip to main content

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/
NOTE

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/
NOTE

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​

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​

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:

{
"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 --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​

{
"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​

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​

{
"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​

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​

{
"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​

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​

{
"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​

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​

{
"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​

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​

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

Example Request​

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​

{
 "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:

curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'

Example Response​

{
    "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:

curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'

Example Response​

{
    "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

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.

curl --location 'https://{commerce_url}/users/conversations/?data_source_id=1' \
--header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'

Example Response​

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

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.

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'
NOTE

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:

  • message_content
  • conversation
  • content_type
  • content_id
  • user_type

Example Request​

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​

{
    "conversation": 9,
    "message_content": "hello this is the first question",
    "user_type": "guest",
    "content_id": 545383,
    "content_type": "user"
}
NOTE

If content_type is set to datasource, a notification email will be sent to the user.

NOTE

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.

  • 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​

curl --location 'https://{storefront_url}/public-questions/' \
--header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu'

Example Response​

{
    "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
        }
    ]
}

GETListing Public Reviews​

Example Request​

curl --location 'https://{storefront_url}/public-reviews/' \
--header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu'

Example Response​

{
    "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
        }
    ]
}