Python library and CLI for monitoring Chaturbate Events API. Real-time event tracking with automatic error handling and optional InfluxDB integration.
- Real-time event monitoring - Chat messages, tips, room status changes, and user interactions
- Robust error handling - Automatic retries with exponential backoff and connection recovery
- Structured data output - Clean event formatting with type-safe models
- Database integration - Optional InfluxDB support for analytics and time-series data
- Flexible configuration - Environment variables, CLI options, or programmatic setup
uv pip install chaturbate-poller
pip install chaturbate-poller
uvx chaturbate_poller start
Generate your API token at https://chaturbate.com/statsapi/authtoken/ with "Events API" permission.
# Direct credentials
chaturbate_poller start --username your_username --token your_token
# Testbed environment
chaturbate_poller start --testbed --verbose
# Environment configuration
chaturbate_poller start
Create a .env
file in your project root:
CB_USERNAME="your_chaturbate_username"
CB_TOKEN="your_chaturbate_token"
# Optional InfluxDB configuration
INFLUXDB_URL="http://influxdb:8086"
INFLUXDB_TOKEN="your_influxdb_token"
INFLUXDB_ORG="chaturbate-poller"
INFLUXDB_BUCKET="events"
chaturbate_poller start [OPTIONS]
Key options:
-
--username TEXT
- Chaturbate username -
--token TEXT
- API token -
--timeout FLOAT
- Request timeout in seconds (default: 10.0) -
--database
- Enable InfluxDB integration -
--testbed
- Use testbed environment -
--verbose
- Enable detailed logging
docker run -e CB_USERNAME="username" -e CB_TOKEN="token" \
ghcr.io/mountaingod2/chaturbate_poller:latest --verbose
cp .env.example .env
# Configure credentials in .env
docker-compose up -d
import asyncio
from chaturbate_poller import ChaturbateClient
async def main():
async with ChaturbateClient("username", "token") as client:
url = None
while True:
response = await client.fetch_events(url)
for event in response.events:
print(f"Event: {event.method}")
print(event.model_dump_json(indent=2))
url = response.next_url
asyncio.run(main())
from chaturbate_poller import ChaturbateClient, format_message
async def process_events():
async with ChaturbateClient("username", "token") as client:
url = None
while True:
response = await client.fetch_events(url)
for event in response.events:
if event.method == "tip":
amount = event.object.tip.tokens
user = event.object.user.username
print(f"Tip: {user} -> {amount} tokens")
elif event.method == "chatMessage":
message = format_message(event)
print(f"Chat: {message}")
url = response.next_url
Enable with --database
flag to store events for analytics. See sample queries for data analysis examples.
git clone https://github.com/MountainGod2/chaturbate_poller.git
cd chaturbate_poller
uv sync --all-extras
uv run pytest
Pull requests welcome. Fork the repository, create a feature branch, add tests, and submit a PR.