Skip to main content
All chat endpoints require authentication with auth:sanctum.

​
Overview

The chat system allows customers to communicate with sellers about products. Each conversation is linked to a product and contains multiple messages.

​
Get Conversations

​
Query Parameters

​
page
integer
default:"1"
Page number

​
Response

Returns paginated list of conversations where the authenticated user is the sender, ordered by most recent first.

​
Example

curl -X GET https://your-domain.com/api/v2/chat/conversations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Get Messages

​
Path Parameters

​
id
integer
required
Conversation ID

​
Query Parameters

​
page
integer
default:"1"
Page number

​
Response

Returns paginated list of messages in the conversation, ordered by most recent first.

​
Example

curl -X GET https://your-domain.com/api/v2/chat/messages/123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Create Conversation

​
Request

​
product_id
integer
required
Product ID to inquire about
​
title
string
required
Conversation title/subject
​
message
string
required
Initial message content

​
Response

​
result
boolean
Success status
​
message
string
Success message
​
conversation_id
integer
Created conversation ID
​
shop_name
string
Seller’s shop name or “In House Product”
Seller’s shop logo URL
​
title
string
Conversation title

​
Example

curl -X POST https://your-domain.com/api/v2/chat/create-conversation \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "title": "Question about product size",
    "message": "Do you have this in size XL?"
  }'
When a conversation is created:
  • An initial message is automatically added
  • Email notification is sent to the seller
  • Conversation is linked to the product

​
Send Message

​
Request

​
conversation_id
integer
required
Conversation ID
​
message
string
required
Message content

​
Response

Returns the created message object in a collection format.

​
Example

curl -X POST https://your-domain.com/api/v2/chat/insert-message \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 123,
    "message": "Thank you for your response!"
  }'

​
Get New Messages

​
Path Parameters

​
conversation_id
integer
required
Conversation ID
​
last_message_id
integer
required
Last message ID the client has

​
Response

Returns messages with ID greater than last_message_id, ordered by most recent first.

​
Example

curl -X GET https://your-domain.com/api/v2/chat/get-new-messages/123/456 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Use this endpoint for polling new messages in real-time chat interfaces.

​
Conversation Response Structure

​
id
integer
Conversation ID
​
sender_id
integer
Customer user ID
​
receiver_id
integer
Seller user ID
​
title
string
Conversation subject
​
sender_viewed
string
Whether sender has viewed (0 or 1)
​
receiver_viewed
string
Whether receiver has viewed (0 or 1)
​
created_at
string
Creation timestamp

​
Message Response Structure

​
id
integer
Message ID
​
conversation_id
integer
Parent conversation ID
​
user_id
integer
Sender user ID
​
message
string
Message content
​
created_at
string
Message timestamp

​
Chat Flow

​
1. Starting a Conversation

  1. Customer views a product
  2. Customer clicks “Contact Seller”
  3. App calls /api/v2/chat/create-conversation with product_id
  4. Conversation is created and seller receives email notification

​
2. Sending Messages

  1. User views conversation messages
  2. User types and sends message
  3. App calls /api/v2/chat/insert-message
  4. Message is added to conversation
  5. View status is updated

​
3. Polling for New Messages

  1. App stores the latest message ID
  2. Periodically calls /api/v2/chat/get-new-messages/{conversation_id}/{last_message_id}
  3. Displays new messages to user
  4. Updates last message ID

​
Viewing Status

The conversation tracks viewing status:
  • sender_viewed: Set to “1” when sender sends a new message
  • receiver_viewed: Set to “1” when receiver sends a new message
This allows showing unread message indicators in the UI.

​
Email Notifications

When a new conversation is created, an email is sent to the seller containing:
  • Sender’s name
  • Initial message content
  • Link to view conversation (for admin or seller dashboard)
Email sending failures are silently caught to prevent conversation creation from failing.

​
Best Practices

  1. Polling: Poll for new messages every 5-10 seconds for active conversations
  2. Caching: Cache conversation list locally and refresh periodically
  3. Pagination: Load older messages on-demand when user scrolls up
  4. Real-time: Consider implementing WebSocket for true real-time messaging
  5. Notifications: Send push notifications when new messages arrive

​
Limitations

  • Messages are text-only (no attachments in current version)
  • One conversation per product per customer-seller pair
  • Conversations cannot be deleted by users
  • No group conversations (only 1-to-1)

Build docs developers (and LLMs) love

Get started for freeTalk to us