---
title: "Document notifications"
space: "Raven"
url: "https://docs.frappe.io/raven/frappe-apps/document-notifications"
updated: "2026-10-19"
---
A document notification posts a message in Raven when something happens to a document. For example, it can tell a channel each time a document of a given type is submitted. It works with any document from any Frappe app on your site.
The message is sent by an agent. It can go to a channel, to a person as a direct message, or both. The document card is attached to the message.
:::note
Only Raven admins and System Managers can set up document notifications. Each notification needs an agent to send it, so create an agent first. See [Agents](wiki:6e7bbec94d65).
:::
## See your notifications
Open **Settings** and click **Document Notifications**. The list shows each notification, its document type, when it is sent and whether it is enabled.
## Create a notification
1. Open **Settings** and click **Document Notifications**.
2. Click **Create**.
3. Fill in the **Details** tab.
4. Click the **Recipients** tab and add at least one recipient.
5. If you want, click the **Conditions** tab and add a condition.
6. Click **Create**.
A new notification is enabled. The sections below explain each field.
### Details
| Field | What it does |
| :--- | :--- |
| Name | A name for the notification. You can't change it after you save. |
| Send Alert On | The event that sends the message. See the table below. |
| Document Type | The type of document to watch. |
| Sender | The agent that sends the message. |
| Hide document preview in the notification message | When on, the message is sent without the document card. |
| Message Content | The text of the message. You can format it and add values from the document. |
| Send Alert On | When the message is sent |
| :--- | :--- |
| New Document | When a document is created. |
| Update | Every time a document is saved. This includes when it is created and when it is submitted. |
| Submit | When a document is submitted. |
| Cancel | When a document is cancelled. |
| Delete | When a document is deleted. |
To put a value from the document in the message, write the field name between double braces, like `{{ doc.name }}`. Under the message box, Raven lists every field of the document type you picked. Click a row to copy it. See [Write the message](#write-the-message) for more.
### Recipients
Click **Add Recipient** to add a row. Add one row for each place the message should go.
| Column | What it does |
| :--- | :--- |
| Channel Type | **Channel** posts in a channel. **Direct Message** sends a direct message to a person. |
| Variable Type | How Raven finds the channel or person. See the table below. |
| Value | The channel, the person, the field or the Jinja expression. |
| Variable Type | What to put in Value |
| :--- | :--- |
| Static | Pick one channel or one person. The message always goes there. |
| Document Field | Pick a field of the document that holds a channel or a user. Fields that link to a channel or a user are listed under **Suggested**. For direct messages, **Owner** and **Modified By** are also suggested. |
| Jinja | Write an expression that gives the ID of a channel, or the email of a user. For example, `{{ doc.owner }}`. |
A person must be a Raven user to get a direct message. The agent posts in the channel even if it is not a member.
### Conditions
A condition limits which documents send the message. Leave it empty to send the message for every document that matches the event.
Write a Python expression that uses `doc`. The message is sent only when the expression is true. Under the condition, Raven lists the fields of the document type. Click a row to copy it. See [Write the condition](#write-the-condition) for examples.
:::caution
Raven checks the condition when someone saves the document. If the condition has an error, the document can't be saved until you fix or disable the notification.
:::
## Write the message
The message is a Jinja template, the template language Frappe uses. Type it in **Message Content**. Raven fills it in when the event happens, then sends it.
The template can use these names:
| Name | What it is |
| :--- | :--- |
| `doc` | The document that changed, with all its fields. For **Delete**, it is the document as it was before it was deleted. |
| `frappe` | Frappe's read-only helpers, such as `frappe.utils`, `frappe.db.get_value` and `frappe.get_fullname`. |
| `nowdate` | A function that gives today's date. |
The helpers can only read data. A template can't change or create documents.
Some useful expressions:
| Expression | Gives |
| :--- | :--- |
| `{{ doc.name }}` | The ID of the document. |
| `{{ doc.doctype }}` | The document type. |
| `{{ frappe.get_fullname(doc.owner) }}` | The full name of the person who created the document. |
| `{{ frappe.get_fullname(doc.modified_by) }}` | The full name of the person who last changed it. |
| `{{ frappe.utils.format_date(doc.modified) }}` | The date it was last changed, in the site's date format. |
| `{{ frappe.utils.today() }}` | Today's date. |
| `{{ frappe.db.get_value("User", doc.owner, "email") }}` | A value read from another document. |
Use `doc.get("fieldname")` for a field that might be empty or missing. It gives nothing instead of an error.
Each line you type in **Message Content** becomes a line in the message. In this template, the second line is empty when the document has no status:
```jinja
{{ doc.doctype }} {{ doc.name }} was submitted by {{ frappe.get_fullname(doc.modified_by) }}.
{% if doc.get("status") %}Status: {{ doc.status }}{% endif %}
Submitted on {{ frappe.utils.format_date(doc.modified) }}.
```
To list the rows of a table field, loop over it. Replace `items` with the name of the table field in your document type:
```jinja
Rows in {{ doc.name }}:
{% for row in doc.get("items", []) %}
{{ row.idx }}. {{ row.get("item_name") }}
{% endfor %}
```
You can format the text around the template tags with the toolbar, such as bold or a list.
## Write the condition
The condition is one Python expression. Each line in the block below is a separate example. It can use the same names as the message: `doc`, `frappe` and `nowdate`. Leave out the double braces. The message is sent when the expression gives a value that is true, or not empty.
```python
# Only documents with this status
doc.status == "Open"
# One of several statuses
doc.status in ("Open", "Replied")
# Only submitted documents
doc.docstatus == 1
# A number above a limit
doc.get("grand_total", 0) > 10000
# A field that is filled in
doc.get("assigned_to")
# Not created by the Administrator
doc.owner != "Administrator"
```
The fields in these examples are only examples. Use the fields of your document type, from the list under the condition.
## A full example
This example posts in a channel and sends a direct message to the person who made the document, each time a document is submitted.
1. Open **Settings** and click **Document Notifications**, then click **Create**.
2. In **Name**, enter `Submitted documents`.
3. In **Send Alert On**, pick **Submit**.
4. In **Document Type**, pick the type of document.
5. In **Sender**, pick an agent.
6. In **Message Content**, enter `{{ doc.name }} was submitted.`
7. Click the **Recipients** tab, then click **Add Recipient**.
8. Leave **Channel** and **Static**, and pick the channel under **Value**.
9. Click **Add Recipient** again.
10. Pick **Direct Message** and **Document Field**, then pick **Owner** under **Value**.
11. Click **Create**.
The next time someone submits a document of that type, the agent posts the message in the channel and sends it to the document's owner. The document card is attached to both.
## Change, turn off or delete a notification
Click a notification in the list to open it. Make your changes and click **Save**.
To stop a notification without deleting it, click **⋮** at the top right and click **Disable**. Click **Enable** to turn it back on. To remove it for good, click **⋮** and then **Delete**.
