> ## Documentation Index
> Fetch the complete documentation index at: https://botsify.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Botsify Bots and Agents: Types, Keys, and Lifecycle

> Understand the difference between chatbots, AI agents, and voice bots, and learn how bot_id, bot_key, and apikey work in your Botsify workspace.

In Botsify, a **bot** (or **agent**) is the core unit of your conversational deployment. It holds your AI configuration, chat flows, memory settings, identity instructions, and channel integrations — everything needed to have a coherent conversation with a user. Every bot has a unique identifier, an API key, and a type that determines how it processes and responds to messages.

***

## Agent Types

Botsify supports three agent types. You select the type when you create a bot, and it cannot be changed afterward, so it's worth understanding the differences before you start.

| Type | Best For | AI-Driven? | Voice Support? |
| - | - | - | - |
| `chatbot` | Structured flows, FAQ bots, guided interactions | Partially | No |
| `agent` | Autonomous multi-turn AI conversations, agentic API use | Yes | No |
| `voice` | Audio and voice-interface deployments | Yes | Yes |

> **Chatbot**
>
> Chatbots follow defined chat flows and decision trees. They are straightforward to configure in the visual builder and are ideal for predictable, structured interactions like onboarding sequences, FAQs, or lead capture forms.

> **AI Agent**
>
> Agents are fully AI-driven and reason over the full conversation context. They support named versions, long-term memory, identity and soul configuration, and the agentic REST API — making them the right choice for open-ended, intelligent conversations.

> **Voice Bot**
>
> Voice bots bring AI conversation capabilities to spoken audio interfaces. They share the same agent configuration primitives as AI agents and are optimized for voice channel deployments.

***

## Key Identifiers

Every bot in Botsify has three identifiers you'll encounter regularly:

**`bot_id`** — A unique identifier for the bot record. Used in platform management API calls such as updating configuration, managing versions, or deleting a bot.

**`bot_key`** — The primary identifier used when sending or receiving conversation messages. Pass `bot_key` in the request body of `/api/v1/converse` and related messaging endpoints to tell Botsify which bot should handle the conversation.

**`apikey`** (bot API key) — A secret key scoped to a specific bot. Used for bot-level operations such as managing user attributes and some conversation endpoints. Treat it like a password — do not expose it in client-side code.

> [!NOTE]
>
> The `bot_key` and `apikey` serve different purposes. The `bot_key` is a routing identifier (it tells the API which bot to talk to), while the `apikey` is an authentication credential (it proves you are authorized to act on that bot's behalf). Some endpoints accept one; others accept the other — check each endpoint's documentation.

***

## Workspace Organization

Your Botsify workspace can hold multiple bots. Bots are organized into two visibility scopes:

* **My Agents** — Bots you created. You have full administrative access: read, write, configure, delete.
* **Shared Agents** — Bots that have been shared with you by another workspace member. Access level depends on the permissions granted by the owner.

This separation makes it straightforward to collaborate on bots within a team without accidentally modifying each other's production agents.

***

## Bot Lifecycle

Every bot follows the same four-stage lifecycle from creation to live conversation:

**1. Create**

Create a bot by calling `POST /api/v1/create-bot` with a `bot_name` and `agent_type`, or use the Botsify dashboard. A `bot_id`, `bot_key`, and `apikey` are generated and returned.

**2. Configure**

Define the bot's behavior: set up chat flows, configure AI identity and memory, write system prompts, and optionally create named versions for safe iteration. Configuration can be done through the dashboard or the API.

**3. Deploy**

Connect the bot to one or more channels — your website widget, Facebook Messenger, or WhatsApp. Botsify handles the channel-specific protocol; your bot configuration stays the same regardless of channel.

**4. Converse**

Start sending messages via `POST /api/v1/converse` (or the streaming equivalents) using the bot's `bot_key` and a user identifier (`fbId`). Botsify maintains per-user conversation context automatically.

***

## Multi-Channel Support

A single Botsify bot can serve users across multiple channels simultaneously:

* **Web** — Embed the Botsify widget on any website, or drive conversations programmatically through the API.
* **Facebook Messenger** — Connect your Facebook Page to route Messenger conversations through your bot.
* **WhatsApp** — Integrate with WhatsApp Business to handle inbound and outbound WhatsApp messages.

You manage one bot configuration; Botsify routes messages from each channel through the same AI agent and conversation history.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.