NotionApps Messaging How-To Guide
NotionApps Messaging How-To Guide
Support visual: this image shows Messaging as a routing hub. Events can move from screens, workflows, broadcasts, linked apps, and webhooks through validated routes to the destinations that subscribe to them.
Current state: Messaging is now documented as one engine inside Automation (Beta Testing). Use Messaging for channels, direct conversations, group conversations, announcements, notifications, linked app events, and workflow-aware replies. Use the NotionApps Automation Current State Guide for the latest packaging, entitlement, and provisioning language.
Messaging Foundation is the routing and communication layer for a NotionApps application. It lets app events, workflows, announcements, linked apps, webhooks, and subscribers communicate through structured messages.
Use this guide when you need to configure channels, topics, contracts, publishers, subscribers, announcements, request/reply flows, linked app handoffs, or webhook routes.
For the complete cross-tool explanation, examples, support playbooks, and entitlement model, see the Automation, Workflow, and Messaging Support Handbook.
How To Use This Guide
Start with the outcome-first setup path if you are new to Messaging. A maker should be able to say what they want in business language, answer a few numbered questions, and let NotionApps assemble the route objects. Use the concepts section when you need to understand or troubleshoot the channels, topics, contracts, publishers, and subscribers that the platform created.
When To Use Messaging
Use Messaging when the main problem is routing an event.
Good Messaging use cases:
A button click should notify more than one destination.
A workflow should publish a reusable event.
One workflow should ask another workflow for a decision.
An app owner should broadcast a message to all app users.
One app should send an event to another app.
A record change should call a webhook.
An external system should send a structured event into NotionApps.
You need route activity, validation, and subscriber visibility.
Use Workflow when the main problem is doing a sequence of work.
Use Automation when the builder wants a guided recipe that may generate Workflow, Messaging, or both.
What Messaging Is Not
Messaging is not the same thing as email delivery.
Messaging can create the event that should result in an email. A Workflow Notify step, webhook, subscriber, or future delivery provider sends the actual email.
For native outbound email today, use Workflow Foundation's Notify step with:
Messaging is also not a replacement for Workflow. Workflow makes decisions, updates records, waits, branches, and performs multi-step work. Messaging moves structured events to the right places.
Where To Find Messaging
Open an application in the builder and select Automation > Messaging or open the advanced Messaging builder when available.
Messaging contains these pages:
Overview
The progressive messaging home. New work starts with the messaging outcome; existing work shows route setup, testing, failures, or management.
Guided setup
The deeper setup workspace for describing the business result, answering source/destination questions, reviewing route details, creating the channel, contract, publisher, subscriber, and running a dry-run from one action.
Announcements
App-wide in-app broadcast messages.
Channels
Message lanes and allowed topics.
Contracts
Payload schemas and examples.
Publishers
Sources that can publish and destinations that can subscribe.
Activity
Dry-run, publish test messages, and inspect delivery.
Start With Business Language
The Messaging home experience now starts the same way Workflow setup starts: with the maker describing the business outcome.
Instead of asking a maker to begin with a channel, topic, contract, publisher, and subscriber, the setup page asks:
The maker can type normal language, such as:
NotionApps then recommends a route pattern and fills in the technical objects that Messaging needs.
Messaging Overview Progressive Path
Messaging Overview is the safest starting place for a maker who does not already know the channel, topic, contract, publisher, or subscriber.
It shows one current required step:
Start with the outcome: the maker types what the message should accomplish or chooses a starter such as notify, broadcast, conversation, or external event.
What NotionApps will build: appears after the outcome exists. It explains the recommended route and asks for the real source and destination.
Create the messaging route: appears when the source and destination are ready. One action creates or reuses the channel, contract, publisher, subscriber, and optional dry-run path.
Test the route: appears when route objects exist and live publish access allows a dry-run preview.
No required action right now: appears when the app already has messaging work to manage.
Secondary tools such as Continue work, Announcements, Manual objects, and Manage / monitor appear only after there is messaging work to manage. This keeps a new maker focused on the current setup decision instead of exposing every advanced page up front.
What The Outcome Panel Does
The outcome panel helps the maker:
Describe the desired result in normal business language.
Review a recommended setup pattern.
Answer numbered questions about where the message starts, where it should go, and what payload should travel with it.
Review the generated channel, topic, contract, source type, destination type, fields, and example payload.
Build the route in one action. NotionApps creates or reuses the channel, saves and publishes the contract, attaches the publisher, attaches the subscriber, and dry-runs the route when live publish access allows it.
This keeps Messaging consistent with Workflow's direction: the maker describes the work, and NotionApps assembles the engine.
Current Outcome Patterns
Notify the right person
A form, button, screen, or workflow event should alert a supervisor, reviewer, owner, or operations queue.
notifications / work.notification.requested
Broadcast an announcement
An app admin needs to publish a maintenance notice, policy update, or service announcement to everyone.
announcements / announcement.published
Start or continue a conversation
People need a direct or contextual message thread tied to a request, approval, item, incident, or customer record.
conversations / conversation.message.sent
Send an event to another system
A workflow, form, or app event should notify a webhook, linked app, or external system.
integrations / external.event.created
The patterns are starting points. After applying one, the maker can still edit the route details before creating objects.
The Messaging Setup Flow
Messaging Overview uses the same steps progressively. The Guided setup page exposes the full setup workspace when the maker or support team needs to inspect or adjust the route details directly:
Describe what should happen
Type the business outcome. NotionApps recommends a route pattern.
Answer the numbered questions
Choose the source type, source object, destination type, destination object, and payload. The source and destination fields are context-aware, so makers can search screens, forms, controls, data sources, workflows, and saved IDs instead of remembering raw identifiers.
Review the route plan
NotionApps explains the route in plain language and highlights anything missing before it can be created safely.
Build this messaging route
One action creates the required Messaging objects in the correct order and runs a dry-route preview when the app has live publish access. Advanced makers can still inspect or refine the generated channel, contract, publisher, subscriber, and activity afterward.
Example: Notify A Supervisor After A Form Submission
Business outcome:
Recommended pattern:
NotionApps fills in:
Channel
notifications
Topic
work.notification.requested
Contract
notification_request@1.0.0
Source type
form
Destination type
workflow
Example payload
record id, message, recipient, priority
Maker actions:
Choose the actual form in the Source field.
Choose the actual workflow or notification destination in the Destination field.
Review the route plan.
Select Build this messaging route.
Confirm the dry-run shows the expected destination.
Example: Create An App-Wide Broadcast
Business outcome:
Recommended pattern:
NotionApps fills in:
Channel
announcements
Topic
announcement.published
Contract
announcement_broadcast@1.0.0
Source type
workflow
Destination type
screen
Example payload
title, message, severity
For simple app-wide announcements, makers can also use the dedicated Announcements page. Use the guided setup route when the broadcast should be generated by a workflow, screen action, or integration event.
Start In Automation When You Want Guardrails
Use Automation before opening the advanced Messaging builder when the maker knows the business outcome but does not yet know the channel, topic, contract, publisher, or subscriber.
Automation adds three maker-friendly steps:
Preflight checks: confirms Messaging entitlement, route support, app context, saved recipes, generated objects, and Activity visibility.
Plain-language setup: asks when the event happens, who receives it, what result should occur, and what data should travel with the message.
Guided testing: previews the route, exposes blockers, generates objects, then asks the maker to test as the real user and verify Activity.
Use Messaging directly when you already know the route primitives.
Use Automation when the maker says:
After Automation generates the route, open Automation > Messaging to inspect or refine the channel, contract, publisher, subscriber, announcement, or delivery activity. If the maker is starting directly inside Messaging, use Overview first. Open Guided setup when they need the full setup workspace, and use the manual Channels, Contracts, Publishers, and Activity pages only when an advanced builder needs to tune the generated objects.
Core Concepts
Channel
A channel is a message lane.
Examples:
Use lowercase names that will still make sense months later.
Topic
A topic describes the specific event inside a channel.
Examples:
Prefer noun.action or domain.event.
Contract
A contract describes the payload a message should carry.
Example contract:
Contracts help builders catch missing fields before live delivery.
Publisher
A publisher is a source allowed to publish messages.
Publisher examples:
Button.
Screen/form.
Workflow.
External API.
Admin operation.
Linked app.
Subscriber
A subscriber is a destination listening for messages.
Subscriber examples:
Workflow.
App screen.
Announcement.
Webhook.
Linked app.
Admin activity route.
Message
A message is one event sent through Messaging.
It usually has:
Channel.
Topic.
Message type.
Contract name and version.
Payload.
Source.
Subscriber delivery records.
Entitlement Levels
Messaging behavior is gated. The exact source may be subscription, account, app, or admin override.
Common levels:
builder_draft_only
Configure and preview drafts without live delivery.
intra_app_enabled
Same-app messaging, workflows, and announcements.
inter_app_enabled
Linked app routing.
external_api_enabled
Webhooks and external API routes.
admin_enabled
Admin-level operations and elevated support controls.
Use the lowest level that supports the route. Do not request external API access for a simple in-app announcement.
How To Build: App-Wide Service Announcement
Goal:
Step 1: Open Announcements
Open Messaging > Announcements.
Step 2: Create Announcement
Set:
Title
Scheduled maintenance
Message
The app will be unavailable tonight from 9-10 PM Eastern.
Severity
warning
CTA label
View details
CTA URL
Optional status page
Starts at
Optional start time
Expires at
Optional end time
Step 3: Publish Or Activate
Save the announcement. If the builder exposes an active state, activate it.
Step 4: Test
Open several live app screens and verify the announcement appears.
Use this for:
Maintenance windows.
Data freeze notices.
"Timesheets due today" reminders.
Critical policy changes.
Temporary outage warnings.
How To Build: Button Publishes Task Assignment
Goal:
Step 1: Create Channel
Open Channels and create:
Allowed topic:
Step 2: Create Contract
Open Contracts and create:
Fields:
task_id
record_reference
Yes
rec_123
task_title
string
Yes
Review client intake
assignee_email
email
Yes
manager@example.com
due_date
datetime
No
2026-06-30T17:00:00Z
Step 3: Create Publisher
Open Publishers.
Create a publisher:
Source type
Button
Source
Search for Assign task
Channel
tasks
Topic
task.assigned
Contract
task_assignment@1.0.0
Step 4: Create Workflow Subscriber
Create a subscriber:
Subscriber type
Workflow
Destination
Notify assignee workflow
Channel
tasks
Topic
task.assigned
Contract
task_assignment@1.0.0
Step 5: Configure The Workflow
In Workflow, create a workflow triggered by Message received.
Set:
Message channel
tasks
Message topic
task.assigned
Contract name
task_assignment
Contract version
1.0.0
Notify step:
Channel
Email
Recipient
payload.assignee_email
Subject
New task assigned
Body
A task was assigned to you in NotionApps.
Step 6: Dry-Run
Open Activity and publish a test message:
Confirm Messaging finds the workflow subscriber.
How To Build: Workflow Publishes A Message
Goal:
Messaging Setup
Channel:
Topic:
Contract:
Fields:
order_id
record_reference
Yes
customer_email
email
Yes
total
number
No
Workflow Setup
In Workflow, add a Publish message step after the record is created.
Set:
Channel
orders
Topic
order.ready_for_fulfillment
Contract name
order_ready
Contract version
1.0.0
Payload
Map from payload and earlier step output
Example payload:
Subscriber Options
The message can route to:
Fulfillment workflow.
External webhook.
Linked operations app.
Activity-only subscriber for audit.
How To Build: Request And Reply Between Workflows
Goal:
Messaging Concepts
Use a request topic and a reply topic.
Workflow A
Add Send message request.
Set:
Channel
approvals
Topic
approval.requested
Reply channel
approvals
Reply topic
approval.decided
Timeout seconds
86400
Workflow A should then wait for the matching reply or follow the timeout path.
Workflow B
Trigger:
Channel/topic:
Workflow B notifies a manager, records a decision, then adds Send message reply.
Reply payload:
Why This Pattern Helps
Use request/reply when:
One process needs another team to decide.
The first workflow should pause instead of polling.
You need audit records for both request and reply.
You need a timeout path.
How To Build: Linked App Handoff
Goal:
Required entitlement:
Source App
Create channel/topic:
Create contract:
Fields:
customer_name
string
customer_email
email
plan
string
approved_by
email
Create publisher from Workflow or Button.
Destination App
Create subscriber:
Subscriber type
Linked app or Workflow
Destination
Operations workflow
Channel/topic
Match the source route
Test
Use Activity in both apps.
Confirm:
Source message is accepted.
Contract validates.
Linked app delivery occurs.
Destination workflow receives the payload.
How To Build: Webhook Subscriber
Goal:
Required entitlement:
Messaging Setup
Channel/topic:
Subscriber:
Subscriber type
Webhook
Destination
https://example.com/notionapps-webhook
Payload visibility
metadata_only, redacted, or full
Use full only when the receiving service is trusted and needs the whole payload.
Test Payload
Activity And Dry-Run
Use Activity to:
Publish a test message.
Preview subscriber matches.
Verify contract validation.
Inspect recent messages.
See delivery status.
Identify missing subscribers.
Confirm webhook/linked app routing.
Dry-run before live delivery when:
A route has multiple subscribers.
A contract is new.
Payload visibility matters.
Webhooks are involved.
A workflow should start from a message.
When the route was created from Automation, follow the Guided testing panel first:
Then use Messaging Activity for lower-level delivery details.
Messaging With Native Automation Screens
Messaging can send events to workflows, webhooks, linked apps, and native app screens. Native screens make message state visible to app users and owners.
Common pairings:
Broadcast service announcement
Notification Center
Show an ongoing support or approval discussion
Conversation
Route a message to work that a person must claim
Work Queue
Ask a user to approve, reject, or request changes
Decision
Show linked app exchanges
Linked App Exchange
Monitor message-driven operations
Operator Console
For detailed setup and troubleshooting for each screen type, see the Native Automation And Operational Screen Guides.
When configuring a native screen:
Add the screen in the application builder.
Choose the screen type by its distinct icon and title.
Open the screen configuration.
Set Listen scope.
For conversation/message screens, search channel, topic, conversation, or correlation suggestions instead of typing IDs.
For linked app screens, search linked applications instead of copying application IDs.
If the action should send the user somewhere after they acknowledge or reply, choose the After-action screen from the context-aware picker.
Hidden screens can appear in the picker. This is expected when the screen is hidden from navigation but still reachable through a workflow or messaging route.
Private Conversations Versus Announcements
Use Conversation when the message belongs to one record, workflow run, review, ticket, or support exchange. Use announcements or Notification Center when the message is for everyone.
Private conversation pattern:
Announcement pattern:
For private conversations, include participant fields in the payload whenever possible:
This lets NotionApps show the conversation to the right people without exposing raw route IDs to the maker or the end user.
Troubleshooting
No Matching Subscriber
Check:
Channel spelling.
Topic spelling.
Subscriber active state.
Contract name/version.
Entitlement level.
Source and target app IDs for linked app routes.
Contract Validation Fails
Check:
Required fields exist.
Email fields contain valid email strings.
Number fields are numbers.
Date fields are ISO-like date/time values.
Field names match exactly.
Workflow Does Not Start From Message
Check:
Subscriber type is
Workflow.Subscriber destination is the correct workflow.
Workflow trigger is
Message received.Workflow channel/topic/contract match the message.
Workflow is published.
Announcement Does Not Appear
Check:
Announcement is active.
Starts at and expires at are correct.
Severity is allowed.
User is viewing a live app screen.
Messaging entitlement supports announcements.
Webhook Does Not Receive
Check:
Entitlement allows external API/webhook delivery.
Endpoint URL is valid.
Subscriber is active.
Payload visibility is not blocking needed fields.
Activity shows delivery attempt or failure.
Best Practices
Use channel names for domains, not one-off actions.
Use topic names for specific events.
Use contracts for every reusable route.
Include realistic payload examples.
Keep contract versions stable once published.
Use new contract versions for breaking payload changes.
Prefer Workflow when you need decisions or multi-step work.
Prefer Messaging when you need routing, subscribers, linked apps, or webhooks.
Prefer Automation recipes when a non-technical builder owns the setup.
Use Activity dry-run before publishing a new route.
Use native Notification Center or Conversation screens when messages need to remain visible inside the app.
Configure native screen source binding from context-aware pickers, not memorized IDs.
Confirm hidden screens are intentional route destinations before removing them.
Messaging Checklist
Before going live:
Automation Preflight has no Messaging blockers when the route was created from a recipe.
Automation Guided testing preview has run when a non-technical maker owns setup.
Entitlement supports the route.
Channel exists.
Topic is allowed or intentionally open.
Contract exists with realistic examples.
Publisher source is correct.
Subscriber destination is correct.
Payload visibility is intentional.
Dry-run finds the expected subscriber.
Workflow subscribers are published.
Webhook subscribers have valid URLs.
Announcement schedules are correct.
Native message screens have the right listen scope, channel, topic, and action destination.
Activity shows expected route behavior.