Add Notifications

POST /v2/notifications/add

Add Notifications

cURL

curl --request POST \
  --url https://api.velt.dev/v2/notifications/add \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "createOrganization": true,
    "documentId": "<string>",
    "createDocument": true,
    "actionUser": {},
    "verifyUserPermissions": true,
    "notificationId": "<string>",
    "isNotificationResolverUsed": true,
    "displayHeadlineMessageTemplate": "<string>",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {},
      "recipientUser": "<string>",
      "yourCustomField": "<string>"
    },
    "displayBodyMessage": "<string>",
    "notifyUsers": [
      {}
    ],
    "notifyAll": true,
    "notificationSource": "<string>",
    "notificationSourceData": {},
    "context": {
      "access": {}
    }
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}

Use this API to add notifications.

Endpoint

POST https://api.velt.dev/v2/notifications/add

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

organizationId · string · required

Organization ID

createOrganization · boolean

If set to true, a new organization will be created (if it doesn’t exist) before the notification is created.

documentId · string · required

Document ID

createDocument · boolean

If set to true, a new document will be created before the notification is created.

actionUser · User · required

User who took the action

verifyUserPermissions · boolean

When enabled, notifications are only created for users who have access to the specified document. This ensures notifications respect document access permissions configured via Access Control or Permission Provider.

Default: false

notificationId · string

Notification ID. If not provided, Velt will generate a random ID. Use this if you want more control on the ID being set and prevent duplicate notifications. Only the special characters _, - are allowed.

isNotificationResolverUsed · boolean

Set to true to enable Notification Resolver mode. When enabled, displayHeadlineMessageTemplate and displayBodyMessage are not required — notification content is resolved from your own infrastructure at read time.

displayHeadlineMessageTemplate · string

Display Headline Message Template. Required unless isNotificationResolverUsed is true.

displayHeadlineMessageTemplateData · object

Display Headline Message Template Data (Optional)

Show properties

actionUser · User

User who took the action

recipientUser · string

User who was directly affected by the action

yourCustomField · string

Any custom field with string value

displayBodyMessage · string

Display Body Message. Required unless isNotificationResolverUsed is true.

notifyUsers · User[] · required

Array of Notify Users

notifyAll · boolean

Default is true. If set to true, the notification will be sent to all users in the organization. If set to false, the notification will be sent to only the users specified in the notifyUsers array.

notificationSource · string

Source identifier for the notification. Set to 'custom' for notifications that should be routed through the Notification Resolver. Other values include 'comment', 'huddle', and 'crdt'.

notificationSourceData · object

Any custom object to be stored with the notification. When the user clicks on the notification, this data will be sent in the callback.

context · Context

Context for filtering notifications. Use this to enable context-based filtering of notifications.

Show properties

access · object · required

Key-value pairs for filtering. Keys are custom field names, values are strings or numbers.

Show example

{
  "entityId": "numberOfVisitors",
  "dashboardId": "myDashboard"
}

Example Request

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "actionUser": {
      "userId": "yourUserId",
      "name": "User Name",
      "email": "[e-mail]"
    },
    "displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {
        "userId": "yourUserId",
        "name": "User Name",
        "email": "[e-mail]"
      },
      "recipientUser": {
        "userId": "recipientUserId",
        "name": "Recipient Name",
        "email": "[e-mail]"
      },
      "yourCustomField": "Variable will be replaced with this text"
    },
    "displayBodyMessage": "This is body message (Secondary message)",
    "notifyUsers": [
      {
        "email": "[e-mail]",
        "userId": "testingUserId"
      },
      {
        "userId": "yourUserId",
        "name": "User Name",
        "email": "[e-mail]"
      }
    ]
  }
}

Example Request with Permission Verification

{
  "data": {
    "organizationId": "org1",
    "documentId": "document3",
    "actionUser": {
      "userId": "1.1"
    },
    "verifyUserPermissions": true,
    "displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {
        "userId": "1.1"
      },
      "recipientUser": {
        "userId": "2.2"
      }
    },
    "displayBodyMessage": "This is body message (Secondary message)",
    "notifyUsers": [
      {
        "userId": "2.2"
      }
    ],
    "notifyAll": false
  }
}

When verifyUserPermissions is enabled, the API checks document access for each user before creating notifications. Only users with access to the document will receive notifications.

Example Request with Context

{
  "data": {
    "organizationId": "org1",
    "documentId": "document3",
    "actionUser": {
      "userId": "1.1",
      "name": "User One",
      "email": "[e-mail]"
    },
    "context": {
      "access": {
        "entityId": "numberOfVisitors",
        "dashboardId": "myDashboard"
      }
    },
    "displayHeadlineMessageTemplate": "New comment on {entityName}",
    "displayHeadlineMessageTemplateData": {
      "entityName": "Visitor Analytics"
    },
    "displayBodyMessage": "A new comment has been added to the visitor analytics dashboard",
    "notifyUsers": [
      {
        "userId": "2.2"
      }
    ],
    "notifyAll": false
  }
}

When context is provided, notifications will be filtered based on the specified context fields. Users will only receive notifications that match their context permissions.

Example Request with Notification Resolver

Use this when notification content (headline, body) is stored on your own infrastructure and resolved at read time via the Notification Resolver. Omit displayHeadlineMessageTemplate and displayBodyMessage and set notificationSource to 'custom'.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "documentId": "yourDocumentId",
    "actionUser": {
      "userId": "yourUserId",
      "name": "User Name",
      "email": "[e-mail]"
    },
    "notificationId": "custom-notif-001",
    "isNotificationResolverUsed": true,
    "notificationSource": "custom",
    "notifyUsers": [
      {
        "userId": "recipientUserId",
        "email": "[e-mail]"
      }
    ],
    "notifyAll": false
  }
}

When isNotificationResolverUsed is true, displayHeadlineMessageTemplate and displayBodyMessage are not required. Notification content is fetched from your configured data provider at read time.

Response

Success Response

{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "Notification added successfully.",
    "data": {
      "success": true,
      "message": "Notification added successfully."
    }
  }
}