Stream Chat Python Client

Common errors

• StreamChatAPIException: Authentication Error: Invalid credentials provided for StreamChat.

  cause The API Key or API Secret provided during `StreamChat` client initialization is incorrect or missing.
  fix Double-check your `STREAM_API_KEY` and `STREAM_API_SECRET` in your environment variables or code. Ensure they match the credentials found in your Stream Dashboard (https://getstream.io/dashboard/). Verify there are no leading/trailing spaces or typos.

• StreamChatAPIException: GetOrCreateChannel failed with error: "either data.created_by or data.created_by_id must be provided when using server side auth."

  cause When creating a channel using server-side authentication (i.e., with an API Secret), the `created_by` or `created_by_id` field is missing in the channel creation data.
  fix Ensure that the `create()` method for a channel is called with a `created_by_id` parameter, which specifies the user creating the channel. Example: `channel.create(created_by_id='your-user-id')`.

• StreamChatAPIException: Channel with given ID does not exist

  cause An operation was attempted on a channel (e.g., `channel.watch()`, `channel.send_message()`) that has not yet been created or initialized on the Stream platform.
  fix Before performing operations on a channel, ensure it has been properly created or retrieved. Call `channel.create(created_by_id='...')` to create the channel, or use `client.query_channels(...)` to retrieve existing ones.

Warnings

• breaking The `stream-chat` library is in maintenance mode. While it continues to receive critical updates, new projects are strongly advised to use the newer `getstream` Python SDK (`pip install getstream`). The `getstream` library is the actively developed, full-product SDK covering Chat, Video, Moderation, and Feeds.
  Fix: For new projects, install and use `getstream` instead: `pip install getstream`. Refer to the official Stream documentation for migration guides if moving an existing project.
• gotcha As of v4.0, API responses are instances of `StreamResponse`, which inherits from `dict`. While backward compatible (you can access data like a dictionary), it also provides additional methods like `.rate_limit()`, `.headers()`, and `.status_code()` for enhanced metadata access. Unexpected type checks might fail if only `dict` is assumed.
  Fix: Access response data as you would with a dictionary, but be aware of the `StreamResponse` type for additional methods. Example: `resp = client.call_api(...); print(resp.rate_limit()); data = resp['some_key']`.
• gotcha Do not rely on parsing error messages for business logic. Error messages are subject to change and may vary. Always use HTTP status codes and Stream's internal error codes for robust error handling.
  Fix: Implement error handling based on `resp.status_code()` and the error codes provided in the response body, rather than string matching against error messages.

Install

• pip install stream-chat Install stable version

Imports

• StreamChat

  from stream_chat import StreamChat

Quickstart

Initializes the Stream Chat client, upserts a user, generates a user token for client-side authentication, creates or retrieves a channel, and sends a message to it. Ensure `STREAM_API_KEY`, `STREAM_API_SECRET`, and `STREAM_USER_ID` are set as environment variables or replaced with actual values.

import os
from stream_chat import StreamChat

# Initialize the client with your API Key and Secret
# Get these from your Stream Dashboard: https://getstream.io/dashboard/
STREAM_API_KEY = os.environ.get('STREAM_API_KEY', 'YOUR_STREAM_API_KEY')
STREAM_API_SECRET = os.environ.get('STREAM_API_SECRET', 'YOUR_STREAM_API_SECRET')
STREAM_USER_ID = os.environ.get('STREAM_USER_ID', 'test_user_id')

if not all([STREAM_API_KEY, STREAM_API_SECRET]):
    raise ValueError("STREAM_API_KEY and STREAM_API_SECRET environment variables must be set.")

client = StreamChat(api_key=STREAM_API_KEY, api_secret=STREAM_API_SECRET)

# Create/update a user
user_data = {"id": STREAM_USER_ID, "name": "Test User"}
client.upsert_user(user_data)
print(f"User '{STREAM_USER_ID}' upserted.")

# Create a user token for client-side authentication (e.g., in a frontend app)
token = client.create_token(STREAM_USER_ID)
print(f"Generated user token: {token}")

# Create a channel
channel_id = "general"
channel_type = "messaging"
channel = client.channel(channel_type, channel_id)
channel.create(STREAM_USER_ID)
print(f"Channel '{channel_type}:{channel_id}' created/initialized.")

# Send a message to the channel
message_data = {"text": "Hello from the Python client!"}
channel.send_message(message_data, STREAM_USER_ID)
print("Message sent!")