Skip to content

Bot Platform API Overview

This document provides a high-level overview of the Bot Platform API surface for conversations, sessions, channels, and webhooks. It is written for architects and engineers integrating with the Bot Platform.

The Bot Platform provides AI-powered conversational interfaces across multiple channels (Slack, Teams, web chat, custom). This is a conceptual overview—concrete OpenAPI/Swagger documentation lives in the Bot Platform product repository.

Note

This is a conceptual overview of the Bot Platform API. Concrete OpenAPI/Swagger documentation with exact endpoints, request/response schemas, and authentication details lives in the Bot Platform product repository.

API Surface at a Glance

The Bot Platform API provides endpoints for:

  • Conversations - Managing conversations and sessions
  • Messages - Sending and receiving messages
  • Channels - Channel management and configuration
  • Webhooks - Webhook endpoints for external channels
  • Analytics - Conversation analytics and metrics

Authentication and Authorization

Authentication Methods

  • OAuth2/OIDC - Standard OAuth2 client credentials flow
  • API Keys - Service API keys for programmatic access
  • Channel-Specific Auth - Channel-specific authentication (Slack, Teams, etc.)

Authorization

  • Tenant Isolation - All operations are scoped to tenants
  • Channel Access - Channel-specific access control
  • Conversation Access - Conversation-level access control

See: Identity Platform API Overview for authentication details.

Main Resource Groups

Resource Group Examples Notes
Conversations /conversations, /conversations/{id}, /conversations/{id}/messages Conversation management
Sessions /sessions, /sessions/{id}, /sessions/{id}/context Session management
Channels /channels, /channels/{id}, /channels/{id}/config Channel configuration
Webhooks /webhooks, /webhooks/{id} Webhook endpoints
Analytics /analytics/conversations, /analytics/metrics Conversation analytics

Common Usage Patterns

Pattern 1: Frontend → Bot API → Channels → Responses

Steps:

  1. Frontend sends message to Bot API
  2. Bot API processes message
  3. Bot API routes to appropriate channel
  4. Channel delivers message
  5. Bot API receives response
  6. Bot API sends response to frontend

Example Flow: 

POST /api/v1/conversations/{conversationId}/messages
{
  "channelId": "channel-123",
  "message": "Hello, bot!",
  "userId": "user-456",
  "tenantId": "tenant-123"
}

Response: {
  "messageId": "msg-789",
  "response": "Hello! How can I help you?",
  "timestamp": "2026-01-01T10:30:00Z"
}

Pattern 2: External Channel → Webhook → Bot API

Steps: 1. External channel (Slack, Teams) sends webhook 2. Bot API receives webhook 3. Bot API processes message 4. Bot API generates response 5. Bot API sends response to channel

Example Flow: 

POST /api/v1/webhooks/slack
{
  "event": {
    "type": "message",
    "text": "Hello, bot!",
    "user": "user-123",
    "channel": "channel-456"
  }
}

Bot API processes and responds via Slack API

Pattern 3: Conversation Management

Steps: 1. Create conversation 2. Send messages 3. Manage session context 4. Retrieve conversation history 5. Close conversation

Example Flow: 

POST /api/v1/conversations
{
  "channelId": "channel-123",
  "userId": "user-456",
  "tenantId": "tenant-123"
}

POST /api/v1/conversations/{id}/messages
GET /api/v1/conversations/{id}/history
DELETE /api/v1/conversations/{id}

Error Handling and Status Codes

Standard HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request (e.g., invalid message format)
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "CHANNEL_NOT_FOUND",
    "message": "Channel with ID 'channel-123' not found",
    "details": {
      "channelId": "channel-123",
      "tenantId": "tenant-123"
    }
  }
}

Versioning and Compatibility

API Versioning

  • URL Versioning - /api/v1/, /api/v2/, etc.
  • Message Format Versioning - Version message formats
  • Backward Compatibility - Maintain backward compatibility within major versions

Compatibility

  • Channel Adapters - Channel-specific adapters (Slack, Teams, etc.)
  • Message Format - Standard message format
  • Webhook Payloads - Versioned webhook payloads

Tip

Best Practices: 1. Handle channel-specific formats 2. Manage conversation context 3. Handle webhook validation 4. Implement rate limiting 5. Monitor conversation metrics