Guide to Stateless and Stateful Interactions

In this guide, we will explore the two main ways to interact with the ChatBotKit API: stateless and stateful modes. Additionally, we will cover how to stream responses in real time and how to use the Triggers feature to enhance your chatbot workflows.

Prerequisites

Install the ChatBotKit Node.js SDK and set your API secret:

Stateless Interaction

In stateless mode, no conversation state is maintained by the API, meaning each interaction is independent and does not retain any previous context or information. This requires you to submit all necessary messages and relevant data with every single interaction, ensuring the API can process the request accurately without relying on past interactions.

Here's an example on how you can achieve this effectively using the ChatBotKit Node.js SDK, which provides the tools and methods needed for seamless integration:

Example

In this example:

• An array of messages is created and passed to the complete method of the conversation object.
• The API generates the next message, which is then added to the array.
• This way, you can keep the entire conversation in memory and pass all relevant details during each interaction.

Stateful Interaction

In stateful mode, the API maintains the conversation state for you, meaning it keeps track of the context and previous interactions. This allows you to focus on passing only the necessary information for the current request without worrying about the entire conversation history.

Example

In this example:

• A new conversation is created using the create method.
• The conversationId is used to maintain the state for subsequent messages.
• You only need to pass the conversationId and the new message text to continue the conversation.

Streaming Responses

For a more responsive user experience, you can stream the bot's reply token-by-token using the stream option. This is useful for displaying output as it is generated rather than waiting for the full response.

Example

In this example:

• Passing stream: true returns an async iterable of events.
• Events of type token contain individual text fragments as they arrive.
• The loop ends when the stream is complete.

Using Triggers

The Triggers feature in ChatBotKit allows you to send events and information to your bots, enabling powerful workflows and enhanced performance. A trigger functions similarly to a webhook. You can call it from any other place and pass in an input message. The state/session is maintained automatically if you pass a session id or contact parameter.

Example Using curl

In this example:

• The session parameter ensures the state is maintained for a unique user session.

Alternatively, you can pass contact details to maintain the state:

In this example:

• The state is maintained because the contact information is provided.
• Any subsequent trigger call with the same contact.email will continue the same conversation thread.

For more detailed information, you can refer to the ChatBotKit Trigger documentation.

Conclusion

By using these methods and techniques, you can effectively manage conversations and enhance your chatbot's capabilities with ChatBotKit. Stateless mode gives you full control over the conversation history in your own application, while stateful mode lets ChatBotKit manage it automatically. Streaming responses make your application feel fast and interactive, and Triggers allow you to build event-driven workflows that connect your bots to external systems.