> ## Documentation Index
> Fetch the complete documentation index at: https://v0.x-docs.novu.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby quickstart

> Learn how to use Novu to quickly send multi-channel (SMS, Email, Chat, Push) notifications with Ruby.

Learn how to integrate Novu into your Ruby project on the fly and send notifications across different channels (SMS, Email, Chat, Push).

Let's get started! 💪

## Requirements

To follow the steps in this quickstart, you'll need:

* A Novu account. [Sign up for free](http://web.novu.co/?utm_campaign=docs-gs-quick-ruby) if you don’t have one yet.
* A working Ruby development environment with at least version 2.6.0.

You can also [view the completed code](https://github.com/novuhq/novu-ruby-quickstart) of this quick start in a GitHub repo.

## Install Novu Ruby SDK

The [Ruby SDK](http://github.com/novuhq/novu-ruby) provides a fluent and expressive interface for interacting with Novu's API and managing notifications.

You can install the client library via RubyGems:

```ruby theme={null}
gem install novu

```

Or add it to your Gemfile:

```ruby theme={null}
gem 'novu'

```

Then run `bundle install`.

## Initialize & Configure the Novu Ruby SDK

To use the library, Create a new file `index.rb` then initialize the client with your API token:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

```

Replace the `<NOVU_API_KEY>` argument with the authentic key from the **API Key** section of your [Novu Dashboard](https://web.novu.co/settings?utm_campaign=docs-quick-ruby).

<Note>
  Please do not hardcode your credentials in a file in production. Use environment variables instead.
</Note>

To test your API key, call the methods on the client to interact with the Novu API and display the result on your ruby console:

```ruby theme={null}
puts client.notifications

```

Run the file `index.rb`:

```bash theme={null}
ruby index.rb

```

You should see a result as below:

```json theme={null}
{
  "page": 0,
  "totalCount": 0,
  "pageSize": 10,
  "data": []
}

```

## Set Up A Channel Provider

A channel provider is a service that provides one or more notification functionality such as sending an email, SMS, push notification etc. Our [integration store](https://web.novu.co/integrations?utm_campaign=docs-quick-ruby) includes four channels: Email, SMS, Chat, and Push. These channels have multiple providers associated with them.

| Channel | Providers                                                           |
| ------- | ------------------------------------------------------------------- |
| Email   | MailGun, Mandrill, MailJet, Amazon SES, Sendgrid, Postmark, Netcore |
| SMS     | Twilio, Amazon SNS, Plivo, SMS, SMSCentral, Kannel, Infobip, Termii |
| Chat    | Mattermost, Slack, Microsoft Teams, Discord                         |
| Push    | FCM, APNS, Expo                                                     |

Only one provider can be **active** per **channel**. Connect any of your favorite providers to get started. The email channel comes with Novu's email provider, which is active by default and includes 300 credits.

## Create A Workflow

A workflow is a blueprint for the notifications that will be sent. It holds the entire flow of messages sent to the subscriber. This is where all the different channels are tied together under a single entity.

The workflow includes the following:

* Workflow name and Identifier
* Channel-tailored content:

| Channel<br /><br /> | Content Style<br /><br /> | Custom Variables<br />`{{handlebars}}` format |
| ------------------- | ------------------------- | :-------------------------------------------: |
| **Email**           | HTML                      |                       ✅                       |
|                     | Visual Editor             |                       ✅                       |
| **SMS**             | Text                      |                       ✅                       |
| **Chat**            | Text                      |                       ✅                       |
| **In-App**          | Text                      |                       ✅                       |
| **Push**            | Text                      |                       ✅                       |

<Note>
  Proper authorization needs to be set for the Chat channel for subscribers.
</Note>

Please proceed to create a workflow.

1. Click **Workflows** on the left sidebar of your Novu dashboard.
2. Click the **Create Workflow** button on the top right.

<Frame caption="Use the create workflow button to create a workflow">
  <img src="https://mintcdn.com/novu-v2-docs/NV5X8JGFK6ip1oRy/images/workflow-kotlin.png?fit=max&auto=format&n=NV5X8JGFK6ip1oRy&q=85&s=1d85a6a1495d7ec322c6ae9813ddb837" width="2000" height="1116" data-path="images/workflow-kotlin.png" />
</Frame>

3. The name of the new workflow is currently Untitled, rename it to a more suitable title.

<Frame caption="Rename the workflow to a more suitable title">
  <img src="https://mintcdn.com/novu-v2-docs/rGvFx0oDoBLPCuxk/images/renam-workflow-kotlin.png?fit=max&auto=format&n=rGvFx0oDoBLPCuxk&q=85&s=f8574dcbfd7b87977dfee74fc0b7551a" width="2000" height="1112" data-path="images/renam-workflow-kotlin.png" />
</Frame>

4. Select Email as the channel you want to add, by dragging it from the right sidebar.

<Frame caption="Select Email as the channel you want to add, by dragging it from the right sidebar.">
  <img src="https://mintcdn.com/novu-v2-docs/rGvFx0oDoBLPCuxk/images/select-email-kotlin.png?fit=max&auto=format&n=rGvFx0oDoBLPCuxk&q=85&s=608eb643f25dfd769af0b2b85f8aa36c" width="2000" height="1113" data-path="images/select-email-kotlin.png" />
</Frame>

5. Click on the Email in the workflow and edit it as per this image. Don’t forget to add the fields in the editor which is supposed to be updated with dynamic values that will be sent when calling the API.

<Frame caption="Add the fields in the email editor">
  <img src="https://mintcdn.com/novu-v2-docs/sGuc2UrECiU5eWcY/images/add-fields-kotlin.png?fit=max&auto=format&n=sGuc2UrECiU5eWcY&q=85&s=d8dbf1f462795bcc5c5358b066675abe" width="2000" height="1242" data-path="images/add-fields-kotlin.png" />
</Frame>

6. Also, add the variables in the Variables section in the test tab and try testing it by sending the email to your email address using the Send Test Email button at the bottom right.

<Frame caption="Add the variables in the Variables section in the test tab">
  <img src="https://mintcdn.com/novu-v2-docs/sGuc2UrECiU5eWcY/images/add-variables-kotlin.png?fit=max&auto=format&n=sGuc2UrECiU5eWcY&q=85&s=0371a5a533d663a3cd3ed256ec03fd33" width="2000" height="1112" data-path="images/add-variables-kotlin.png" />
</Frame>

You should get an email within seconds! 👌

Great, you have successfully sent your first notification via the Novu dashboard! Now, let’s take a step further to trigger notifications via code.

## Create A Subscriber

The recipients of a triggered notification are called subscribers.

Click **Subscribers** on the left sidebar of the Novu dashboard to see all subscribers. By default, the dashboard will display a subscriber, as you were added automatically during sign-up.

<Frame caption="By default, the dashboard will display a subscriber, as you were added automatically during sign-up.">
  <img src="https://mintcdn.com/novu-v2-docs/RjdbijoFZs-J-RVM/images/default-sub-kotlin.png?fit=max&auto=format&n=RjdbijoFZs-J-RVM&q=85&s=e2410492ff07dc140dac1d64182f271c" width="2000" height="933" data-path="images/default-sub-kotlin.png" />
</Frame>

Now, let's create a subscriber on Novu. Copy and paste the following code to do so:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

## Create subscriber

create_payload = {
    'subscriberId' => '7789', # replace with system_internal_user_id
    'firstName' => 'John', # optional
    'lastName' => 'Doe', # optional
}
client.create_subscriber(create_payload)

```

Run the code in your terminal:

```bash theme={null}
ruby index.rb

```

You should see the subscriber on your Novu dashboard.

\![https://res.cloudinary.com/dxc6bnman/image/upload/f\_auto,q\_auto/v1685466979/guides/Screenshot\_2023-05-14\_at\_11.06.38\_ugvmc0.png](https://res.cloudinary.com/dxc6bnman/image/upload/f_auto,q_auto/v1685466979/guides/Screenshot_2023-05-14_at_11.06.38_ugvmc0.png)

I’d like to publicly announce that `abc@gmail.com` is a random unlikely email your users will have. To update this to an alternative email, you can call the `updateSubscriber` method like so:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

## Update subscriber detail

update_payload = {
    'email' => 'validemail@gmail.com',  # replace with valid email
    'firstName' => '<insert-firstname>', # optional
    'lastName' => 'Obasanjo', # optional
}
client.update_subscriber('7789', update_payload);
```

Other valid fields that can be updated are `phone`, `avatar`, and `data`. The `data` field can accept an object of metadata that you want to attach to the subscriber.

<Note>
  To make all of your app users subscribers, you need to programmatically add them to Novu.
</Note>

## Trigger A Notification

Copy and paste the following code into your app to trigger a notification:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

## trigger a notification

trigger_payload = {
    'name' => 'Trigger1',
    'payload' => {
        'first-name' => 'Adam'
    },
    'to' => {
        'subscriberId' => '7789'
    }
}
client.trigger_event(trigger_payload)

```

Before running the code, make sure you understand the following:

* The value of `name` should be the workflow’s trigger ID/slug.

<Frame caption="Make sure your workflow's trigger ID/slug matches the value you'd used">
  <img src="https://mintcdn.com/novu-v2-docs/rGvFx0oDoBLPCuxk/images/template-nodejs.png?fit=max&auto=format&n=rGvFx0oDoBLPCuxk&q=85&s=2021841772a344d9bd5f87eb4ddaf524" width="2000" height="1059" data-path="images/template-nodejs.png" />
</Frame>

* The value of `payload` is an array of the data that you want to be dynamically injected into the workflow content.
* The value of `subscriberId` is the id of the subscriber on Novu. Replace `7789` with your subscriber ID.

Run the code to trigger a notification!

```bash theme={null}
ruby index.rb

```

Next, we’ll learn how to send notifications to different groups of subscribers easily via **Topics.**

## Topics

Novu provides a simple API that offers an easy interface for triggering notifications to multiple subscribers at once. This API is called **Topics** and allows users to manage their bulk notifications without having to implement complex loops.

A topic is identified by a custom key and this key will be the identifier used when triggering notifications. You can assign a name to a topic for descriptive purposes. This name does not need to be unique and can be changed programmatically.

<Note>
  The topic key should be unique and can't be changed once chosen. Novu also safeguards for key uniqueness behind the scenes.
</Note>

A topic can have multiple subscribers who will receive a notification whenever a message is sent to the topic.

## Create a Topic

Copy and paste the following code into your app to create a topic:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')
## Create a Topic

create_topic_payload = {
    'key'  => 'frontend-users',
    'name' => 'All frontend users'
}
client.create_topic(create_topic_payload)

```

Before running the code, make sure you understand the following:

* When creating a `key`, ensure it is unique and accurately identifies the topic. Document naming conventions and communicate them to team members to avoid confusion and ensure a smooth workflow.
* The value of `name` should be a descriptive topic name.

## Add and Remove Subscribers to a Topic

Copy and paste the following code into your app to add subscribers to a topic:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

topicKey = 'frontend-users'
subscribers = ['6460925ce1a93324257d2fc1', '7789'].to_s

## Add subscribers to a topic
client.add_subscribers(topicKey, subscribers)

```

Also, you can remove subscribers from a topic by using the code snippet below:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

topicKey = 'frontend-users'
subscribers = ['6460925ce1a93324257d2fc1', '7789'].to_s

## Remove subscribers from a topic
client.remove_subscribers(topicKey, subscribers)

```

## Sending a notification to a Topic

Thanks to the topics feature, it is possible to trigger a notification to all subscribers assigned to a topic. This helps avoid listing all subscriber identifiers in the `to` field of the notification trigger.

To trigger a notification to all subscribers of a topic, copy and paste the code below:

```ruby theme={null}
require 'novu'

client = Novu::Client.new('<NOVU_API_KEY>')

## Send notifications to a topic (all frontend users)
client.trigger_event({
    'name' => 'Trigger1',
    'to' => {
        'type' => 'Topic',
        'topicKey' => 'frontend-users'
    }
})

```

<Note>
  The value of the `name` key in the payload should be the name of the notification created earlier.
</Note>

## Conclusion

Great job! If you've reached this point, you should now have successfully created a subscriber, workflow, configured a channel provider and triggered a notification in your application.