Create Widget Session

POST/v1/widget/sessions

Create a session token for embedding the interactive avatar widget.

What is a Widget Session?

A widget session is a secure, time-limited token that allows you to embed an interactive AI avatar widget into your website or application without exposing your API key. The session token provides secure authentication for the widget while maintaining control over where and how long the widget can be used.

Key Benefits:

Security: Session tokens prevent API key exposure in client-side code
Control: Restrict widget usage to specific domains and time periods
Flexibility: Enable or disable specific features (voice input, text input, knowledge base)
Best Practice: Recommended approach for production deployments

Request History

TIME	STATUS	USER AGENT
Make a request to see history.

0 Requests This Month

Request Body

The request body contains the agentic avatar ID and session configuration settings. All fields in the request body are required to create a valid widget session.

Field	Type	Description
agentic_avatar_id	string required	The unique identifier of the agentic avatar to use in the widget. This must be a valid agentic avatar ID from your account. The agentic avatar determines the avatar's appearance, voice, personality, and knowledge base integration.
settings	object required	Configuration object that controls session behavior, security, and available features. This includes session duration limits, domain restrictions, and feature toggles.

Settings Object

The settings object allows you to configure security, duration, and feature availability for the widget session. All fields within the settings object are optional, but recommended for production use.

Field	Type	Description
max_duration	integer optional	Maximum session duration in seconds. After this time, the session will expire and the widget will stop working. Common values: `3600` (1 hour), `7200` (2 hours), `86400` (24 hours). If not specified, a default duration is used.
allowed_domains	array optional	Array of allowed domain names where the widget can be embedded. This is a security feature that prevents unauthorized use of your session token. Include both the main domain and any subdomains (e.g., `["example.com", "app.example.com", "www.example.com"]`). If not specified, the widget can be embedded on any domain (not recommended for production).
features	object optional	Feature flags object that controls which interactive features are available in the widget. You can enable or disable voice input, text input, and knowledge base integration independently. If not specified, all features are enabled by default.

Features Object

The features object allows you to control which interactive capabilities are available to users in the widget. Each feature can be enabled or disabled independently based on your use case.

Field	Type	Description
voice_input	boolean optional	When `true`, users can interact with the avatar using voice input (microphone). When `false`, voice input is disabled. Default: `true`
text_input	boolean optional	When `true`, users can type messages to interact with the avatar. When `false`, text input is disabled. Default: `true`
knowledge_base	boolean optional	When `true`, the avatar can access and use information from the associated knowledge base (brain) to answer questions. When `false`, knowledge base integration is disabled. Default: `true`

Request Example

shell

curl -X POST https://api.konpro.ai/v1/widget/sessions \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentic_avatar_id": "3deccfb2-cf96-459c-8b69-f601d6767ea5",
    "settings": {
      "max_duration": 3600,
      "allowed_domains": ["example.com", "app.example.com"],
      "features": {
        "voice_input": true,
        "text_input": true,
        "knowledge_base": true
      }
    }
  }'

Response

Field	Type	Description
session_token	string	JWT token for authenticating the widget session
expires_at	string	ISO 8601 timestamp of when the session expires
widget_url	string	URL for embedding the widget (e.g., `https://widget.konpro.ai/embed`)
session_id	string	Unique identifier for the widget session

Sample Successful Response

json

{
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-01T01:00:00Z",
  "widget_url": "https://widget.konpro.ai/embed",
  "session_id": "session-789"
}

Notes

This endpoint requires authentication using the x-api-key header. Always keep your API key secure and never expose it in client-side code.
The agentic_avatar_id must be a valid agentic avatar ID from your account. You can create agentic avatars through the KonPro Studio or API.
Security Best Practice: Session tokens are JWT tokens that should be used securely on the client side. Never expose your API key directly in client-side code. Always generate session tokens on your backend server and pass them to your frontend.
The allowed_domains array restricts where the widget can be embedded for security purposes. This prevents unauthorized use of your session tokens. Always specify allowed domains in production.
The max_duration is specified in seconds (e.g., 3600 = 1 hour, 7200 = 2 hours, 86400 = 24 hours). Sessions automatically expire after this duration.
Session tokens are single-use or time-limited. Once a session expires, you'll need to create a new session token to continue using the widget.
You can retrieve session details using the Get Widget Session endpoint.
For error descriptions, see Error Responses.

Widget Integration Get Widget Session