API Reference

Build powerful integrations with the BotHero REST API. Simple, predictable, and developer-friendly.

Quick StartAuthenticationFull Docs

Base URL

https://api.bothero.ai/v1

All API requests must use HTTPS. HTTP requests will be rejected.

Authentication

Authenticate using Bearer tokens in the Authorization header. Get your API key from the dashboard.

Authorization: Bearer YOUR_API_KEY
Get your API key →

API Endpoints

Authentication

POST
/auth/login

Authenticate and get access token

POST
/auth/refresh

Refresh expired access token

POST
/auth/logout

Revoke access token

Bots

GET
/bots

List all bots

POST
/bots

Create a new bot

GET
/bots/:id

Get bot details

PUT
/bots/:id

Update bot configuration

DELETE
/bots/:id

Delete a bot

POST
/bots/:id/deploy

Deploy bot to Telegram

Messages

GET
/messages

List conversation messages

POST
/messages

Send a message

GET
/messages/:id

Get message details

POST
/messages/:id/handoff

Transfer to human agent

Analytics

GET
/analytics/overview

Get overview metrics

GET
/analytics/conversations

Conversation statistics

GET
/analytics/leads

Lead capture data

GET
/analytics/sentiment

Sentiment analysis

Code Examples

Create a Bot

cURL
curl -X POST https://api.bothero.ai/v1/bots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "telegram_token": "YOUR_TELEGRAM_TOKEN",
    "personality": "friendly and helpful"
  }'

Create a Bot

JavaScript
const response = await fetch('https://api.bothero.ai/v1/bots', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Support Bot',
    telegram_token: 'YOUR_TELEGRAM_TOKEN',
    personality: 'friendly and helpful'
  })
});

const bot = await response.json();

Create a Bot

Python
import requests

response = requests.post(
    'https://api.bothero.ai/v1/bots',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Support Bot',
        'telegram_token': 'YOUR_TELEGRAM_TOKEN',
        'personality': 'friendly and helpful'
    }
)

bot = response.json()

Rate Limits

100
requests per minute
10,000
requests per day

Enterprise customers can request higher rate limits. Contact sales for details.

Error Responses

The API uses standard HTTP response codes. Errors include a JSON body with details.

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: name",
    "field": "name"
  }
}
200Success
400Bad Request
401Unauthorized
404Not Found
429Rate Limited
500Server Error

Official SDKs Coming Soon

We're working on official SDKs for JavaScript, Python, Go, and PHP to make integration even easier.

JavaScriptPythonGoPHP

Need Help?

Check out our full documentation or contact support for assistance.

View Full DocsContact Support