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

# Messaging and Notifications

Canonical maker page for Messaging building blocks. The deep book remains [Application Messaging Foundation Guide](https://docs.notionapps.com/automation/application-messaging-foundation-guide). Extra messaging how-tos redirect there or here. This page absorbs the maker-facing parts of the local first-win and entitlements notes (levels, not admin override order).

## What this is / when to use it

Messaging **moves the event**. Workflow **does the work**. Approvals **get a decision**. Use Messaging when someone must be notified, must converse, must receive an announcement, or when a workflow must create inbox work and later resume on a named reply.

A **topic** is the event name on a channel. It is not a comment. Publishers, Wait steps, Decision outcomes, and Conversation screens only match when they use the **same string**. See [Topics that perform work](#topics-that-perform-work).

When **not** to: you only need a form thank-you. Use submit actions. You need a place for people to act — add a [Decision](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/decision-screen) or [Work Queue](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/work-queue-screen) screen. The topic creates the card; the screen is where they act.

## Before you start

Messaging entitlement is on. Know the level you have:

| Level            | What you may do                                    |
| ---------------- | -------------------------------------------------- |
| **Draft**        | Build routes. Do not publish live messages.        |
| **Intra**        | Same-app messaging and in-app Notification Center. |
| **Inter**        | Linked-app messages (application-link).            |
| **External API** | Inbound/outbound HTTP, partner webhooks.           |

If the builder shows Request access, use that. Do not paste JSON to bypass a level.

## Build it

1. Open Automation Home. Prefer **Create your first automation: Notify someone** (see [wizard](https://docs.notionapps.com/automation/start-from-a-wizard)).
2. For anything beyond a first notify, open Messaging Foundation:
   * Create a **channel** (where messages go).
   * Create a **contract** (shape of the payload).
   * Add **subscriptions** (who receives).
   * Add **publishers** (what may send).
3. Add a **Notification Center** screen if users should read in-app notices.
4. Add a **Conversation** screen if they should reply. Guide: [Conversation](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/conversation-screen).
5. Publish messaging + the app. Send a test.

## Every control

| Block              | What it is                     | Maker controls                                                                      |
| ------------------ | ------------------------------ | ----------------------------------------------------------------------------------- |
| Channel            | Pipe                           | Name, allowed topics, type (in-app / email / webhook), entitlement level required   |
| Topic              | Event name on a channel        | Must match on publish, Wait, Decision reply, and Conversation. Named catalog below. |
| Contract           | Schema                         | Fields the payload must include                                                     |
| Subscription       | Audience                       | Role, user, people field, webhook URL                                               |
| Publisher          | Who may send                   | Workflow step, maker, inbound webhook                                               |
| Announcement       | Broadcast                      | Severity `info` / `warning` / `critical`                                            |
| Application-link   | State machine between two apps | States for request / accept / reject / expire (Linked App Exchange screen)          |
| Notification prefs | End user                       | Profile screen + audience how-to                                                    |

Inbox item types that messaging can create (`AutomationItemType`): `decision` (Decision / Needs Review), `task` (Work Queue), `message` (Conversation), `notification` (Notification Center), plus `linked_app_request` when exchanging with another app. Claim/waiting/expired are item **statuses**, not message types. See [Approval workflows](https://docs.notionapps.com/automation/approval-workflows#shared-inbox-model) for the shared inbox.

## Topics that perform work

Topics are the contract that turns a publish into **work** or a **wait resume**. The Publish Message and Wait for message steps offer these names in the builder. Prefer the dropdown. Do **not** invent a nearby name (`review.sent`, `client.approved`) and expect the queue or the Wait to notice.

Allow every topic you use on the **channel**. A publish or reply with a topic the channel does not list is dropped.

### Named topics (builder presets)

| Topic                               | What it does                                                                           | Inbox item | Typical next step                     |
| ----------------------------------- | -------------------------------------------------------------------------------------- | ---------- | ------------------------------------- |
| `client.review.requested`           | Puts a **Decision** card in Needs Review (for example when Status becomes With Client) | `decision` | Client decides on the Decision screen |
| `client.intake.submitted`           | Puts a **Task** card in the Agency / Work Queue after intake                           | `task`     | Staff claims and works the item       |
| `supervisor.review.requested`       | Puts a **Decision** card in a supervisor inbox                                         | `decision` | Supervisor decides                    |
| `checklist.ready`                   | Puts a **Task** when a related checklist (for example photo slots) is ready            | `task`     | Staff completes the checklist         |
| `client.decision.approve`           | Reply published when the client **approves**                                           | —          | Wakes **Wait for message**            |
| `client.decision.changes_requested` | Reply published when the client **requests changes**                                   | —          | Wakes **Wait for message**            |
| `client.decision.reject`            | Reply published when the client **rejects**                                            | —          | Wakes **Wait for message**            |
| `supervisor.decision.approve`       | Supervisor **approve** reply                                                           | —          | Wakes **Wait for message**            |
| `supervisor.decision.escalate`      | Supervisor **escalate** reply                                                          | —          | Wakes **Wait for message**            |

The three `client.decision.*` topics are the closed set the builder’s **Use all client decision topics** control writes onto a Wait step.

### Same channel, two kinds of work

One workflow channel can carry both reviews and intake. The **topic** plus the **item type** keep the inboxes apart:

* Publish `client.review.requested` as a **decision** → Decision screen (Approve / Changes / Reject).
* Publish `client.intake.submitted` as a **task** → Work Queue (claim and work).

Do not send intake as a decision, or a client review as a task. The cards will land in the wrong inbox.

If you type a custom topic, the builder still infers an item type from the suffix:

* Ends with `.review.requested` or `.approval.requested` → `decision`
* Ends with `.intake.submitted` or `.submitted` → `task`

Otherwise set the item type yourself.

### The wait loop (do not invent names)

A review route only resumes when Publish, Decision, and Wait agree:

```
Publish client.review.requested (item type decision)
  → Decision screen
  → outcome publishes client.decision.approve | changes_requested | reject
  → Wait for message on those exact topics wakes
  → Condition branches on the decision
```

**Wait for message** listens for the reply topics, not the request topic. A custom request topic never wakes a Wait that lists `client.decision.approve`. A Decision outcome that publishes a homemade reply never wakes a Wait that lists the presets.

Notification Center is the **ping**. Preference categories (for example email / social / project alerts) can mute the notice. The Decision or Work Queue card still exists if the user turned the ping off.

Conversation screens bind a **channel** (and usually stay on the workflow channel) so replies stay on the same asset. They do not replace the topic contract above.

### Custom topics

Custom is allowed when the presets do not fit. Then you own both sides:

1. Add the exact string to the channel’s allowed topics.
2. Use that same string on Publish Message (and set item type).
3. Use that same string on Wait for message, **Message received**, or the Decision reply step.
4. Bind Conversation to the same channel if people reply in-app.

Examples such as `task.assigned` or `approval.requested` in older guides are **naming style**, not extra platform topics. They only work if you wire them on every side.

## What users see

Notification Center cards, email, Conversation threads, or a Linked App Exchange request. They set prefs on Profile (mute email, keep in-app, and so on).

## Limits and plans

External webhook subscribers need External API level. Intra cannot send to another app. Draft cannot reach customers. File the rest in the Foundation guide.

## Example

First win: form submitted → notify record owner in Notification Center + email. Review loop: Status becomes With Client → publish `client.review.requested` as a **decision** → client decides → `client.decision.*` wakes Wait. Intake loop: publish `client.intake.submitted` as a **task** on the same channel → Agency Work Queue.

## Fix problems

| Symptom                             | What to do                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Notify wizard blocked               | Request Messaging access                                                                                                                                                                                                                                                                                                      |
| In-app empty, email works           | Add Notification Center, publish the app, and use **Notify someone** / **in\_app** — not a channel subscriber. [How the screen gets populated](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/notification-center-screen#how-this-screen-gets-populated) |
| Decision or Work Queue empty        | Publish used the wrong **topic** or **item type**, or the topic is not allowed on the channel. See [Topics that perform work](#topics-that-perform-work).                                                                                                                                                                     |
| Wait never resumes after a decision | Wait topics must match the Decision reply topics exactly. Use the presets or **Use all client decision topics**.                                                                                                                                                                                                              |
| Webhook subscriber 401              | [Webhook reference](https://docs.notionapps.com/automation/webhooks-and-integrations/webhook-technical-reference)                                                                                                                                                                                                             |

## Related

[Which automation](https://docs.notionapps.com/automation/which-automation). [Approval workflows](https://docs.notionapps.com/automation/approval-workflows). [Step catalog](https://docs.notionapps.com/automation/advanced-reference/step-catalog) (`publish_message`, `wait_for_message`). [Notification Center — how to populate it](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/notification-center-screen#how-this-screen-gets-populated). [Conversation screen](https://docs.notionapps.com/screens-and-components/types-of-screens/native-automation-and-operational-screen-guides/conversation-screen). Foundation guide (deep book).