Bot Sessions

Bot sessions are the secure gateway for enabling conversations with your bots in user-facing applications. Each session generates a time-limited authentication token that grants controlled access to bot interactions without requiring users to have full API credentials. This security model protects your API keys while enabling seamless conversational experiences.

Creating Bot Sessions

Creating a bot session establishes a secure, time-limited way to interact with your bots through conversations. The session generates an authentication token that allows users to send messages and receive responses from the bot without requiring full API credentials. This is essential for embedding bots in applications, websites, or third-party platforms.

When you create a bot session, you establish a conversation context that persists throughout the session duration. The session includes the bot's configuration, connected resources like datasets and skillsets, and any initial messages you want to include. The returned session token authenticates subsequent conversation API calls, enabling secure real-time interactions.

The session duration determines how long the authentication token remains valid, with a minimum of 30 minutes and maximum of 24 hours. Longer durations are useful for persistent chat widgets or applications where users might return to continue conversations, while shorter durations provide better security for sensitive use cases.

Including contact information when creating a session associates the conversation with a specific user, enabling features like conversation history, user tracking, and personalized responses. The contact data can include name, email, and phone number, which helps with analytics and follow-up.

You can optionally include initial messages when creating the session. This is useful for pre-populating conversation context, simulating previous interactions, or starting the conversation with specific information. Only user-type messages are allowed in the initial message array to prevent potential manipulation of bot responses.

The response includes the conversation ID, session token, token expiration time, and any processed initial messages. Use the session token for all subsequent conversation API calls to send messages and receive bot responses. The conversation ID allows you to retrieve conversation history or perform other conversation-related operations.

Bot sessions respect visibility settings - public bots can create sessions for any user, while private bots require the session creator to be the bot owner. This enables flexible deployment scenarios from open chatbots to restricted internal tools.

Security Note: Session tokens should be treated as sensitive credentials and transmitted securely. They grant access to bot conversations for the specified duration, so implement appropriate token management and storage practices in your applications.