---
title: Ruby SDK
description: Install and use the official Trigv Ruby client for Rails apps, scripts, background jobs, deploy hooks, and CI pipelines.
---
# Ruby SDK

Use the official Trigv Ruby SDK to send push notifications from Rails apps, scripts, background jobs, deploy hooks, and CI pipelines.

## Install

Add the gem to your Gemfile:

```
gem 'trigv', '~> 0.1'
```

Then install:

```
bundle install
```

## Send a notification

```
require "trigv"

client = Trigv::Client.new(api_key: ENV.fetch("TRIGV_API_KEY"))

result = client.send_event(
		channel: "general",
		title: "Job finished",
		description: "Nightly sync completed",
		level: "success",
		event_type: "job.completed"
)

puts result.event.public_id
```

## Event fields

| Field | Required | Description |
| --- | :---: | --- |
| `channel` | Yes | Channel slug, such as `general`, `deploys`, or `payments`. |
| `title` | Yes | Push notification title. |
| `description` | No | Body text shown in the notification. |
| `image_url` | No | HTTPS image URL for screenshots, charts, camera snapshots, or previews. |
| `url` | No | Destination URL opened from the notification. |
| `level` | No | `info`, `success`, `warning`, or `error`. Defaults to `info`. |
| `delivery_urgency` | No | `standard` or `time_sensitive`. Defaults to `standard`. |
| `event_type` | No | Free-form event label such as `deploy.completed` or `cron.failed`. |
| `idempotency_key` | No | Deduplication key for safe retries. |

## Safe retries with idempotency

```
result = client.send_event(
		channel: "deploys",
		title: "Production deploy complete",
		idempotency_key: "deploy-prod-42"
)

puts result.duplicate ? "duplicate" : "new"
```

## Configuration

| Option | Default | Description |
| --- | --- | --- |
| `api_key` | `TRIGV_API_KEY` | Workspace API key. |
| `base_url` | `https://api.trigv.com/api` | API base URL. |
| `timeout` | `30` | Request timeout in seconds. |
| `max_retries` | `2` | Retry count for retryable failures. |

## Verify the API key

```
connection = client.verify_connection
puts connection.workspace.name
```

## Error handling

```
begin
		client.send_event(channel: "general", title: "Hello")
rescue Trigv::ValidationError => e
		puts e.errors
rescue Trigv::NotFoundError
		puts "Channel not found"
rescue Trigv::RateLimitError => e
		puts e.retryable ? "Retry later" : "Monthly limit reached"
end
```

## Good places to use it

- Rails jobs, mailers, commands, and operational scripts
- Sidekiq, GoodJob, Resque, and scheduled background work
- Deploy hooks and CI pipelines that need a phone alert

<DocsResourceLinks
  packageHref="https://rubygems.org/gems/trigv"
  packageTitle="RubyGems package"
  packageDescription="Install the official Trigv Ruby SDK from RubyGems."
  packageLabel="Gem"
  sourceHref="https://github.com/Trigv/trigv-ruby"
  sourceDescription="View the Ruby SDK source on GitHub."
/>