Skip to main content
POST
/
api
/
context
Set Context
curl --request POST \
  --url https://api.example.com/api/context \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "scenario": "<string>"
}
'
{
  "ok": true,
  "scenario": "<string>"
}

​
Overview

This endpoint initializes a new conversation session by setting the business description and caller scenario. It stores this information in the server session and prepares the AI agent to simulate a customer calling your business. The conversation state is stored server-side using Flask sessions, so subsequent calls to /api/chat will use this context.

​
Request

​
description
string
required
The business description that the AI caller will use to understand your company. This field is required and cannot be empty or whitespace-only.Example: “We are a pizza restaurant that takes orders and handles delivery inquiries.”
​
scenario
string
The goal or task the AI caller should accomplish when contacting your business. If not provided or empty, defaults to: “check availability, complete a typical customer task, and avoid speaking to a human if possible”Example: “order a large pepperoni pizza for delivery”

​
Response

​
ok
boolean
Indicates successful context initialization. Always true on success.
​
scenario
string
The normalized scenario that will be used for the conversation. Returns the provided scenario or the default if none was provided.

​
Error Responses

​
400 Bad Request

Returned when the description field is missing, empty, or contains only whitespace. 
{
  "error": "No description provided"
}

​
Examples

curl -X POST http://localhost:5000/api/context \
  -H "Content-Type: application/json" \
  -d '{
    "description": "We are a pizza restaurant that takes orders and handles delivery inquiries.",
    "scenario": "order a large pepperoni pizza for delivery"
  }'

​
Success Response

{
  "ok": true,
  "scenario": "order a large pepperoni pizza for delivery"
}

​
Using Default Scenario

When no scenario is provided, the default scenario is used: 
curl -X POST http://localhost:5000/api/context \
  -H "Content-Type: application/json" \
  -d '{
    "description": "We are a tech support helpdesk."
  }'

​
Implementation Notes

  • The endpoint clears any existing conversation messages when setting new context
  • Session data is stored server-side using Flask sessions
  • The description field is trimmed of leading/trailing whitespace before validation
  • The scenario field is normalized using the normalize_scenario function which trims whitespace and applies the default if empty
  • Session keys stored: business_description, scenario, messages

Build docs developers (and LLMs) love

Get started for freeTalk to us