←back to docs

Conversations

Overview of what conversations are and how they work. Learn how to build build your own conversation flow using the ChatBotKit API.

A conversation refers to the interaction between a user and a chatbot. It include exchanges of text forms of communication. Conversations have associated backstories, datasets and skillsets. The backstory defines the overall personality and ability of the chatbot. The datasets and skillsets specify specific information and actions the chatbot have access to. During a conversation, the chatbot may use both datasets and skillsets to serve the user.

Conversations can be created in multiple ways. You can directly create them via the ChatBotKit platform, or you can use integrations such as Slack or directly via the API. As a general rule of the thumb, when you interact with a chatbot, you are creating a conversation.

How to create a Conversation

Follow these instructions to create a new conversation from ChatBotKit web interface.

  1. Got to "Conversations" from the navigation bar.
  2. Click "Create Conversation" button.
  3. Select the preferred dataset and skillset and provide the chatbot backstory.
  4. Click the "Send" button.

Conversation Messages

The key component of a conversation is the message. Messages can be of various types, but the most common ones are the "user" message and the "bot" message type. The "user" message type are all chat messages submitted by the user, while the "bot" message type are all chatbot's response. When you interact with a chatbot, you are building a list of conversation messages.

It's important to note that chatbot conversations can be complex and dynamic, depending on the needs of the user and the capabilities of the chatbot. ChatBotKit provides various tools and resources to help you create and manage chatbot conversations, including adding context information, supplying inline instructions and responding with actions.

Now that the conversation is started you can engage the chatbot in a completely natural way. Ask questions and converse as you would normally.

Conversation flow

Conversation flow refers to the sequence of interactions between a user and a chatbot during a conversation. It typically follows a simple pattern, where the conversation is initiated, the user sends a message, and the chatbot responds with a message. However, conversation flow can also be more complex, depending on the capabilities and needs of the chatbot and the user. For example, the chatbot may ask additional questions to gather more context or provide multiple responses to break up the back-and-forth nature of the conversation.

As a developer, you can use tools and resources provided by ChatBotKit to create and manage chatbot conversations, including adding context information and inline instructions.

Basic Conversation Flow

Consider the following example which describes the basic conversation flow which is entirely structured around the ChatBotKit API. Note that in this case the APP acts as a proxy / interface between the User and ChatBotKit.

Let's go over this diagram step by step.

  1. The user initiates a conversation with the app.
  2. The app sends a request to ChatBotKit to create a conversation.
  3. ChatBotKit responds with a unique conversation id.
  4. The user sends a message to the app saying "Hi there".
  5. The app forwards this message to the ChatBotKit by using the conversation/{conversationId}/send endpoint.
  6. The app requests the next message in the conversation by calling the conversation/{conversationId}/receive ChatBotKit API endpoint.
  7. ChatBotKit responds with a object containing the message id and the text "Hello! how can I help?".
  8. The app passes this message on to the user.

Session Conversation Flow

In the basic conversation flow example we had to develop our own backend to forward the messages between the chatbot and the user. In this example, we use the conversation session feature to shortcut the process and make it easier to develop our chatbot.

  1. The user starts a conversation with the app.
  2. The app sends a request to the ChatBotKit to create a conversation.
  3. The ChatBotKit responds with a conversation id.
  4. The app sends a request to the ChatBotKit to create a conversation token.
  5. The ChatBotKit responds with a token.
  6. The user sends the text message "Hi there" to the ChatBotKit with the conversation id and the token.
  7. The user requests to receive a message from the ChatBotKit.
  8. The ChatBotKit responds with a message id and the text "Hello! how can I help?".

Notice that once the conversation and the conversation session are created, the entire conversation flow occurs directly between the User and ChatBotKit. While the number of initial steps are the same subsequent steps will be a lot less and faster.

Basic Conversation Flow in Code

In this example let's see how to use the ChatBotKit API and JavaScript async to initiate and interact with a chatbot:

// Initiate conversation through API

const conversation = await chatbotkit.startConversation({
  backstory: 'my_backstory',
  datasetId: 'my_dataset',
  skillsetId: 'my_skillset',
})

// Send initial message to chatbot through API

conversation.sendMessage({
  message: 'Hello, chatbot!',
})

const { text } = await conversation.receiveMessage()

console.log(text)

// Use a prompt to receive additional messages from the user and send them to the chatbot

while (true) {
  const message = await prompt('Enter a message:')

  conversation.sendMessage({
    message: 'Hello, chatbot!',
  })

  const { text } = await conversation.receiveMessage()

  console.log(text)
}

Let's go over this code step by step.

  1. The conversation is initiated through the startConversation method.
  2. The startConversation method takes optional parameters backstory, datasetId, and skillsetId.
  3. The user sends a message to the chatbot using the sendMessage method.
  4. The chatbot's response is received and stored in the text variable using the receive method.
  5. The conversation continues using a prompt to receive additional messages from the user.
  6. The additional messages from the user are sent to the chatbot through the sendMessage method.
  7. The chatbot's response is received and logged to the console using the receive method.
  8. This process continues until the conversation is ended.

This is of course just the beginning, as the conversation flow can be fully customized to fit every need. Using the ChatBotKit API, developers can create and manage chatbot conversations in a variety of ways, including adding context information, supplying inline instructions, and responding with actions.

Summary

To summarize, chatbot conversations are the interactions between a user and a chatbot. They can include exchanges of text, voice, or other forms of communication, and can be created in multiple ways. Messages are the key component of a conversation, and ChatBotKit provides various tools and resources to help you create and manage chatbot conversations.