Skip to content

Get or Create Store Session

Get the current chat session for a store, or create one if it doesn't exist.

Endpoint

GET /v1/chat/store/session/

Authentication

Required: Store authentication token

Authorization: Token <store_token>

Request

No request body required.

Response

Success (200 OK)

Returns the existing or newly created chat session.

{
  "id": 1,
  "store_id": 5,
  "admin_id": null,
  "status": "open",
  "last_message_at": "2025-12-16T10:00:00Z",
  "created": "2025-12-16T10:00:00Z",
  "updated": "2025-12-16T10:00:00Z",
  "messages": []
}

Session with Admin Claimed

{
  "id": 1,
  "store_id": 5,
  "admin_id": 2,
  "status": "claimed",
  "last_message_at": "2025-12-16T10:15:00Z",
  "created": "2025-12-16T10:00:00Z",
  "updated": "2025-12-16T10:15:00Z",
  "store": {
    "id": 5,
    "name": "Tech Store",
    "logo_url": "https://example.com/logo.jpg",
    "email": "store@example.com"
  },
  "messages": [
    {
      "id": 123,
      "session_id": 1,
      "sender_type": "store",
      "sender_id": 5,
      "content": "Hello, I need help",
      "attachment_url": "",
      "attachment_type": "",
      "status": "sent",
      "created": "2025-12-16T10:10:00Z"
    },
    {
      "id": 124,
      "session_id": 1,
      "sender_type": "admin",
      "sender_id": 2,
      "content": "How can I help you?",
      "attachment_url": "",
      "attachment_type": "",
      "status": "sent",
      "created": "2025-12-16T10:15:00Z"
    }
  ]
}

Error (401 Unauthorized)

{
  "success": false,
  "message": "Unauthorized"
}

Response Fields

Field Type Description
id integer Unique session ID
store_id integer ID of the store
admin_id integer|null ID of assigned admin (null if unclaimed)
status string Session status: "open", "claimed", or "closed"
last_message_at string ISO 8601 timestamp of last message
created string ISO 8601 timestamp when session was created
updated string ISO 8601 timestamp of last update
closed_at string|null ISO 8601 timestamp when session was closed (if closed)
store object|null Store information (if enriched)
messages array Array of message objects (up to 200 most recent messages)

Message Object Fields

Field Type Description
id integer Message ID
session_id integer Session ID
sender_type string "store" or "admin"
sender_id integer ID of the sender
content string Message content
attachment_url string URL of attachment (if any)
attachment_type string Type of attachment (if any)
status string Message status: "sent", "delivered", or "read"
created string ISO 8601 timestamp when message was created

Session Status

  • open: Session created but not yet claimed by an admin
  • claimed: Session has been claimed by an admin
  • closed: Session has been closed

Example Usage

JavaScript/Fetch

async function getSession() {
  const response = await fetch('/v1/chat/store/session/', {
    method: 'GET',
    headers: {
      'Authorization': `Token ${storeToken}`
    }
  });

  const data = await response.json();

  console.log('Session ID:', data.id);
  console.log('Status:', data.status);
  console.log('Messages:', data.messages);
}

Axios

import axios from 'axios';

const getSession = async () => {
  try {
    const response = await axios.get('/v1/chat/store/session/', {
      headers: {
        'Authorization': `Token ${storeToken}`
      }
    });

    return response.data;
  } catch (error) {
    console.error('Failed to get session:', error);
  }
};

cURL

curl -X GET "http://localhost:8000/v1/chat/store/session/" \
  -H "Authorization: Token your_store_token_here"

Notes

  • This endpoint will automatically create a new session if the store doesn't have an active one
  • A store can only have one active session at a time (excluding closed sessions)
  • The messages array contains up to 200 most recent messages, ordered by creation time (ascending)
  • Use the WebSocket connection for real-time message updates
  • Message status field indicates delivery status: "sent", "delivered", or "read"