Skip to main content

​
Quick-action deep links

Every per-channel messaging page in the Orbit dashboard supports a ?dialog=compose URL parameter that opens the compose dialog automatically on mount. Combine it with channel-specific query params (recipient, template, conversation context) to build deep links from internal tooling, contact lists, or browser bookmarks. This is the same pattern used by the dashboard’s own Quick Actions menu and the contact list’s “Send message” button.

​
Supported pages

The dashboard’s top-bar Quick Actions menu always uses these URLs; the entry chosen reflects the channels the operator’s organisation has connected.

​
Supported params by channel

The dialog hand-off is uniform: ?dialog=compose always opens the compose dialog. What differs by channel is which additional query params the page reads to pre-fill fields. The matrix below covers the params the pages actively consume. A — means the channel page ignores that param; appending it is harmless but does nothing. On channels that support a param, the value is captured once on mount and forwarded into the dialog, so a repeat navigation with a different value re-opens with the new recipient/template/thread.

​
Pre-fill the recipient

Append ?to=<E.164 or address> along with dialog=compose:
URL-encode the + as %2B. Email addresses pre-fill as-is — ?to=alex%40example.com&dialog=compose.

​
Pre-fill a template

For SMS / WhatsApp / Email (the three channel pages that resolve the shared template library), append template=<template_name>:
The dialog opens with the template selector pre-set. Variables are presented as empty fields the operator must fill — the deep link cannot supply variables (this is a deliberate guard against templating-injection from external links). RCS and Viber do not read ?template — RCS uses demo messages / rich cards scoped to the account, Viber does not register shared-library template handlers — so omit it.

​
Thread into an existing conversation

For channels whose compose dialog can scope to an existing thread (currently WhatsApp, RCS, Viber), include conversation=<conversation_id>:
The compose dialog opens scoped to that conversation thread; recipient + sender (WABA / RCS bot / Viber sender) are auto-resolved from the conversation row. SMS, Email, Push, and Fax ignore this param.

​
Common combinations

​
Invalid input behaviour

Deep links validate at the dialog level, not at the URL level. The page always opens the compose dialog, even when a parameter is wrong, so a malformed link comes up empty rather than failing silently:
  • Invalid E.164 to — the dialog opens with an empty recipient field. For example, ?to=+141-5555&dialog=compose opens the dialog with the recipient blank so the operator can fix it; the dialog’s own Zod schema flags “Enter a recipient in E.164 format” if the operator then presses Send.
  • Unknown template name — the template selector remains unset; the operator simply picks a template by hand. For example, ?template=order-shipped-bk2&dialog=compose still opens the dialog and the operator recovers by selecting a template inside it.
  • Unknown conversation id — the dialog opens scoped to a fresh thread (no conversation bound); the conversation-scoping simply falls back to the equivalent of a no-conversation link.
(SMS/Email treat ?to the same way — they auto-open on an invalid input so the operator lands in the dialog, not on the bare page, and the inline Zod check guides the fix on Send.)

​
Role guards

The operator’s role still controls whether the compose dialog renders at all. A viewer-tier role lands on the channel page but the compose dialog refuses to mount — the URL alone cannot turn a read-only role into a sender. Grant compose through the role’s message-send permission, never by crafting a URL.

​
Locale prefix

Every URL is locale-prefixed: /${locale}/messages/.... When building from JS / TS, read the locale from the dashboard’s useLocale() hook (or the URL path on a server-rendered page); when building from external systems, default to the operator’s preferred language or en.

​
Cross-channel dispatch from Quick Actions

The dashboard’s Quick Actions component normalises a “Send message” intent into the right channel automatically. If you build a custom Quick Action via the Orbit SDK, prefer the same logic over hard-coding /messages/sms:
This avoids the previous behaviour where every Quick Action sent the operator to SMS even when SMS wasn’t connected.

​
What the dialog will NOT do

  • Auto-send — the dialog always opens in compose mode and waits for explicit operator confirmation. There is no &auto_send=true.
  • Pre-fill body content — ?body= is intentionally unsupported; we don’t want a malicious link from outside the org to draft messages on behalf of the operator. Use templates for repeatable content.
  • Bypass role guards — the operator’s role still controls whether the compose dialog renders at all. A viewer-tier role lands on the channel page but the compose dialog refuses to mount.

​
See also