Add notifications (v1)

Create and send in-app notifications to Velt users using the v1 REST API. Trigger notifications from your server with custom payloads and targets.

POST /v1/notifications/add

Add Notifications

cURL

curl --request POST \
  --url https://api.velt.dev/v1/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>",
    "documentId": "<string>",
    "actionUser": {},
    "notificationId": "<string>",
    "displayHeadlineMessageTemplate": "<string>",
    "displayHeadlineMessageTemplateData": {
      "actionUser": {},
      "recipientUser": "<string>",
      "yourCustomField": "<string>"
    },
    "displayBodyMessage": "<string>",
    "notifyUsers": [
      {}
    ],
    "notifyAll": true,
    "notificationSourceData": {},
    "createDocument": true,
    "createOrganization": true
  }
}
'

import requests

url = "https://api.velt.dev/v1/notifications/add"

payload = { "data": {
        "organizationId": "<string>",
        "documentId": "<string>",
        "actionUser": {},
        "notificationId": "<string>",
        "displayHeadlineMessageTemplate": "<string>",
        "displayHeadlineMessageTemplateData": {
            "actionUser": {},
            "recipientUser": "<string>",
            "yourCustomField": "<string>"
        },
        "displayBodyMessage": "<string>",
        "notifyUsers": [{}],
        "notifyAll": True,
        "notificationSourceData": {},
        "createDocument": True,
        "createOrganization": True
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      organizationId: '<string>',
      documentId: '<string>',
      actionUser: {},
      notificationId: '<string>',
      displayHeadlineMessageTemplate: '<string>',
      displayHeadlineMessageTemplateData: {actionUser: {}, recipientUser: '<string>', yourCustomField: '<string>'},
      displayBodyMessage: '<string>',
      notifyUsers: [{}],
      notifyAll: true,
      notificationSourceData: {},
      createDocument: true,
      createOrganization: true
    }
  })
};

fetch('https://api.velt.dev/v1/notifications/add', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v1/notifications/add",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'organizationId' => '<string>',
        'documentId' => '<string>',
        'actionUser' => [
                
        ],
        'notificationId' => '<string>',
        'displayHeadlineMessageTemplate' => '<string>',
        'displayHeadlineMessageTemplateData' => [
                'actionUser' => [
                                
                ],
                'recipientUser' => '<string>',
                'yourCustomField' => '<string>'
        ],
        'displayBodyMessage' => '<string>',
        'notifyUsers' => [
                [
                                
                ]
        ],
        'notifyAll' => true,
        'notificationSourceData' => [
                
        ],
        'createDocument' => true,
        'createOrganization' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v1/notifications/add"

	payload := strings.NewReader("{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"actionUser\": {},\n    \"notificationId\": \"<string>\",\n    \"displayHeadlineMessageTemplate\": \"<string>\",\n    \"displayHeadlineMessageTemplateData\": {\n      \"actionUser\": {},\n      \"recipientUser\": \"<string>\",\n      \"yourCustomField\": \"<string>\"\n    },\n    \"displayBodyMessage\": \"<string>\",\n    \"notifyUsers\": [\n      {}\n    ],\n    \"notifyAll\": true,\n    \"notificationSourceData\": {},\n    \"createDocument\": true,\n    \"createOrganization\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v1/notifications/add")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"actionUser\": {},\n    \"notificationId\": \"<string>\",\n    \"displayHeadlineMessageTemplate\": \"<string>\",\n    \"displayHeadlineMessageTemplateData\": {\n      \"actionUser\": {},\n      \"recipientUser\": \"<string>\",\n      \"yourCustomField\": \"<string>\"\n    },\n    \"displayBodyMessage\": \"<string>\",\n    \"notifyUsers\": [\n      {}\n    ],\n    \"notifyAll\": true,\n    \"notificationSourceData\": {},\n    \"createDocument\": true,\n    \"createOrganization\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v1/notifications/add")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"organizationId\": \"<string>\",\n    \"documentId\": \"<string>\",\n    \"actionUser\": {},\n    \"notificationId\": \"<string>\",\n    \"displayHeadlineMessageTemplate\": \"<string>\",\n    \"displayHeadlineMessageTemplateData\": {\n      \"actionUser\": {},\n      \"recipientUser\": \"<string>\",\n      \"yourCustomField\": \"<string>\"\n    },\n    \"displayBodyMessage\": \"<string>\",\n    \"notifyUsers\": [\n      {}\n    ],\n    \"notifyAll\": true,\n    \"notificationSourceData\": {},\n    \"createDocument\": true,\n    \"createOrganization\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "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/v1/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

documentId · string · required

Document ID

actionUser · User · required

User who took the action

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.

displayHeadlineMessageTemplate · string · required

Display Headline Message Template

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 · required

Display Body Message

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.

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.

createDocument · boolean

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

createOrganization · boolean

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

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]"
      }
    ]
  }
}

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."
    }
  }
}