--- title: Conversations description: Overview of what conversations are and how they work. Learn how to manage conversations and build your own conversation flow using the ChatBotKit API. tags: - chatbot - conversational ai - interaction - text communication - backstory - datasets - ChatBotKit - integration - API category: Objects --- A conversation is the interaction between a user and a chatbot. It consists of a sequence of messages exchanged in real time or over multiple sessions. Each conversation can have an associated bot, dataset, skillset, and contact, which together define what the bot knows, what it can do, and who it is talking to. Conversations can be created in multiple ways: directly from the ChatBotKit dashboard, through integrations such as the AI Widget, Slack, Discord, Messenger, WhatsApp, Telegram, and others, through [Tasks](https://chatbotkit.com/docs/tasks) that your AI agents run automatically, or directly via the [API](https://chatbotkit.com/docs/api). As a general rule, whenever a user interacts with a chatbot, a conversation is being created. ## Managing Conversations The Conversations dashboard lets you view and search all conversations in your account. Conversations appear in reverse chronological order. You can filter the list by integration - for example, see only conversations that came in through a specific Slack or widget integration - or by contact to see all interactions with a particular person. Clicking a conversation opens its detail page, which shows the full message history, the resources the conversation is connected to, and configuration settings you can edit. ## Conversation Details Each conversation detail page shows all resources associated with that conversation: - **Messages** - The full exchange between the user and the bot, with the ability to continue or review the conversation - **Attachments** - Files uploaded to the conversation, with quick access to download each attachment - **Bot** - The bot that handled the conversation, with links to the bot's dataset and skillset - **Dataset** - The knowledge base directly attached to the conversation (if set independently of the bot) - **Skillset** - The skillset directly attached to the conversation (if set independently of the bot) - **Contact** - The person linked to this conversation, with quick access to their profile and other related conversations - **Task** - The scheduled task that triggered this conversation, if it was initiated by an automated task You can also edit the conversation's **name** and **description**, and set custom **meta** fields under Advanced Options for tracking or workflow purposes. ## Conversation Messages The key component of a conversation is the message. Messages can be of two main types: **user** messages (submitted by the person) and **bot** messages (the chatbot's responses). As the conversation progresses, these messages accumulate into a full transcript. Conversations can be complex and dynamic. The bot uses its associated backstory, datasets, and skillsets to generate relevant responses. ChatBotKit provides tools to add context, supply inline instructions, and trigger actions during a conversation. ## 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 bot may ask additional questions to gather more context or provide multiple responses to break up the back-and-forth nature of the conversation. ### 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. `````mermaid sequenceDiagram autonumber actor User User->>APP: start conversation APP->>ChatBotKit: conversation/create ChatBotKit->>APP: {conversationId} User->>APP: "Hi there" APP->>ChatBotKit: conversation/{conversationId}/send "Hi there" APP->>ChatBotKit: conversation/{conversationId}/receive ChatBotKit->>APP: "Hello! how can I help?" APP->>User: "Hello! How can I help?" ````` Let's go over this diagram step by step. 1. The user initiates a conversation with an 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. Both send and receive operations are often used together in what is known as a completion. Thus when using ChatBotKit most API/SDK calls make use of the `conversation/{conversationId}/complete` method. ### 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. `````mermaid sequenceDiagram autonumber actor User User->>APP: start conversation APP->>ChatBotKit: conversation/create ChatBotKit->>APP: {conversationId} APP->>ChatBotKit: conversation/{conversationId}/session/create ChatBotKit->>APP: {token} User->>ChatBotKit: conversation/{conversationId}/send "Hi there" {token} User->>ChatBotKit: conversation/{conversationId}/receive {token} ChatBotKit->>User: "Hello! how can I help?" ````` 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. ## Summary Conversations are the record of every interaction between users and your bots. You can review them from the dashboard, see which resources were involved, follow up through linked contacts and tasks, and build custom workflows on top of them using the API or SDKs.