# 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]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.api.intratool.de/api-reference/notifications.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.