Notifications

Notifications alert your team when something needs attention — most commonly when an AI agent escalates a conversation to a human. This guide explains how notifications work, how to configure notification rules, and how members can control the channels they receive alerts on.

For setting up escalation behavior in workflows, see Escalation & Human Handoff. For per-member channel preferences, see Notification Preferences.

How Notifications Work

When an event occurs (such as an AI escalation), the system:

1. Looks up notification rules that match the event type and current workflow
2. For each matching rule, identifies the target member
3. Checks the member's notification preferences to see which channels are enabled
4. Delivers the notification only on channels that both the rule and the member preferences allow

Both layers must agree for a notification to go out:

This design lets workspace admins configure workspace-wide routing while individual members retain control over how they're contacted.

Notification Rules

Notification rules define who gets notified, on which channels, and for which events.

Viewing Notification Rules

Go to Settings → Workspace → Escalation → Notification Rules.

Each rule shows the recipient member, the notice type, the workflow scope (or workspace-wide), and the configured channels.

Creating a Notification Rule

1. Go to Settings → Workspace → Escalation
2. Scroll to the Notification Rules section and click Add Rule
3. Configure the rule fields:

4. Click Save.

You can create multiple rules to notify different team members for the same event.

Editing and Deleting Rules

Click Edit next to any rule to update its fields. Click Delete to remove a rule permanently.

Workflow-Scoped vs. Workspace-Wide Rules

Rules can be scoped to a specific workflow or apply across the entire workspace:

• Workflow-scoped rules fire when an escalation happens in that specific workflow. They take priority over workspace-wide rules.
• Workspace-wide rules (no workflow selected) fire for any escalation, regardless of which workflow triggered it. These fill in when no workflow-specific rules match.

Use workflow-scoped rules when different workflows need different on-call contacts. Use workspace-wide rules for a general escalation path that applies everywhere.

Channels

Three notification channels are available. Each can be enabled or disabled independently on both the rule and the member's preferences.

SMS

The most common channel for real-time alerts. Sends a text message with the escalation details and a direct link to the chat.

Requirements:

• The member must have a phone number set in their profile.
• The member's notify_sms preference must be enabled (it is by default).

Email

Sends an email with escalation details and a link to the chat. Useful for non-urgent notifications or for team members who prefer email over SMS.

Requirements:

• The member must have an email address set in their profile.
• The member's notify_email preference must be enabled (disabled by default — enable it per member as needed).

Voice

Voice call notifications are planned but not yet available. The channel option appears in the UI and API but does not send calls. Use SMS or email in the meantime.

Escalation Flow Walkthrough

Here is what happens end-to-end when an AI agent escalates a conversation:

1. AI calls talk_to_human — triggered by the AI agent when it needs human help, or when the member asks to speak with a person.

2. Chat state updates — the chat is flagged as needs_response. If Pause on Escalate is enabled, the AI stops replying.

3. Notification rules fire:

   • The system looks for rules with notice type tool.escalate
   • Workflow-scoped rules for the current workflow are checked first
   • Workspace-wide rules fill in any remaining recipients
   • For each rule, the target member receives an alert on their enabled channels

4. Member message sent — the member (customer) sees a message in the chat based on the time of day:

   • During business hours: Online Hours message template
   • Outside business hours: Offline Hours message template
   • After notifications are sent: Notification Sent message template
   • When chat is paused: Chat Paused message template

5. Teammate responds — once a team member opens the chat and replies, the conversation continues with the human in the loop.

See Workspace Settings → Escalation to configure message templates and business hours.

Member Notification Preferences

Each member has per-channel preferences that act as an opt-out override. If a member has SMS disabled, they won't receive SMS notifications even if a rule is configured to send them.

To update a member's preferences, go to People → Members, open the member, and use the Notifications section in the edit form.

See Notification Preferences for full instructions, including bulk CSV updates.

API Reference

Manage notification rules programmatically via the REST API.

Base URL: https://api.gravityrail.com/api/v2/w/{workspace_id}

List Rules

bash

Requires automations:read scope.

Create a Rule

bash

Requires automations:admin scope.

Update a Rule

bash

Requires automations:admin scope. Include only the fields you want to change.

Delete a Rule

bash

Requires automations:admin scope.

Member Notification Preferences

Member preferences are updated through the Members API using the notifySms, notifyEmail, and notifyVoice boolean fields:

bash

Permissions

Known Limitations

• Voice notifications — The notifyVoice field is available in the API and UI but does not yet send calls. Voice call delivery is planned for a future release.
• Acknowledged state — Notifications track read, dismissed, and an acknowledged_at timestamp, but there is currently no UI or API endpoint for acknowledging a notification. The acknowledged_at field is reserved for a future "I'm handling this" status distinct from simply reading the notification.
• Single notice type — Only tool.escalate is supported as a notice type today. Additional event-driven types are planned.

Tips

• Set up at least one workspace-wide rule — Even if you build workflow-specific rules later, a workspace-wide fallback ensures escalations don't go unnoticed.
• Check member phone numbers before enabling SMS — If a member has no phone number on file, SMS notifications will silently fail. A warning appears on the member edit form.
• Use the Offline Hours template — Members who escalate outside business hours need to know when to expect a response. A short message is much better than silence.
• Audit rules when team members change — When someone leaves or changes role, review their notification rules and reassign them so escalations still reach the right person.
• Test before going live — Use the Qualifications feature to run test conversations and confirm your escalation and notification setup fires as expected.

Related

• Escalation & Human Handoff — Configure escalation triggers, priority members, and ability-level settings
• Notification Preferences — Per-member channel opt-ins and opt-outs
• Workspace Settings → Escalation — Message templates, business hours, and pause behavior
• Business Hours — Controls the Online vs. Offline message branch
• People → Members — Member management, including phone numbers and email addresses
• Actions — Event-triggered automations that can also send notifications