> 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

## Messaging and Notifications

![](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F3N99vYj45F6n5fDVAAzZ%2Fnotionapps-messaging-screenshot-gallery.png?alt=media\&token=b62bd223-5268-48da-852d-051c24d62ba5)

Messaging helps your app tell people what happened, what needs attention, and where to go next. Use it when your app needs notifications, announcements, direct conversations, group conversations, or workflow-aware messages.

Messaging is part of **Automation (Beta Testing)**. Workflow moves work through steps. Messaging keeps people informed while that work happens. The simplest way to think about it is:

> A screen, workflow, or app event sends a message. Messaging routes it to the right person, screen, workflow, or conversation.

**When to use Messaging**

Use Messaging when your app needs to communicate with people or route updates between parts of the app.

Good use cases include:

* Notify a supervisor when a form is submitted.
* Send a reminder when a request needs review.
* Let two people discuss a record inside the app.
* Create a group conversation for a team or support queue.
* Broadcast a service announcement to all app users.
* Show routed notifications in a Notification Center screen.
* Let a workflow publish a message after an approval, rejection, hold, or exception.
* Create a conversation around a customer request, inventory exception, timecard, support ticket, or approval.

Use **Workflow** when the app needs to make decisions, wait, branch, update records, or run a multi-step process. Use **Messaging** when the app needs to tell people about that process or let people respond in context.

**Messaging concepts in plain language**

| Concept      | What it means                                                      | Example                                                 |
| ------------ | ------------------------------------------------------------------ | ------------------------------------------------------- |
| Message      | A communication created by a user, screen, workflow, or app event. | “A new timecard is ready for review.”                   |
| Notification | A short alert that appears in the app.                             | “Inventory count exception needs attention.”            |
| Announcement | A broadcast message for many users.                                | “The system will be unavailable at 6 PM.”               |
| Conversation | A thread of replies between users.                                 | A supervisor and employee discuss a submitted timecard. |
| Channel      | A lane for a category of messages.                                 | announcements, notifications, conversations             |
| Topic        | The specific kind of event inside a channel.                       | announcement.published or conversation.message.sent     |
| Recipient    | The person or group who should receive the message.                | Employee, supervisor, requester, admin, operations team |

You do not need to memorize raw IDs to get started. The guided setup asks for the business outcome first, then helps create the right messaging objects.

**Start with the business outcome**

The easiest way to build Messaging is to start with a plain sentence:

> When this happens, tell these people, and show the message here.

Examples:

* When an employee submits a timecard, notify their supervisor.
* When a stock count is below the expected amount, notify operations.
* When payroll is complete, announce it to all employees.
* When a customer refund is rejected, notify the requester and start a conversation.

After you describe the outcome, NotionApps can recommend a messaging pattern and help you create the supporting route.

**Guided setup flow**

Messaging can be configured manually, but most makers should start with **Guided setup**.

Guided setup is organized around three steps:

1. **Describe what should happen**

   Type the business outcome in normal language. You might write, “When a stock count is submitted and the numbers do not match, notify operations and start a review conversation.”
2. **Review the objects NotionApps will create**

   NotionApps recommends a channel, topic, contract, source, destination, fields, and example payload. You can accept the recommendation or adjust it.
3. **Create, attach, and test the route**

   Create the channel, save the message shape, attach the sender, attach the receiver, and run a dry-route preview before using it live.

This keeps Messaging approachable: the maker describes the business outcome, and NotionApps assembles the engine.

**Common messaging patterns**

| Pattern                          | Use it when                                                      | Typical result                                            |
| -------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- |
| Notify the right person          | A user or workflow needs to alert one or more people.            | A notification appears for the recipient.                 |
| Broadcast an announcement        | An admin needs to send an app-wide message.                      | The announcement appears in the Notification Center.      |
| Start or continue a conversation | Users need to discuss a record, request, or approval.            | A conversation thread is created or continued.            |
| Send a workflow update           | Workflow should tell users what happened.                        | A message is published after a workflow step.             |
| Send an event to another system  | A screen or workflow should notify a webhook or external system. | A structured event is sent to the configured destination. |

**Add a Notification Center screen**

Use a Notification Center screen when users need one place to see announcements, service messages, and routed notifications.

Recommended setup:

1. Open your app in the builder.
2. Go to the Screens area.
3. Add a **Notification Center** screen.
4. Give it a clear name, such as **Notifications** or **Announcements**.
5. Choose where the screen should receive messages from.
6. Set visibility so the right users can open it.
7. Publish and test as a real app user.

A Notification Center is best for broad messages and alerts. It is not meant to replace a back-and-forth conversation thread.

**Add a Conversation screen**

Use a Conversation screen when users need to reply to each other.

Good examples:

* A manager asks an employee to clarify a timecard.
* Operations discusses an inventory mismatch.
* A reviewer asks a requester for more information.
* Support staff discuss a customer issue.

Recommended setup:

1. Add a **Conversation** screen.
2. Decide whether the screen should show direct conversations, record-related conversations, group conversations, or a focused thread.
3. Bind the screen to the appropriate messaging channel.
4. Set visibility rules so users only see conversations they are allowed to access.
5. Test with two personas so you can confirm replies appear for both sides.

For private communication, make sure your visibility rules only allow the intended participants to see the conversation.

**Send an announcement**

Announcements are useful for app-wide or role-wide updates.

Examples:

* “Payroll exports are ready.”
* “Inventory counts are due by Friday.”
* “The app will be under maintenance tonight.”
* “New approval policy starts next week.”

Recommended setup:

1. Open **Automation**.
2. Open **Messaging** or **Announcements**.
3. Create an announcement message.
4. Choose the audience.
5. Choose where it should appear, usually Notification Center.
6. Send or publish the announcement.
7. Log in as a target user and confirm they can see it.

Keep announcement text short and action-oriented. If users need to discuss the announcement, link them to a Conversation screen or a relevant record screen.

**Example: notify a supervisor after a form submission**

Business outcome:

> When an employee submits a timecard, notify the assigned supervisor.

Recommended setup:

| Object      | Example value                                        |
| ----------- | ---------------------------------------------------- |
| Channel     | notifications                                        |
| Topic       | work.notification.requested                          |
| Source      | The submitted form or screen                         |
| Destination | The workflow, notification screen, or recipient rule |
| Payload     | Record ID, message, recipient, priority              |

Maker steps:

1. Open **Automation > Messaging > Guided setup**.
2. Describe the outcome in plain language.
3. Choose the recommended **Notify the right person** pattern.
4. Select the actual form or screen that starts the message.
5. Select the recipient rule or workflow that should receive it.
6. Create or confirm the channel.
7. Save and test the route.
8. Submit the form as a test user and confirm the supervisor sees the notification.

**Example: broadcast a maintenance announcement**

Business outcome:

> Broadcast a maintenance notice to everyone using this application.

Recommended setup:

| Object      | Example value                          |
| ----------- | -------------------------------------- |
| Channel     | announcements                          |
| Topic       | announcement.published                 |
| Source      | Admin announcement action or workflow  |
| Destination | Notification Center                    |
| Payload     | Title, message, severity, created date |

Maker steps:

1. Add or confirm a Notification Center screen.
2. Open **Automation > Messaging**.
3. Choose the **Broadcast an announcement** pattern.
4. Write a short title and message.
5. Choose the audience.
6. Send or test the announcement.
7. Log in as a target user and confirm the announcement appears.

**Use Messaging with Workflow**

Messaging becomes especially powerful when combined with Workflow.

Example: approval request

1. A user submits a request form.
2. Workflow starts an approval route.
3. Workflow sends a notification to the reviewer.
4. The reviewer opens the decision screen.
5. The reviewer approves, rejects, or asks a question.
6. Messaging notifies the requester and can continue a conversation.

Example: inventory exception

1. A user submits a stock count.
2. Workflow checks the expected quantity.
3. If the count is outside the expected range, Workflow creates an exception.
4. Messaging notifies operations.
5. Operations discusses the issue in a Conversation screen.
6. Workflow records the resolution.

**What a useful message should include**

A good message tells the recipient enough to act.

Include:

* What happened.
* Which record or request is involved.
* Who submitted or triggered it.
* What the recipient should do next.
* Where to open the related screen or record.

Weak message:

> Workflow update.

Better message:

> Timecard for Jordan Lee is ready for review. Open Supervisor Review Queue to approve, reject, or request changes.

**Testing checklist**

Before publishing your app, test Messaging with real app personas.

Check that:

* The right screen exists, such as Notification Center or Conversation.
* The screen is visible to the intended users.
* The messaging channel or announcement setup exists.
* The workflow, form, button, or screen that sends the message is configured.
* The recipient can see the message.
* A user who should not see the message cannot see it.
* Replies appear in the correct conversation thread.
* Announcements do not appear as private direct messages.
* Workflow-triggered messages appear after the workflow step runs.

**Troubleshooting**

If messages do not appear, check these items first:

| Problem                                 | What to check                                                                                                    |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| User cannot see the Notification Center | Screen visibility may be too restrictive, or the screen may not be in navigation for that role.                  |
| Conversation appears empty              | The screen may be listening to the wrong channel, topic, or conversation context.                                |
| Announcement does not show              | Confirm the announcement channel exists and the target screen is listening for announcements.                    |
| Workflow message does not send          | Confirm the workflow is active, valid, and the notification or message step is configured.                       |
| Wrong people can see a message          | Review screen visibility, recipient rules, and conversation participants.                                        |
| A setup field asks for an ID            | Use the context-aware selector when available. Search by friendly screen, form, workflow, channel, or user name. |

**Best practices**

* Start with the business outcome, not the technical object.
* Use short channel names such as notifications, announcements, conversations, and approvals.
* Keep announcement text brief.
* Use conversations when people need to reply.
* Use Notification Center for alerts and broadcasts.
* Test with more than one persona.
* Keep private conversations separate from broadcast announcements.
* Combine Workflow and Messaging when a business process needs both action and communication.Current guided messaging setup

  Messaging setup now follows the same outcome-first pattern as Workflow and Approval setup. A maker should be able to describe what they want in business language and let NotionApps assemble the messaging route.

  Start with a sentence such as:

  ```
  When a stock count is submitted, notify operations and open a conversation around the item.
  ```

  The guided setup then walks through these steps:

  1. **Describe what should happen.** NotionApps recommends a messaging pattern, such as notify the right person, broadcast an announcement, start a conversation, or send an event to another system.
  2. **Answer the numbered questions.** Choose the source type, source object, destination type, destination object, and payload. The source and destination fields are context-aware and can suggest screens, forms, controls, data sources, workflows, channels, and saved IDs from the current application.
  3. **Review the route plan.** NotionApps explains which channel, contract, source attachment, and destination attachment will be created or reused.
  4. **Build this messaging route.** One action creates or reuses the channel, saves and publishes the contract, attaches the publisher, attaches the subscriber, and runs a dry-run when live publish access is available.
  5. **Inspect Activity.** Use Activity to confirm which subscriber matched, whether the payload was accepted, and whether any delivery or entitlement blocker remains.

  The maker does not need to start by understanding channels, topics, contracts, publishers, or subscribers. Those objects still exist and remain visible for advanced tuning and support, but the normal maker path begins with the desired business result.

  **Example: Notify a supervisor**

  Business language:

  ```
  When an employee submits a timecard, notify the assigned supervisor.
  ```

  What NotionApps assembles:

  | Object      | Example                                                                |
  | ----------- | ---------------------------------------------------------------------- |
  | Channel     | notifications                                                          |
  | Topic       | work.notification.requested                                            |
  | Contract    | notification\_request\@1.0.0                                           |
  | Source      | The selected form or screen                                            |
  | Destination | A workflow, screen, role, or subscriber that receives the notification |

  After the route is built, run a dry-run and then test as the real app user. The proof is visible in Messaging Activity, Workflow Activity, the Notification Center, or the target conversation screen depending on the route.Current guided messaging setup

  Messaging now follows the same outcome-first pattern as Workflow. The maker starts with the message outcome and NotionApps helps create the channel, topic, route, and proof steps.

  Example outcome:

  > When a stock count is submitted, notify operations and open a conversation around the item.

  A maker should configure that outcome this way:

  1. Describe what should happen in plain language.
  2. Choose the source screen or event from app-aware suggestions.
  3. Choose the destination: notification center, conversation screen, app-wide announcement, role, or person.
  4. Review the route plan.
  5. Click **Build this messaging route** when the route matches the desired outcome.
  6. Send a test message or run the guided test.
  7. Inspect Activity or Messaging Operations if the delivery does not appear.

  A common notification route looks like this:

  | Setting     | Example                                      |
  | ----------- | -------------------------------------------- |
  | Channel     | notifications                                |
  | Topic       | work.notification.requested                  |
  | Contract    | notification\_request\@1.0.0                 |
  | Source      | A selected form or workflow event            |
  | Destination | A role, screen, subscriber, or selected user |

  Use announcements for broadcast messages. Use conversations for direct or grouped discussion. Use notifications for routed system updates that tell someone work needs attention.

### Current guided messaging setup

Messaging now follows the same outcome-first pattern as Workflow. The maker starts with the message outcome and NotionApps helps create the channel, topic, route, and proof steps.

Example outcome:

> When a stock count is submitted, notify operations and open a conversation around the item.

A maker should configure that outcome this way:

1. Describe what should happen in plain language.
2. Choose the source screen or event from app-aware suggestions.
3. Choose the destination: notification center, conversation screen, app-wide announcement, role, or person.
4. Review the route plan.
5. Click **Build this messaging route** when the route matches the desired outcome.
6. Send a test message or run the guided test.
7. Inspect Activity or Messaging Operations if the delivery does not appear.

A common notification route looks like this:

| Setting     | Example                                      |
| ----------- | -------------------------------------------- |
| Channel     | notifications                                |
| Topic       | work.notification.requested                  |
| Contract    | notification\_request\@1.0.0                 |
| Source      | A selected form or workflow event            |
| Destination | A role, screen, subscriber, or selected user |

Use announcements for broadcast messages. Use conversations for direct or grouped discussion. Use notifications for routed system updates that tell someone work needs attention.