directus/docs/reference/system/notifications.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Notifications collection in Directus.	5 min read	page-reference

Notifications

Notifications allow you to send/receive messages to/from other users of the platform.

The Notification Object

id integer
Primary key of the revision.

timestamp string
Timestamp in ISO8601 when the notification was created.

status string
Current status of the notification. One of "inbox", "archived".

recipient many-to-one
User that received the notification.

sender many-to-one
User that sent the notification, if any.

subject string
Subject line of the message.

message string
Notification's message content. Will be sent in the email.

collection string
Collection this notification references.

item string
Primary key of the item this notification references.

{
	"id": 2,
	"timestamp": "2021-11-24T13:57:35Z",
	"status": "inbox",
	"recipient": "3EE34828-B43C-4FB2-A721-5151579B08EA",
	"sender": "497a495e-5529-4e46-8feb-2f35e9b85601",
	"subject": "You were mentioned in articles",
	"message": "\nHello admin@example.com,\n\rijk@directus.io has mentioned you in a comment:\n\n> Hello <em>admin@example.com</em>!\n\n<a href=\"http://localhost:8080/admin/content/articles/1\">Click here to view.</a>\n",
	"collection": "articles",
	"item": "1"
}

List Notifications

List all notifications that exist in Directus.

Request

GET /notifications

SEARCH /notifications

POST /graphql/system

type Query {
	notifications: [directus_notifications]
}

import { createDirectus } from '@directus/sdk';
import { rest, readNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readNotifications(query));

Learn more about SEARCH ->

Query Parameters

Supports all global query parameters.

Response

An array of up to limit notification objects. If no items are available, data will be an empty array.

Example

GET /notifications

SEARCH /notifications

POST /graphql/system

query {
	notifications {
		id
		recipient
		subject
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readNotifications({
		fields: ['*'],
	})
);

Retrieve a notification

List an existing notification by primary key.

Request

GET /notifications/:id

POST /graphql/system

type Query {
	notifications_by_id(id: ID!): directus_notifications
}

import { createDirectus } from '@directus/sdk';
import { rest, readNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(readNotification('notification_id', query));

Query Parameters

Supports all global query parameters.

Response

Returns the requested notification object.

Example

GET /notifications/42

query {
	notifications_by_id(id: 42) {
		id
		sender
		recipient
		message
		subject
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, readNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readNotification('4', {
		fields: ['*'],
	})
);

Create a Notification

Create a new notification.

Request

POST /notifications

{
	"notification_object_field_1": "value_1",
	"notification_object_field_2": "value_2"
}

POST /graphql/system

type Mutation {
	create_notifications_item(data: create_directus_notifications_input!): directus_notifications
}

import { createDirectus } from '@directus/sdk';
import { rest, createNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createNotification({
		notification_field: 'value_1',
		notification_field_2: 'value_2',
		notification_field_3: 'value_3',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial notification object.

Response

Returns the notification object for the created notification.

Example

POST /notifications

{
	"recipient": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
	"subject": "Hi there!"
}

POST /graphql/system

mutation {
	create_notifications_item(data: { recipient: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca", subject: "Hi there!" }) {
		id
		recipient
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createNotification({
		recipient: '86eb0719-f5fc-4465-91f6-9d9cd527e105',
		subject: 'Hello there!',
		message: 'Hi fellow user',
	})
);

Create Multiple Notifications

Create multiple new notifications.

Request

POST /notifications

[
	{
		"notification_field": "value_1",
		"notification_field_2": "value_2",
		"notification_field_3": "value_3"
	},
	{
		"notification_2_field": "value_3",
		"notification_2_field_2": "value_4",
		"notification_2_field_3": "value_5"
	}
]

POST /graphql/system

type Mutation {
	create_notifications_items(data: [create_directus_notifications_input!]!): [directus_notifications]
}

import { createDirectus } from '@directus/sdk';
import { rest, createNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createNotifications([
		{
			notification_field: 'value_1',
			notification_field_2: 'value_2',
			notification_field_3: 'value_3',
		},
		{
			notification_2_field: 'value_4',
			notification_2_field_2: 'value_5',
			notification_2_field_3: 'value_6',
		},
	])
);

Query Parameters

Supports all global query parameters.

Request Body

An array of partial notification objects.

Response

Returns the notification object for the created notification.

Example

POST /notifications

[
	{
		"collection": "directus_files",
		"recipient": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
		"message": "Hi there! You should check out these files"
	},
	{
		"collection": "articles",
		"recipient": "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca",
		"message": "Hi there! You should check out these articles"
	}
]

POST /graphql/system

mutation {
	create_notifications_items(
		data: [
			{
				collection: "directus_files"
				recipient: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca"
				message: "Hi there! You should check out these files"
			}
			{
				collection: "articles"
				recipient: "410b5772-e63f-4ae6-9ea2-39c3a31bd6ca"
				message: "Hi there! You should check out these articles"
			}
		]
	) {
		id
		recipient
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, createNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createNotifications([
		{
			recipient: '86eb0719-f5fc-4465-91f6-9d9cd527e105',
			subject: 'Hello there!',
			message: 'Hi fellow user',
		},
		{
			recipient: '86eb0719-f5fc-4465-91f6-9d9cd527e105',
			subject: 'How are you!',
			message: 'I see you are a new contributor, can I help with anything?',
		},
	])
);

Update a Notification

Update an existing notification.

::: tip Email Notifications

Emails are only sent when the notification is created. Updated to an existing notification won't trigger a new notification email to be sent.

:::

Request

PATCH /notifications/:id

{
	"notification_object_field": "value_1"
}

POST /graphql/system

type Mutation {
	update_notifications_item(id: ID!, data: update_directus_notifications_input): directus_notifications
}

import { createDirectus } from '@directus/sdk';
import { rest, updateNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateNotification('notification_id', {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

A partial notification object.

Response

Returns the notification object for the updated notification.

Example

PATCH /notifications/34

{
	"message": "This is my updated notification"
}

POST /graphql/system

mutation {
	update_notifications_item(id: 32, data: { message: "This is my updated notification" }) {
		id
		message
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateNotification('4', {
		status: 'archive',
	})
);

Update Multiple Notifications

Update multiple existing notifications.

Request

PATCH /notifications

{
	"keys": ["notification_key_1", "notification_key_2"],
	"data": {
		"notification_object_field": "field_1"
	}
}

POST /graphql/system

type Mutation {
	update_notifications_items(ids: [ID!]!, data: update_directus_notifications_input): [directus_notifications]
}

import { createDirectus } from '@directus/sdk';
import { rest, updateNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateNotifications(['notification_1_id', 'notification_2_id', 'notification_3_id'], {
		field: 'value',
	})
);

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the notifications you'd like to update.

data Required
Any of the notification object's properties.

Response

Returns the notification objects for the updated notifications.

Example

PATCH /notifications

{
	"keys": [15, 64],
	"data": {
		"message": "Updated message!"
	}
}

POST /graphql/system

mutation {
	update_notifications_items(ids: [15, 64], data: { message: "Updated message!" }) {
		id
		recipient
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, updateNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateNotifications(['1', '2', '3'], {
		status: 'archive',
	})
);

Delete a Notification

Delete an existing notification.

Request

DELETE /notifications/:id

POST /graphql/system

type Mutation {
	delete_notifications_item(id: ID!): delete_one
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteNotification('notification_1_id'));

Response

Empty body.

Example

DELETE /notifications/34

POST /graphql/system

mutation {
	delete_notifications_item(id: 32) {
		id
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteNotification } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteNotification('3'));

Delete Multiple Notifications

Delete multiple existing notifications.

Request

// DELETE /notifications
["notification_1_id", "notification_2_id", "notification_3_id"]

POST /graphql/system

type Mutation {
	delete_notifications_items(ids: [ID!]!): delete_many
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	deleteNotifications(['notification_1_id', 'notification_2_id', 'notification_3_id'])
);

Request Body

An array of notification primary keys

Response

Empty body.

Example

DELETE /notifications

[15, 251, 810]

POST /graphql/system

mutation {
	delete_notifications_items(ids: [15, 251, 810]) {
		ids
	}
}

import { createDirectus } from '@directus/sdk';
import { rest, deleteNotifications } from '@directus/sdk/rest';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteNotifications(['4', '5', '6', '7']));