{"id":7760,"library":"stream-chat","title":"Stream Chat Python Client","description":"The `stream-chat` library is the official Python API client for Stream Chat, a service designed for building chat applications. It provides server-side access to the chat API endpoints. While actively maintained with critical fixes and requested features, it is currently in maintenance mode. New projects are strongly encouraged to use the newer, full-product `getstream` SDK for comprehensive Stream services, including Chat, Video, Moderation, and Feeds. The library typically sees regular minor releases to introduce new features and bug fixes.","status":"maintenance","version":"4.31.0","language":"en","source_language":"en","source_url":"https://github.com/GetStream/stream-chat-python","tags":["chat","realtime","api-client","communication","messaging"],"install":[{"cmd":"pip install stream-chat","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"StreamChat","correct":"from stream_chat import StreamChat"}],"quickstart":{"code":"import os\nfrom stream_chat import StreamChat\n\n# Initialize the client with your API Key and Secret\n# Get these from your Stream Dashboard: https://getstream.io/dashboard/\nSTREAM_API_KEY = os.environ.get('STREAM_API_KEY', 'YOUR_STREAM_API_KEY')\nSTREAM_API_SECRET = os.environ.get('STREAM_API_SECRET', 'YOUR_STREAM_API_SECRET')\nSTREAM_USER_ID = os.environ.get('STREAM_USER_ID', 'test_user_id')\n\nif not all([STREAM_API_KEY, STREAM_API_SECRET]):\n    raise ValueError(\"STREAM_API_KEY and STREAM_API_SECRET environment variables must be set.\")\n\nclient = StreamChat(api_key=STREAM_API_KEY, api_secret=STREAM_API_SECRET)\n\n# Create/update a user\nuser_data = {\"id\": STREAM_USER_ID, \"name\": \"Test User\"}\nclient.upsert_user(user_data)\nprint(f\"User '{STREAM_USER_ID}' upserted.\")\n\n# Create a user token for client-side authentication (e.g., in a frontend app)\ntoken = client.create_token(STREAM_USER_ID)\nprint(f\"Generated user token: {token}\")\n\n# Create a channel\nchannel_id = \"general\"\nchannel_type = \"messaging\"\nchannel = client.channel(channel_type, channel_id)\nchannel.create(STREAM_USER_ID)\nprint(f\"Channel '{channel_type}:{channel_id}' created/initialized.\")\n\n# Send a message to the channel\nmessage_data = {\"text\": \"Hello from the Python client!\"}\nchannel.send_message(message_data, STREAM_USER_ID)\nprint(\"Message sent!\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions >=4.x.x"},{"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']`.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The API Key or API Secret provided during `StreamChat` client initialization is incorrect or missing.","error":"StreamChatAPIException: Authentication Error: Invalid credentials provided for StreamChat."},{"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')`.","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.","error":"StreamChatAPIException: GetOrCreateChannel failed with error: \"either data.created_by or data.created_by_id must be provided when using server side auth.\""},{"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.","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.","error":"StreamChatAPIException: Channel with given ID does not exist"}]}