Botsify Quickstart: Build and Send Your First Bot Message

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.

If you don’t already have a Botsify account, go to 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.

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.

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.

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:

{
  "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 page for details.

Treat your access_token, client_id, and client_secret like passwords. Never commit them to source control or expose them in client-side code.

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.

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:

{
  "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.

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.

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).

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:

{
  "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.

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

Explore OAuth2 and API key auth methods for different integration patterns.

Agent Versions

Learn how to version your agent configuration for safe iteration.

User Attributes

Attach custom data to users for personalized conversations.

Get Started

Core Concepts

Guides

Botsify Quickstart: Build and Send Your First Bot Message

What’s Next?

Authentication

Agent Versions

User Attributes

​What’s Next?

Authentication

Agent Versions

User Attributes

What’s Next?