> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/notifications.md).

# Notifications

## Introduction

The notification entity holds information about which user should have received a notification and what contents this notification has. Also, the seen and read information for a notification is stored in this table.

Notifications are related to many different entities as polymorphic relations which intratool will resolve by given keys.

An internal notification basically consists of:

* Type
* Target entity
* Notifiable entity

to resolve which type of information should be dispatched to whom.

## Model Definition

**Relations**

| Relation               | Key          | Type     | Relation Field(s)                |
| ---------------------- | ------------ | -------- | -------------------------------- |
| Targetable (see below) | `notifiable` | Morph to | `notifiable_type, notifiable_id` |
| Notifiable (see below) | `targetable` | Morph to | `targetable_type, targetable_id` |

**Targetable types**

* infoboardPost ([InfoboardPost](/api-reference/infoboard/infoboard-posts.md))
* infoboardComment ([InfoboardComment](/api-reference/infoboard/infoboard-comments.md))
* calendarEvent (not documented yet).
* ManualEntry ([ManualEntry](/api-reference/manual/manual-entries.md))

**Notifiable types**

* user ([User](/api-reference/users.md))

**Types**

* infoboardPostCreated
* infoboardPostUpdated
* infoboardCommentCreated
* calendarEventCreated
* calendarEventUpdated
* ManualEntryCreated
* ManualEntryUpdated
* generic

{% hint style="warning" %}
Targetable types are keys for different entities existing in our system. Every targetable type listed here has itself a relationship to notifications which can be accessed with the key `notifications`.

Affected entities are marked with the trait `TriggersNotifications`.
{% endhint %}

## List

Get a list of all `Notifications` thar are related to the current authenticated [User](/api-reference/users.md).

**Definition**

<mark style="color:green;">`GET`</mark> `/api/notifications`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": "3dbac57e-d7a5-43b6-ab7b-8999f3a209d9",
    "type": "calendarEventCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "calendarEvent",
    "targetable_id": 16,
    "data": {
      "title": "Neuer Termin im Kalender von Max Mustermann",
      "body": "example body",
      "url": "/kalender/#event=6voprwjq5x3w83n9y2k740e8"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-05-10 11:34:57",
    "updated_at": "2019-05-10 11:34:57"
  },
  {
    "id": "6ec5bc5f-af49-4383-9c27-bb05c26906de",
    "type": "calendarEventUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "calendarEvent",
    "targetable_id": 9,
    "data": {
      "title": "Aktualisierter Termin im Kalender von Max Mustermann",
      "body": "Example body",
      "url": "/kalender/#event=wke24qrd5918plv7zxmg8j06"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-09 19:13:07",
    "updated_at": "2019-04-09 19:13:07"
  },
  {
    "id": "dd1de37c-33f6-4477-9769-e0ea46bf00c0",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 134,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Example body",
      "url": "/infoboard/eintrag/2pmeg69yq73kv71zv54rownx"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-05-10 10:25:04",
    "updated_at": "2019-05-10 10:25:04"
  },
  {
    "id": "f0d244ac-28f2-4906-9918-e1f38fd5d777",
    "type": "infoboardPostUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 133,
    "data": {
      "title": "Aktualisierter Eintrag im Infoboard von Max Mustermann",
      "body": "Example body",
      "url": "/infoboard/eintrag/wke24qrd5918dwlv7zxmg8j0"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-29 15:45:29",
    "updated_at": "2019-04-29 15:45:29"
  },
  {
    "id": "fa2f06fb-add3-4269-98e9-0a8828cde9ac",
    "type": "ManualEntryUpdated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "ManualEntry",
    "targetable_id": 58,
    "data": {
      "title": "Aktualisierter Eintrag im Handbuch von Max Mustermann",
      "body": "Example body",
      "url": "/handbuch/anleitungen/#telefonische-kontakte"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-04 22:07:55",
    "updated_at": "2019-04-04 22:07:55"
  }
]
```

## Count

Get the count of all `Notifications` the current authenticated [User](/api-reference/users.md) is allowed to view.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/notifications/count`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
2
```

## List by target entity type

Lists all `Notifications` with the given target entity type. This enables you to get all notifications related to a specific type of content.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/notifications/type/{targetEntityType}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/infoboardPost', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 850,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
      "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-23 09:16:52",
    "updated_at": "2019-04-23 09:16:52"
  }
]
```

## List by target entity

Lists all `Notifications` with the given target entity type and target entity ID. This enables you to get all notifications related to a specific content.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/notifications/{targetEntityType}/{targetEntity}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/infoboardPost/850', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
    "type": "infoboardPostCreated",
    "notifiable_type": "user",
    "notifiable_id": 1,
    "targetable_type": "infoboardPost",
    "targetable_id": 850,
    "data": {
      "title": "Neuer Eintrag im Infoboard von Max Mustermann",
      "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
      "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
    },
    "seen_at": null,
    "read_at": null,
    "created_at": "2019-04-23 09:16:52",
    "updated_at": "2019-04-23 09:16:52"
  }
]
```

## Show

Show a single `Notification` by `id`.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/notifications/{id}`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/notifications/3dbac57e-d7a5-43b6-ab7b-8999f3a209d9', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": "3dbac57e-d7a5-43b6-ab7b-8999f3a209d9",
  "type": "calendarEventCreated",
  "notifiable_type": "user",
  "notifiable_id": 1,
  "targetable_type": "calendarEvent",
  "targetable_id": 16,
  "data": {
    "title": "Neuer Termin im Kalender von Max Mustermann",
    "body": "Example body",
    "url": "/kalender/#event=6voprwjq5x3w83n9y2k740e8"
  },
  "seen_at": null,
  "read_at": null,
  "created_at": "2019-05-10 11:34:57",
  "updated_at": "2019-05-10 11:34:57"
}
```

## Create

Create a new `Notification`.

This will dispatch a generic notification based on given information to all clients within the given departments and / or users and should be used with care.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/notifications`

**Request Keys**

| Key              |  Type  | Default | Description                                                           |
| ---------------- | :----: | :-----: | --------------------------------------------------------------------- |
| `title` \*       | string |    -    | The title of the notification.                                        |
| `body`\*         | string |    -    | The body text of the notification.                                    |
| `url` \*         | string |    -    | The url the dispatched notification should point to.                  |
| `department_ids` |  array |         | The array of departments that should be targeted by the notification. |
| `user_ids`       |  array |    -    | The array of users that should be targeted by the notification.       |

The fields with `*` are required.

#### Advanced Key-Specifications

* `department_ids` - The array needs to contain valid department ids as integers.
* `user_ids` - The array needs to contain valid user ids as integers.
* `user_ids` - Needs to be filled if there are no department\_ids

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/notifications', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'My own notification',
        'body' => 'The body of my notification.',
        'url' => 'https://my-internal-system.de/',
        'department_ids' => [3,4,5],
        'user_ids' => [4, 6, 8, 10]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": []
}
```

## Update for user

Update **all unread** notifications for the current authenticated user. This route will return the count of affected rows on success.

{% hint style="warning" %}
Notifications are dispatched by our system when you save the information. Thus given, you can not update any content of notifications that are already dispatched.
{% endhint %}

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/notifications/`

**Request Keys**

| Key          |   Type   | Default | Description                                          |
| ------------ | :------: | :-----: | ---------------------------------------------------- |
| `seen_at` \* | datetime |  `NULL` | The timestamp when a user has seen the notification. |
| `read_at`\*  | datetime |  `NULL` | The timestamp when a user has read the notification. |

The fields with `*` are required.

#### Advanced Key-Specifications

* `read_at` - This value will also set the `seen_at` information if no value is given for `seen_at`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": [25]
}
```

## Update

Update a `Notification`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/notifications/{id}`

**Request Keys**

| Key          |   Type   | Default | Description                                          |
| ------------ | :------: | :-----: | ---------------------------------------------------- |
| `seen_at` \* | datetime |  `NULL` | The timestamp when a user has seen the notification. |
| `read_at`\*  | datetime |  `NULL` | The timestamp when a user has read the notification. |

The fields with `*` are required.

#### Advanced Key-Specifications

* `read_at` - This value will also set the `seen_at` information if no value is given for `seen_at`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/017b276f-65f9-4d00-9789-aa6aa0967203', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": [
    {
      "id": "017b276f-65f9-4d00-9789-aa6aa0967203",
      "type": "infoboardPostCreated",
      "notifiable_type": "user",
      "notifiable_id": 1,
      "targetable_type": "infoboardPost",
      "targetable_id": 850,
      "data": {
        "title": "Neuer Eintrag im Infoboard von Max Mustermann",
        "body": "Bitte \u00c4nderungen ber\u00fccksichtigen",
        "url": "/infoboard/eintrag/kn978r25g376561dqwzem4px"
      },
      "seen_at": "2019-01-01 15:00:00",
      "read_at": null,
      "created_at": "2019-04-23 09:16:52",
      "updated_at": "2019-04-23 09:16:52"
    }
  ]
}
```

## Update by target entity type

Update all notifications of the current authenticated user for a specific type.

This enables you to mass update all notifications of a specific target type.

This route will return the count of affected rows on success.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/notifications/{targetableType}`

**Request Keys**

| Key          |   Type   | Default | Description                                          |
| ------------ | :------: | :-----: | ---------------------------------------------------- |
| `seen_at` \* | datetime |  `NULL` | The timestamp when a user has seen the notification. |
| `read_at`\*  | datetime |  `NULL` | The timestamp when a user has read the notification. |

The fields with `*` are required.

#### Advanced Key-Specifications

* `read_at` - This value will also set the `seen_at` information if no value is given for `seen_at`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/infoboardPost', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": [25]
}
```

## Update by target entity

Update a **unread** notification of the current authenticated user by it's target. This is useful if you want to update a notification related to a specific content.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/notifications/{targetableType}/{targetableId}`

**Request Keys**

| Key          |   Type   | Default | Description                                          |
| ------------ | :------: | :-----: | ---------------------------------------------------- |
| `seen_at` \* | datetime |  `NULL` | The timestamp when a user has seen the notification. |
| `read_at`\*  | datetime |  `NULL` | The timestamp when a user has read the notification. |

The fields with `*` are required.

#### Advanced Key-Specifications

* `read_at` - This value will also set the `seen_at` information if no value is given for `seen_at`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/notifications/infoboardPost/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'seen_at' => '2019-01-01 15:00:00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": [25]
}
```