back to tutorials

Guide to Stateless and Stateful Interactions

Learn how to use triggers for enhanced chatbot workflows. Examples provided for both stateless and stateful modes.

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 use the new Triggers feature to enhance your chatbot workflows.

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

const messages = [ { "type": "user", "text": "Hi there" } ]; const { text } = await cbk.conversation.complete(null, { messages: messages }); console.log(text); messages.push({ "type": "bot", "text": text });

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. Here’s a detailed example on how to effectively use the stateful interaction mode with the ChatBotKit Node SDK:

Example

const { id: conversationId } = await cbk.conversation.create({}); const { text } = await cbk.conversation.complete(conversationId, { text: "Hi there" }); console.log(text);

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.

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

curl '<https://api.chatbotkit.com/v1/integration/trigger/{triggerId}/event>' \ -H 'Authorization: Bearer {SECRET}' \ -H 'Content-Type: application/json' \ --data '{"session": "unique id for the current user session", "text":"Hi there"}'

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:

curl '<https://api.chatbotkit.com/v1/integration/trigger/{triggerId}/event>' \\ -H 'Authorization: Bearer {SECRET}' \\ -H 'Content-Type: application/json' \\ --data '{"contact": {"email": "user@abc.xy"}, "text":"Hi there"}'

In this example:

  • The state is maintained because the contact information is provided.

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. This not only improves the user experience but also ensures that your chatbot can handle a wider array of interactions and scenarios. With regular updates and tweaks, your chatbot will become more intuitive and efficient over time. Happy coding and best of luck on your chatbot development journey!