Sending

Sending Notifications

All send endpoints use workflow_id to specify which Novu workflow to trigger. Call ListWorkflows first to discover available workflow IDs.

Send to a User

POST /api/v1/notifications/manage/send-notification

{
  "workflowId": "push-notification",
  "userId": "recipient-user-id",
  "payload": {
    "title": "New Message",
    "body": "You have a new coaching update",
    "deep_link": "socayo://conversation/conv_abc"
  },
  "transactionId": "optional-idempotency-key"
}

Response:

{
  "acknowledged": true,
  "status": "processed",
  "transactionId": "txn_abc123"
}

Field	Type	Description
workflowId	string	Novu workflow identifier (required)
userId	string	Recipient user ID (required)
payload	object	Arbitrary JSON passed to the workflow template
overrides	object	Novu provider overrides (e.g., FCM data payload)
transactionId	string	Optional idempotency/tracking key

Send Bulk

Trigger workflows for multiple recipients in a single call.

POST /api/v1/notifications/manage/send-bulk-notification

{
  "events": [
    {
      "workflowId": "push-notification",
      "userId": "user-1",
      "payload": {"title": "Update", "body": "New feature available"}
    },
    {
      "workflowId": "push-notification",
      "userId": "user-2",
      "payload": {"title": "Update", "body": "New feature available"}
    }
  ]
}

Response:

{
  "results": [
    {"acknowledged": true, "status": "processed", "transactionId": "txn_1"},
    {"acknowledged": true, "status": "processed", "transactionId": "txn_2"}
  ]
}

Cancel a Notification

Cancel a pending notification by transaction ID.

POST /api/v1/notifications/manage/cancel-notification

{
  "transactionId": "txn_abc123"
}

Response:

{
  "cancelled": true,
  "message": "Event cancelled successfully"
}

Send at a Scheduled Time

Send a notification at a specific date/time. Uses direct content delivery (not Novu workflow), with channel and content fields.

POST /api/v1/notifications/manage/send-scheduled

{
  "userId": "recipient-user-id",
  "channel": "CHANNEL_PUSH",
  "content": {
    "title": "Weekly check-in",
    "body": "Time to review your progress."
  },
  "scheduledAt": "2026-07-01T09:00:00Z",
  "timezone": "America/New_York",
  "idempotencyKey": "weekly-check-in-user-id-2026-07-01"
}

Send After a Delay

Send a notification after a fixed delay in seconds. Useful for follow-up or reminder notifications.

POST /api/v1/notifications/manage/send-delayed

{
  "userId": "recipient-user-id",
  "channel": "CHANNEL_PUSH",
  "content": {
    "title": "Don't forget",
    "body": "You haven't completed your check-in."
  },
  "delaySeconds": 3600,
  "idempotencyKey": "reminder-user-id-2026-07-01"
}

Digest / Batching

Digest behavior is configured in the Novu workflow itself (digest step). This RPC triggers a workflow that has digest enabled.

POST /api/v1/notifications/manage/send-with-digest

{
  "workflowId": "activity-digest",
  "userId": "user-1",
  "payload": {
    "title": "Activity Update",
    "body": "New activity in your coaching plan"
  },
  "transactionId": "digest-event-123"
}

Cancel a digest event:

POST /api/v1/notifications/manage/cancel-digest-event

{
  "transactionId": "digest-event-123"
}