HN
HubNestv1.4.0
Get Started
Quickstart Guides

Node.js / TypeScript Quickstart

Complete end-to-end guide to send multi-channel notifications from a Node.js or TypeScript application — from API key generation to template creation, event triggering, and delivery verification.

1

1. Sign Up & Get API Key

Register at https://app.hubnest.io. Then go to Developer → API Keys → Generate New Key. Set name, scopes: ["send"], environment: "PROD". Copy the rawKey (hn_live_...) immediately — it is shown only once.

Store rawKey immediately
The API key rawKey is shown only once on creation. It is hashed before storage. Save it in your .env file as HUBNEST_API_KEY=hn_live_xxxxxx right away.
2

2. Create a Subscriber

Subscribers represent your users. Create one to map your user's email and phone to a subscriberId. Go to Developer → Subscribers → Add Subscriber, or use the API. Each subscriber can opt into email, sms, whatsapp, and push independently via channelPrefs.

setup/create-subscriber.sh
bash
1curl -X POST "https://api.hubnest.io/developer/subscribers" \
2 -H "Authorization: Bearer $HUBNEST_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "externalId": "user_12345",
6 "email": "user@example.com",
7 "phone": "+919876543210",
8 "channelPrefs": { "email": true, "sms": true, "whatsapp": true, "push": false }
9 }'
10# Returns { "id": "<subscriber-uuid>", "externalId": "user_12345", ... }
11# Pass this UUID as subscriberId in your event triggers
3

3. Create a Notification Template

Templates define the content of your notifications with {{variable}} placeholders. Create a template for each notification type. Variables are auto-extracted from placeholders if variablesSchema is omitted.

setup/create-template.sh
bash
1curl -X POST "https://api.hubnest.io/developer/templates" \
2 -H "Authorization: Bearer $HUBNEST_API_KEY" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "type": "user.welcome",
6 "channel": "EMAIL",
7 "category": "TRANSACTIONAL",
8 "body": "Hi {{customerName}}, welcome to {{appName}}! Your account is ready.",
9 "variablesSchema": ["customerName", "appName"]
10 }'
11# Returns { "id": "<template-uuid>", "type": "user.welcome", "version": 1, ... }
12# type field = the identifier used in Workflow SEND_ACTION nodes
13# id (UUID) = used as templateId in /api/v1/notifications/send
4

4. Connect a Channel Provider

Go to Developer → Channels → Add Provider and connect at least one delivery provider. For instant testing, use the pre-configured Demo Email provider (no setup needed). For production, connect AWS SES, SendGrid, Twilio, MSG91, WhatsApp, FCM, or APNs — see individual channel docs for exact credential formats.

5

5. Install Dependencies

Initialize your Node.js project and install an HTTP client:

terminal/setup.sh
bash
1npm init -y
2npm install -D typescript @types/node ts-node
3npm install axios
4
5# Or use built-in fetch (Node 18+) — no extra packages needed
6

6. Trigger Event — Rules + Workflows Fire Automatically

POST to /api/v1/events from your Node.js app. HubNest evaluates all active Rules and Workflows for this event and dispatches notifications automatically:

src/hubnest.ts
typescript
1import axios from 'axios';
2
3const HUBNEST_API_KEY = process.env.HUBNEST_API_KEY!; // hn_live_xxxxx
4const HUBNEST_API_URL = 'https://api.hubnest.io';
5
6interface HubNestEventResponse {
7 status: 'processed';
8 eventName: string;
9 ruleMatched: boolean;
10 ruleNotificationStatus?: string;
11 workflowsTriggeredCount: number;
12}
13
14async function triggerEvent(
15 eventName: string,
16 subscriberId: string,
17 email: string,
18 payload: Record<string, unknown>
19): Promise<HubNestEventResponse> {
20 const res = await axios.post(
21 `${HUBNEST_API_URL}/api/v1/events`,
22 { eventName, to: { subscriberId, email }, payload },
23 { headers: { Authorization: `Bearer ${HUBNEST_API_KEY}`, 'Content-Type': 'application/json' } }
24 );
25 return res.data;
26}
27
28// Usage
29async function main() {
30 const result = await triggerEvent(
31 'user.welcome',
32 '<subscriber-uuid>',
33 'user@example.com',
34 { customerName: 'Rahul Sharma', appName: 'Acme Inc' }
35 );
36 console.log('Workflows triggered:', result.workflowsTriggeredCount);
37 console.log('Rule matched:', result.ruleMatched);
38}
39main();
7

7. Direct Send & Bulk Send

For direct single sends (bypasses Rules/Workflows) or bulk campaigns use the dedicated APIs:

src/direct-send.ts
typescript
1// Direct individual send — bypasses Rules & Workflow engine
2async function sendDirectEmail(recipient: string, templateId: string, vars: Record<string, string>) {
3 const res = await axios.post(
4 'https://api.hubnest.io/api/v1/notifications/send',
5 { recipient, channel: 'EMAIL', templateId, variables: vars, category: 'TRANSACTIONAL' },
6 { headers: { Authorization: `Bearer ${process.env.HUBNEST_API_KEY}` } }
7 );
8 return res.data; // { notificationId, status }
9}
10
11// Bulk campaign — fans out via Kafka background queue
12async function sendBulkCampaign(recipients: string[], templateId: string) {
13 const res = await axios.post(
14 'https://api.hubnest.io/api/campaigns',
15 { channel: 'EMAIL', templateId, recipients, category: 'MARKETING' },
16 { headers: { Authorization: `Bearer ${process.env.HUBNEST_API_KEY}` } }
17 );
18 // Response: { message: "Fanned out N messages in campaign successfully...", totalRecipients: "N" }
19 return res.data;
20}
8

8. Verify Delivery in Logs

Go to Developer → Logs at https://app.hubnest.io to see every notification dispatched, its delivery status (sent/failed), latency, provider used, and wallet cost. Set up a Webhook at Developer → Webhooks to receive real-time DELIVERED/FAILED callbacks at your own endpoint.

Run your script
Run your TypeScript file with: npx ts-node src/hubnest.ts — then check Developer → Logs for the dispatched notification and its delivery status.

Next steps

AWS SES Email

Configure AWS SES IAM keys, verified domains, and sending rate limits.

SendGrid Email

Connect SendGrid API Keys and verified sender identities.

Twilio SMS Provider

Connect Twilio Account SID, Auth Token, and phone numbers.

WhatsApp Business

Connect Meta WhatsApp Cloud API access tokens and phone number IDs.

Was this guide helpful?