Chat Endpoint

The chat endpoint powers the conversational AI feature, allowing users to ask questions about any article processed by FAQSIR.

POST /chat

Sends a user message and receives an AI-generated response contextualised to the article content. The chat maintains conversation history within a session, allowing follow-up questions and natural dialogue.

Request

curl -X POST https://faqsir.com/api/chat \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "message": "What are the key risks mentioned in this article?",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "source_id": "9e2f1a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b"
  }'

Request Body

{
  "message": "What are the key risks mentioned in this article?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "source_id": "9e2f1a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b"
}

Field	Type	Required	Description
message	string	Yes	The user's question or message. Should be relevant to the article content.
session_id	string (UUID)	Yes	UUID identifying the chat session. Used to maintain conversation context across multiple messages. The widget persists this in localStorage.
source_id	string (UUID)	Yes	The source ID returned from the Source endpoint. Identifies which article the conversation is about.

Success Response

Status: 200 OK

{
  "id": "msg_456",
  "question": "What are the key risks mentioned in this article?",
  "answer": "The article highlights several key risks including...",
  "created_at": "2025-03-15T14:30:00.000000Z"
}

Field	Type	Description
id	string	Unique identifier for this chat interaction.
question	string	The original user message (echoed back).
answer	string	The AI-generated response text. May contain markdown formatting.
created_at	string	ISO 8601 timestamp of when the response was generated.

Error Responses

Status	Description	Response Body
401	Invalid or missing API token	{"message": "Unauthenticated."}
402	Subscription expired or missing	{"message": "Payment required."}
422	Validation error	{"message": "...", "errors": {...}}

Conversation Context

The chat endpoint maintains conversation context using the session_id parameter. Here's how it works:

• The API stores up to 20 previous messages per session, using them as context for generating responses.
• Both user messages and AI responses are included in the conversation history, enabling natural follow-up questions.
• Sessions are identified by the session_id UUID — the widget generates this automatically and persists it in localStorage.
• Starting a new session (new UUID) resets the conversation history.

Chat Modes

FAQSIR offers two chat modes depending on your subscription plan:

Basic Chat (Plus Plan)

Available on the Plus plan. The AI responds based on the extracted article content (summary paragraphs and FAQs). Responses are contextualised to the specific article the user is viewing. Chat is not available on the Starter plan.

Advanced Chat (Pro Plan)

Available on the Pro plan. In addition to the article content, the AI can search your site's Knowledge Base using vector search. This allows the AI to provide richer, more comprehensive answers by drawing on all of your uploaded knowledge documents.

Out-of-Scope Responses

The AI is designed to respond only to questions relevant to the article content. If a user asks an off-topic question, the API returns a polite message indicating the question is outside the scope of the article.

If the AI encounters an error during generation, it returns a standardised error message:

"Sorry, something went wrong. Please try again later."

Widget Error Handling

When the widget receives a non-2xx response, it displays an inline error message within the chat interface. There is no automatic retry — the user can send another message to try again.

Next Steps