Skip to content

Claim Session (Admin)

Claim an open chat session to start handling it.

Endpoint

POST /v1/chat/admin/session/claim/

Authentication

Required: Admin authentication token

Authorization: Token <admin_token>

Request

Headers

Content-Type: application/json
Authorization: Token <admin_token>

Body

{
  "session_id": 5
}

Request Fields

Field Type Required Description
session_id integer Yes ID of the session to claim

Response

Success (200 OK)

{
  "id": 5,
  "store_id": 12,
  "admin_id": 2,
  "status": "claimed",
  "last_message_at": "2025-12-16T11:05:00Z",
  "created": "2025-12-16T11:00:00Z",
  "updated": "2025-12-16T11:20:00Z",
  "store": {
    "id": 12,
    "name": "Tech Store",
    "logo_url": "https://example.com/logo.jpg",
    "email": "store@example.com"
  }
}

Error (400 Bad Request)

Missing or invalid session_id: 

{
  "error": "Session already claimed or not found"
}

Error (401 Unauthorized)

{
  "error": "Unauthorized"
}

Response Fields

Field Type Description
id integer Unique session ID
store_id integer ID of the store
admin_id integer ID of the admin (you)
status string Now "claimed"
last_message_at string ISO 8601 timestamp of last message
created string ISO 8601 timestamp when session was created
updated string ISO 8601 timestamp (now updated)
store object Store information

What Happens When You Claim

  1. Session status changes from "open" to "claimed"
  2. Session admin_id is set to your admin ID
  3. Session moves from open sessions list to your "My Sessions" list
  4. Store receives admin_connected event via WebSocket
  5. All admins are notified via WebSocket that the session was claimed

Example Usage

JavaScript/Fetch

async function claimSession(sessionId) {
  const response = await fetch('/v1/chat/admin/session/claim/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Token ${adminToken}`
    },
    body: JSON.stringify({
      session_id: sessionId
    })
  });

  const data = await response.json();

  console.log('Session claimed:', data.id);
  console.log('Store:', data.store.name);
  return data;
}

Axios

import axios from 'axios';

const claimSession = async (sessionId) => {
  try {
    const response = await axios.post('/v1/chat/admin/session/claim/', 
      { session_id: sessionId },
      {
        headers: {
          'Authorization': `Token ${adminToken}`
        }
      }
    );

    return response.data;
  } catch (error) {
    if (error.response?.status === 409) {
      console.error('Session already claimed');
    } else {
      console.error('Failed to claim session:', error);
    }
  }
};

cURL

curl -X POST "http://localhost:8000/v1/chat/admin/session/claim/" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token your_admin_token_here" \
  -d '{
    "session_id": 5
  }'

Notes

  • Only "open" sessions (with admin_id=null) can be claimed
  • Once claimed, the session can only be accessed by the claiming admin
  • The store is notified via WebSocket that an admin has joined
  • All admins are notified via WebSocket that the session was claimed
  • After claiming, connect to the Admin WebSocket to receive real-time updates
  • Use Get Session to retrieve full message history

Typical Workflow

  1. Admin views Open Sessions
  2. Admin selects a session to handle
  3. Admin calls this endpoint to claim it
  4. Admin receives full message history
  5. Admin can now send messages and communicate with the store