ChatterBox

All-in-one API for Meeting Bots

Integrate your app or AI Agent with Zoom, Teams, and Google Meet to capture near real-time transcripts and meeting recordings

API Documentation

Last Updated: April 2025

The Bot API provides the capability to deploy bots into your Zoom or Google Meet meetings and receive near real-time transcripts of the meeting.

Client Libraries

We provide official client libraries to make integration easier:

Python Package

Install via pip:

pip install chatterbox-io
View on PyPI →

Node.js Package

Install via npm:

npm install @chatterboxio/bot
View on npm →

Authentication

The API uses JWT tokens for authentication. You can use either a permanent API token or generate temporary tokens for enhanced security.

Temporary Tokens

Temporary tokens provide a secure way to authenticate client-side applications without exposing your permanent API token. These tokens are short-lived and can be configured to expire after a specified duration.

Endpoint

  • POST https://bot.chatter-box.io/token

Required Headers

  • Content-Type: application/json
  • Authorization: Bearer token

Note: Use your permanent API token in the Authorization header to generate a temporary token.

Request Body

{
    "expiresIn": 3600
}

expiresIn: The duration in seconds for which the temporary token should be valid. Must be between 60 and 86400 seconds (1 minute to 24 hours). Defaults to 3600 seconds (1 hour) if not specified.

Response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
}

token: The generated temporary JWT token.

expiresIn: The duration in seconds for which the token is valid.

Best Practices

  • Generate temporary tokens on your server using your permanent API token
  • Use temporary tokens in client-side applications to avoid exposing your permanent API token
  • Set an appropriate expiration time based on your application's needs
  • Implement token refresh logic to generate new tokens before expiration

Deploying Bots

Endpoints

  • https://bot.chatter-box.io/join

Required Headers

  • Content-Type: application/json
  • Authorization: Bearer token

Note: Replace 'token' with your secret API access token.

Request Body

{
    "platform": "zoom",
    "meetingId": "1234567890",
    "meetingPassword": "Rks...1",
    "botName": "My Bot",
    "webhookUrl": "https://your-domain.com/webhook"
}

platform: The online conference platform. Accepted values: 'zoom', 'googlemeet'

meetingId: The ID of the Zoom ('###########') or Google Meet ('xxx-xxx-xxx') meeting.

meetingPassword: The password for the Zoom meeting (optional).

botName: The name of the bot (optional).

webhookUrl: URL to receive webhook events for session status (optional).

Response

{
    "sessionId": "04634659-cad2-454a-87f9-e983bd123456"
}

Receiving Transcripts

WebSocket Endpoints

  • https://ws.chatter-box.io

Query Parameters

  • auth: Your API token
  • sessionId: Session identifier from bot deployment

Event Types

Session Started Event

{
    "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
    "timestamp": 1724766459
}

Transcript Event

{
    "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
    "timeStart": 12345,
    "timeEnd": 12345,
    "speaker": "User Name",
    "text": "Transcript utterance"
}

Session Finished Event

{
    "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
    "timestamp": 1724766459
}

Post-Call Information

Endpoints

  • https://bot.chatter-box.io/session/{sessionId}

Required Headers

  • Content-Type: application/json
  • Authorization: Bearer token

Response

{ 
    "recordingLink": "url", 
    "startTimestamp": "2024-05-21T14:00:00Z", 
    "endTimestamp": "2024-05-21T15:00:00Z", 
    "transcript": [ 
        { 
            "timeStart": 12345,
            "timeEnd": 12345,
            "speaker": "User Name", 
            "text": "Transcript utterance" 
        }, 
        { 
            "timestamp": 12378, 
            "speaker": "Another User", 
            "text": "Another transcript utterance" 
        } 
    ]
}

Note: Recording link URL is valid for 5 minutes for security reasons.

Webhook Events

When a webhook URL is provided, the following events will be sent to your endpoint:

Session Started Webhook

{
    "type": "started",
    "payload": {
        "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
        "timestamp": 1724766459
    }
}

Transcript Webhook

{
    "type": "transcript",
    "payload": {
        "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
        "timeStart": 12345,
        "timeEnd": 12345,
        "speaker": "User Name",
        "text": "Transcript utterance"
    }
}

type: Always "transcript" for transcript events

sessionId: The unique identifier for the session

timeStart: Start timestamp of the utterance in milliseconds

timeEnd: End timestamp of the utterance in milliseconds

speaker: Name of the speaker

text: The transcribed text

Session Finished Webhook

{
    "type": "finished", 
    "payload": {
        "sessionId": "04634659-cad2-454a-87f9-e983bd123456",
        "timestamp": 1724766459,
        "recordingUrl": "https://signed-url-to-recording.mp4"
    }
}

Note: The recording URL in the finished webhook is valid for 5 minutes for security reasons.