AI Help and Support Chat API

All endpoints require the existing JWT bearer token and are served below /api/v1/.

AI chat is also available over WebSocket at:

wss://<host>/ws/support/ai-chat/?token=<ACCESS_TOKEN>

For local development without TLS, use:

ws://<host>/ws/support/ai-chat/?token=<ACCESS_TOKEN>

Flow

1. Create a chat session.
2. Send messages to the session.
3. Render the assistant answer, suggested actions, and cited FAQ articles.
4. If should_offer_ticket is true, ask the user whether they consent to creating a support ticket.
5. Call the ticket endpoint only after the user explicitly agrees.

The assistant cannot create a ticket by itself. The backend requires {"consent": true} and an existing AI-generated ticket draft.

Create a session

POST /api/v1/support/chat/sessions/

{
  "language": "en"
}

Send a message

POST /api/v1/support/chat/sessions/{session_id}/messages/

{
  "message": "My inventory is not syncing. What should I try?"
}

Important response fields:

{
  "resolved": false,
  "should_offer_ticket": true,
  "suggested_actions": ["Check your connection", "Refresh inventory"],
  "cited_articles": [
    {"id": 12, "slug": "inventory-sync", "title": "Inventory sync help"}
  ]
}

Read saved sessions

• GET /api/v1/support/chat/sessions/
• GET /api/v1/support/chat/sessions/{session_id}/

The detail endpoint returns the encrypted-at-rest conversation after it has been decrypted for its owning authenticated user.

Create a ticket after consent

POST /api/v1/support/chat/sessions/{session_id}/ticket/

{
  "consent": true
}

The user may optionally edit the draft before creation:

{
  "consent": true,
  "subject": "Inventory sync still failing",
  "description": "I followed the troubleshooting steps, but sync still fails.",
  "ticket_type": "technical",
  "priority": "high"
}

Sending consent: false never creates a ticket.

Configuration

OPENAI_API_KEY=...
SUPPORT_AI_MODEL=gpt-5.4-mini
SUPPORT_AI_REASONING_EFFORT=low
SUPPORT_AI_MAX_OUTPUT_TOKENS=1800
SUPPORT_AI_TIMEOUT_SECONDS=45

The integration uses the OpenAI Responses API with strict structured output, local conversation persistence, built-in verified StoreMate knowledge plus admin-managed FAQ retrieval, and store=false.

WebSocket protocol

Connect with the same SimpleJWT access token used for the REST API. After a successful connection the server sends:

{"type": "support.chat.ready", "data": {}}

Create a session:

{"type": "support.chat.sessions.create", "data": {"language": "en"}}

The server responds with:

{"type": "support.chat.session.created", "data": {"session": {}}}

List or fetch sessions:

{"type": "support.chat.sessions.list"}
{"type": "support.chat.sessions.get", "data": {"session_id": "<uuid>"}}

Send a message:

{
  "type": "support.chat.message.send",
  "data": {
    "session_id": "<uuid>",
    "message": "My inventory is not syncing. What should I try?"
  }
}

The server first confirms the saved user message:

{"type": "support.chat.message.saved", "data": {"session_id": "<uuid>", "message": {}}}

Then it sends the assistant reply:

{
  "type": "support.chat.reply",
  "data": {
    "session": {},
    "message": {},
    "resolved": false,
    "should_offer_ticket": false,
    "ticket_creation_available": false,
    "suggested_actions": [],
    "cited_articles": []
  }
}

Create a ticket after explicit consent:

{"type": "support.chat.ticket.create", "data": {"session_id": "<uuid>", "consent": true}}

Errors are sent without closing the socket:

{"type": "support.chat.error", "data": {"code": "empty_message", "message": "Message cannot be empty."}}