B

Blocktell Docs

API Reference

Complete API documentation to integrate Blocktell chatbots into your applications. Build custom experiences with our RESTful API.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Find your API key in your dashboard under Settings → API Keys

API Endpoints

POST/api/chatbot/query

Send a message to your chatbot and get an AI-powered response using vector search and GPT-4

Example Request

curl -X POST https://your-domain.com/api/chatbot/query \
  -H "Content-Type: application/json" \
  -d '{
    "message": "How do I integrate your chatbot?",
    "chatbotId": "your-chatbot-id",
    "sessionId": "optional-session-id",
    "mode": "productivity"
  }'

Example Response

{
  "response": "To integrate our chatbot, copy the embed code from your Settings → Embed tab...",
  "confidence": 0.92,
  "sources": ["https://docs.example.com/integration"],
  "sessionId": "sess_abc123",
  "responseTime": 847
}
POST/api/chatbot/query-stream

Get streaming responses from your chatbot (real-time response chunks)

Example Request

curl -X POST https://your-domain.com/api/chatbot/query-stream \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain your pricing plans",
    "chatbotId": "your-chatbot-id"
  }' \
  --no-buffer

Example Response

data: {"chunk": "Our pricing includes "}
data: {"chunk": "three tiers: Free (100 messages/month)"}
data: {"chunk": ", Pro ($29/month), and Enterprise..."}
data: [DONE]
GET/api/chatbots/[id]/stats

Get detailed analytics and usage statistics for a specific chatbot

Example Request

curl -X GET https://your-domain.com/api/chatbots/abc123/stats?userId=your-user-id \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Example Response

{
  "totalInteractions": 1247,
  "avgResponseTime": 1.2,
  "topQuestions": ["How to integrate?", "Pricing plans"],
  "satisfactionScore": 4.6,
  "monthlyTrend": [...]
}
GET/api/chatbots/[id]/settings

Retrieve chatbot configuration and settings

Example Request

curl -X GET https://your-domain.com/api/chatbots/abc123/settings?userId=your-user-id \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN"

Example Response

{
  "chatbot": {"id": "abc123", "name": "Support Bot"},
  "settings": {
    "welcomeMessage": "Hi! How can I help you today?",
    "suggestedQuestions": ["How do I get started?"],
    "theme": {"primaryColor": "#10b981", "position": "bottom-right"}
  }
}
PUT/api/chatbots/[id]/settings

Update chatbot configuration and appearance settings

Example Request

curl -X PUT https://your-domain.com/api/chatbots/abc123/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -d '{
    "userId": "your-user-id",
    "settings": {
      "welcomeMessage": "Welcome to our support center!",
      "theme": {"primaryColor": "#3b82f6"}
    }
  }'
GET/api/widget/config/[id]

Get public widget configuration (used by embed code)

Example Request

curl -X GET https://your-domain.com/api/widget/config/abc123

Example Response

{
  "id": "abc123",
  "name": "Support Bot",
  "domain": "example.com",
  "theme": {"primaryColor": "#10b981"},
  "isActive": true
}
POST/api/live-chat/message

Send a message in live chat session (agent or customer)

Example Request

curl -X POST https://your-domain.com/api/live-chat/message \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "live_abc123",
    "message": "I need help with billing",
    "senderType": "customer",
    "senderName": "John Doe"
  }'
PUT/api/live-chat/agent-status

Update agent availability status for live chat handoff

Example Request

curl -X PUT https://your-domain.com/api/live-chat/agent-status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN" \
  -d '{
    "agentId": "agent_123",
    "status": "available",
    "maxConcurrentChats": 3
  }'

Rate Limits

API requests are limited to prevent abuse and ensure fair usage:

  • • Free Plan: 100 requests per hour
  • • Pro Plan: 1,000 requests per hour
  • • Enterprise: Custom limits available

SDKs & Libraries

JavaScript/Node.js

Official SDK for JavaScript and Node.js applications

npm install @blocktell/sdk

Python

Python SDK for easy integration

pip install blocktell

PHP

PHP SDK for server-side integration

composer install blocktell/sdk