> ## 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 Quickstart: Build and Send Your First Bot Message

> Follow this step-by-step guide to sign up, authenticate, create a bot, and send your first conversation message with the Botsify API.

This guide walks you through everything you need to go from zero to a live, responding bot using the Botsify API. By the end you'll have authenticated credentials, a bot, and a completed conversation — all driven through API calls you can automate or integrate into your own application.

**1. Sign up or log in**

If you don't already have a Botsify account, go to [app.botsify.com](https://app.botsify.com) and create one. The free tier is sufficient to follow this guide.

Once your account is active, note the email address and password you used — you'll need them in the next step to obtain API credentials.

> [!TIP]
>
> You can explore the visual bot builder in the dashboard at any time alongside the API. The two interfaces share the same underlying data, so changes you make via the API are immediately visible in the dashboard and vice versa.

**2. Authenticate and get your access token**

All Botsify API requests require authentication. The quickest way to get started is to exchange your email and password for an access token via the login endpoint.

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "yourpassword",
    "agentic-login": true
  }'
```

A successful response returns your credentials:

```json theme={null}
{
  "access_token": "eyJ...",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "token_type": "Bearer"
}
```

Save the `access_token` — you'll pass it as a `Bearer` token in the `Authorization` header for every subsequent request. The `client_id` and `client_secret` are used for OAuth2 flows; see the [Authentication](/authentication.md) page for details.

> [!NOTE]
>
> Treat your `access_token`, `client_id`, and `client_secret` like passwords. Never commit them to source control or expose them in client-side code.

**3. Create your first bot**

With your access token in hand, create a new bot. You choose a display name and an agent type — `chatbot`, `agent`, or `voice`. For this quickstart, use `agent` to get full AI capabilities.

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/create-bot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "bot_name": "Support agent",
    "agent_type": "agent"
  }'
```

The response includes a `bot_key` and a `bot_id` that uniquely identify your new bot:

```json theme={null}
{
  "bot_id": "bot_abc123",
  "bot_key": "bk_xxxxxxxxxxxxxxxx",
  "bot_name": "Support agent",
  "agent_type": "agent"
}
```

Copy the `bot_key` — it's the primary identifier you'll use when sending messages to this bot.

> [!NOTE]
>
> The `agent_type` field accepts three values: `chatbot` for structured flow-based bots, `agent` for fully AI-driven agents, and `voice` for voice-enabled bots. You can't change the type after creation, so choose carefully.

**4. Send your first conversation message**

Now send a message to your bot using the `/converse` endpoint. Each user is identified by a `fbId` — a string you define that uniquely represents a user in your system (a user ID, session token, or any opaque identifier works fine).

```bash theme={null}
curl -X POST https://app.botsify.com/api/v1/converse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "bot_key": "bk_xxxxxxxxxxxxxxxx",
    "fbId": "user-123",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'
```

The bot processes the message and returns a response:

```json theme={null}
{
  "reply": "Hi there! How can I help you today?",
  "fbId": "user-123",
  "conversation_id": "conv_xyz789"
}
```

Every subsequent message you send with the same `bot_key` and `fbId` pair is treated as a continuation of the same conversation, so the bot maintains context across turns automatically.

> [!TIP]
>
> If you want to see responses stream in token-by-token — ideal for building chat UIs — use the `/api/v1/converse/stream` endpoint with the same request body. It returns a server-sent event (SSE) stream instead of a single JSON payload.

## What's Next?

You've authenticated, created a bot, and had a live conversation through the API. Here are some natural next steps:

> **[Authentication](/authentication.md)**
>
> Explore OAuth2 and API key auth methods for different integration patterns.

> **[Agent Versions](/concepts/agent-versions.md)**
>
> Learn how to version your agent configuration for safe iteration.

> **[User Attributes](/concepts/user-attributes.md)**
>
> Attach custom data to users for personalized conversations.


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