# Getting Started

The official Ruby 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/ruby/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/ruby/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/getstream-ruby](https://github.com/GetStream/getstream-ruby) |
| RubyGems | [rubygems.org/gems/getstream-ruby](https://rubygems.org/gems/getstream-ruby)       |

Install the SDK:

```bash
gem install getstream-ruby
```

Or add to your Gemfile:

```ruby
gem 'getstream-ruby'
```

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

```ruby
require 'getstream_ruby'

client = GetStreamRuby.manual(api_key: 'your-api-key', api_secret: 'your-api-secret')
```

You can also load credentials from environment variables (`STREAM_API_KEY`, `STREAM_API_SECRET`) or a `.env` file:

```ruby
client = GetStreamRuby.env
```

## 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.

```ruby
require 'jwt'

token = JWT.encode({ user_id: 'user-id', iat: Time.now.to_i }, 'your-api-secret', 'HS256')
# return the token to the client app
```

Tokens with an expiry:

```ruby
token = JWT.encode(
  { user_id: 'user-id', iat: Time.now.to_i, exp: (Time.now + 3600).to_i },
  'your-api-secret',
  'HS256'
)
```

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:

```ruby
Models = GetStream::Generated::Models

# Upsert a user
client.common.update_users(
  Models::UpdateUsersRequest.new(
    users: { 'john' => Models::UserRequest.new(id: 'john', name: 'John') }
  )
)

# Create or join a channel
client.chat.get_or_create_channel('messaging', 'hello-world',
  Models::ChannelGetOrCreateRequest.new(
    data: Models::ChannelInput.new(created_by_id: 'john')
  )
)

# Send a message
client.chat.send_message('messaging', 'hello-world',
  Models::SendMessageRequest.new(
    message: Models::MessageRequest.new(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/ruby/creating-channels/): Channel types, custom data and everything else about setting up conversations.
- [Sending messages](https://getstream.io/chat/docs/ruby/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

**Which webhook events does chat send?**

The [event catalogue](https://getstream.io/chat/docs/ruby/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/ruby/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/ruby/integrations/stream-chat/#server-side-integration).

---

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