Quickstart

This guide covers creating a custom code agent in the dashboard, hooking up Slack, scaffolding the bridge app, and getting a reply in-thread.

By the end, you'll have a working agent that receives messages from Slack and replies based on your handler code.

Prerequisites:

• A Novu account.
• A Slack workspace where you can install apps.
• Node.js on your machine.

<Prompt description="Add a Novu agent to my app" icon="plug" actions={["copy", "cursor"]}> Add an agent to my app following instructions from this markdown file: https://novu.co/agents.md

Follow my project's existing framework, routing, styling, and TypeScript conventions.

Reference: https://docs.novu.co/agents/custom-code-agent/quickstart </Prompt>

Create your agent

1. Go to the Novu dashboard.
2. In the sidebar, click Agents.
3. Click Create agent.
4. Fill in the required fields:
   • Agent name: Display name for your agent.
   • Identifier: Unique slug used in code. Cannot be changed after creation.
   • Description: Optional.
5. Click Set up agent.

Novu opens the guided setup page after creation.

Select a provider

1. On the setup page, open Select provider.
2. Select Slack.

The dashboard unlocks the Slack setup steps.

Create a Slack app

Novu can create the Slack app using a Slack App Configuration Token.

1. Click Slack App Configuration Token to open Slack API apps.
2. Under Your App Configuration Tokens, click Generate Token.
3. Select your workspace and click Generate.
4. Copy the token.
5. In Novu, paste the token and click Create app.

Install the app in your workspace

1. Click Install agent (the label may include your agent name, for example Install My Agent).
2. Review permissions in Slack and click Allow.

You'll receive a welcome message from the agent when installation completes.

Scaffold your agent project

Copy the scaffold command from the dashboard:

npx novu@latest init -t agent \
 --secret-key=<NOVU_SECRET_KEY> \
 --api-url=<NOVU_API_URL>

Run it in the directory where you want the project. See Scaffold your project for details.

Start your agent locally

npm run dev:novu

This starts your app, opens a dev tunnel, and registers the bridge URL. When connected, you'll see another message from your agent in Slack.

Send a message

Message your bot in Slack. Your onMessage handler runs and the reply appears in the thread.

Edit files in app/novu/agents/ to customize behavior. See Handle events for all event types.

Next steps