# Getting Started

The official Python SDK for Stream covers Chat, Video, Moderation, and Feeds. This page takes you from installing the SDK to your first API call.

## Start here

- [Backend quickstart](https://getstream.io/chat/docs/python/backend/): Generate tokens, sync users and manage channels from your server.
- [Authentication and tokens](https://getstream.io/docs/platform/authentication/): Token signing, expiry and revocation in detail.
- [Client-side overview](https://getstream.io/chat/docs/python/client-side/): Connecting users, presence and everything else that runs in your app.

## How the pieces fit together

This SDK calls the Stream API from your backend, authenticated with your API secret. Your users connect from your app with a client SDK, using a token your backend signs. Anything that needs a connected user or a live WebSocket lives in the client: initialization, guest and anonymous sessions, typing indicators and presence.

```mermaid
flowchart LR
  app[Your app] <-->|WebSocket| api[Stream API]
  backend[Your backend] -->|REST| api
  backend -. user token .-> app
```

## Stream CLI and Agent Skills

Manage Stream from your terminal with the [Stream CLI](https://getstream.io/cli/docs/), including scripting and AI-agent workflows. Install the CLI and the default [Agent Skills](https://getstream.io/agent-skills/docs/):

```bash
curl -fsSL https://getstream.io/cli.sh | bash
getstream skills
```

Then ask your agent in plain English, for example:

```text
/stream List recent channels in my app.
```

See the [CLI docs](https://getstream.io/cli/docs/) and [Agent Skills docs](https://getstream.io/agent-skills/docs/) for more.

## Setup

|        |                                                                          |
| ------ | ------------------------------------------------------------------------ |
| GitHub | [github.com/GetStream/stream-py](https://github.com/GetStream/stream-py) |
| PyPI   | [pypi.org/project/getstream](https://pypi.org/project/getstream/)        |

Install the SDK:

```python
pip install getstream
```

Initialize the client with your API key and secret (available on the [Dashboard](https://getstream.io/signin/?product=chat)):

```python
from getstream import Stream

client = Stream(api_key="your-api-key", api_secret="your-api-secret")
```

The client also reads `STREAM_API_KEY` and `STREAM_API_SECRET` from environment variables, so you can construct it with no arguments:

```python
client = Stream()
```

## Server-side token

Your backend generates a user token that the client SDKs use to authenticate. A typical place to issue this token is during login or registration.

```python
token = client.create_token(user_id="user-id")
# return the token to the client app
```

Tokens with an expiry (in seconds):

```python
token = client.create_token(user_id="user-id", expiration=3600)
```

For token expiry and revocation details, see [Authentication and tokens](https://getstream.io/docs/platform/authentication/).

## Making your first API call

Create a user, open a channel, and send a message:

```python
from getstream.models import UserRequest, ChannelInput, MessageRequest

# Upsert a user
client.upsert_users(
    UserRequest(id="john", name="John")
)

# Create or join a channel
channel = client.chat.channel("messaging", "hello-world")
channel.get_or_create(data=ChannelInput(created_by_id="john"))

# Send a message
channel.send_message(
    MessageRequest(text="Hello, Stream!", user_id="john")
)
```

## What's next

Once your first message is through, these are good places to go deeper:

- [Creating channels](https://getstream.io/chat/docs/python/creating-channels/): Channel types, custom data and everything else about setting up conversations.
- [Sending messages](https://getstream.io/chat/docs/python/send-message/): Attachments, custom fields and the rest of the message API.
- [Webhooks](https://getstream.io/docs/platform/webhooks/): React to chat events from your own backend.

## FAQ

**Is there an asyncio client?**

Yes. `Stream(...).as_async()` returns one for FastAPI and other asyncio apps. See [async](https://getstream.io/chat/docs/python/async/).

**Which webhook events does chat send?**

The [event catalogue](https://getstream.io/chat/docs/python/webhook-events/) lists every webhook event and most payloads.

**Can I check messages before they're delivered?**

Yes, with the [before message send webhook](https://getstream.io/chat/docs/python/before-message-send-webhook/).

**Does this SDK cover other Stream products?**

Yes. Each [backend SDK](https://getstream.io/docs/platform/backend-sdks/) covers every product; build one client and reuse it.

**Are server-sent messages moderated?**

Not by default. Set `force_moderation` to `true` when sending. The flag is server-side only and ignored when sent from a client-side SDK. See [chat moderation](https://getstream.io/moderation/docs/python/integrations/stream-chat/#server-side-integration).

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/python/](https://getstream.io/chat/docs/python/).