chatgpt-api/docs/novu.md

Novu Agentic Service

Intro

Novu provides open-source notification infrastructure for all communication channels in one place: Email, SMS, Direct, and Push. It integrates with almost all major email providers (Mailgun, Sendgrid, Postmark, etc.), SMS providers (e.g., Twilio or Plivo), and a large selection of push and chat providers (such as OneSignal or Slack) while providing a unified API for sending notifications.

Pre-requisites

Ensure the following environment variable is set:

• NOVU_API_KEY - Novu API key.

Otherwise, you can pass it in as an argument to the Novu constructor.

How to Retrieve API Key on Novu.co

1. Open https://web.novu.co and sign in with your existing Novu account credentials (create a new account with your email address and a password or sign in with GitHub if you don't have an account yet)

2. Navigate to "Settings"

3. Click "API Keys"

4. Click here to copy your API key to your clipboard

Create a Notification Template

For each notification type you want to send, you need to create a template in Novu. This is a one-time setup step that you can do on the Novu web interface.

It is possible to customize the notification content at each invocation via handlebars-style placeholders. For example, you can create a template for an email notification that looks like this:

Hello {{name}},
{{content}}

The placeholders will be replaced with the actual values of the payload object you pass to the send method.

To create a template, follow these steps:

1. Open https://web.novu.co and sign in with your Novu account credentials

2. Click "Notifications"

3. Click "Create Workflow" on the top-right

4. Double-click the "notification name" field and enter the name of the template. For this example, we choose the name send-sms. This is the event name with which the respective notification may be triggered from the API.

5. To create, for example, a SMS notification template, click and hold "SMS" and drag it to the left underneath the trigger.

6. Click inside the "SMS message content" text field on the right and enter the content of your SMS, e.g. a handlebars placeholder such as {{content}}.

7. When you're done, click "Update" on the top-right. You are now ready to send SMS notifications via the API. For example, to manually trigger a notification via the Agentic Novu Service client:

import { NovuClient } from '@agentic/core'

const client = new NovuClient()

client.triggerEvent('send-sms', { content: 'Hello World!' }, [{
  subscriberId: '1',
  name: 'Jane Doe',
  email: 'jane.doe-123@hotmail.com'
  phone: '+11234567890'
}])

The subscriberId is a required field with the ID of the subscriber in Novu. If a subscriber with a provided subscriberId does not exist yet in Novu, a new subscriber will be created before the trigger will be executed synchronously. You can find more information about subscribers in the official Novu documentation.