Gates & Channels
Connect a flow to the outside world — a chat widget, a voice call in the browser, a phone number, Slack or WhatsApp.
A gate connects one external channel to one flow of a project. Every message that arrives on the channel runs that flow; the flow's answer goes back out the same channel. The channel is pluggable: each one is a small adapter that describes its own settings, so adding a channel does not change how gates, rules or logs work.
| Channel | Status |
|---|---|
| Web Widget | Available |
| Slack | Available |
| WebRTC Voice | Available |
| Phone (SIP) | Available |
| Available |
You bring your own accounts and credentials: UnderOcean is never a customer of the channel provider. Credentials you enter are stored encrypted and are never returned by the API.
Web Widget
A Web Widget gate can be used two ways:
- Embed script — paste one
<script>tag into your website and a chat bubble appears. - Public link — a standalone chat page you can share or open directly.
<script src="https://widget.example.com/widget.js" data-gate="<public id>" async></script>Both are shown (ready to copy) behind the Setup links (info) button of the gate row. The widget is served from its own address (your administrator configures its public address); on that address only the widget is reachable.
Where it may be embedded. The embed script works only on the websites listed under Allowed websites
(for example https://example.com or https://*.example.com). Leave the list empty and embedding is disabled;
the public link keeps working unless you turn it off. Entries must use https (http is accepted only for
localhost while developing), and a wildcard must sit under one site: https://*.com or https://*.co.uk are
refused. This is enforced by the visitor's browser (it refuses to show the widget on any other site); it does not
hide the chat itself, which anyone who knows the gate's public id can reach, within the Messages per minute limit.
If you turn the public link off and leave no allowed website, the widget has no way in left and stops
answering altogether.
Look and feel. Title (cannot be blank), welcome message (stays at the top of the conversation), brand color, logo, suggested questions (shown until the first message), launcher position
and icon. The brand color carries white text, so colors too light to read (a contrast below 3:1 against white,
such as #ffffff) are refused.
Layout. popup (default) floats above the page; drawer is a full-height panel of 320–640 px at the launcher's
side, and the widget tells the page when it opens or closes (open / close events) so the page can make room.
On screens up to 480 px wide both fill the screen.
Theme. Corner radius, Logo width / height / shape / fit (contain shows the whole logo, cover fills the frame),
Card picture fit and Font family (fonts installed on the visitor's device) are plain settings.
For anything else use Custom CSS (up to 20,000 characters). Style the chat with the stable classes
.uo-widget, .uo-widget-header, .uo-widget-logo, .uo-widget-title, .uo-widget-reset, .uo-widget-close,
.uo-widget-messages, .uo-widget-message (--user / --assistant), .uo-widget-quick-replies,
.uo-widget-quick-reply, .uo-widget-cards, .uo-widget-card (with -image, -badge, -title, -subtitle,
-price, -status, -rank, -tag, -action), .uo-widget-form, .uo-widget-input, .uo-widget-send,
.uo-widget-home, .uo-widget-start, and the variables --uo-primary, --uo-radius, --uo-logo-size, --uo-font.
On your own page the launcher, frame and teaser carry .uo-widget-launcher, .uo-widget-frame, .uo-widget-teaser.
The CSS runs inside the chat frame only. Anything that loads files, runs code or hides either is refused when you save:
url(), image(), image-set(), cross-fade(), element(), paint(), src(), expression(), @import, @font-face,
@namespace, @charset, javascript:, -moz-binding, behavior:, < and backslash escapes.
Behaviour. Teaser message (with delay and an optional starter) shows a bubble next to the launcher; clicking it opens the chat and, when no conversation has started, sends the starter. Home screen greets new visitors with a start page before the chat. Reset button adds a button to the header that starts a fresh conversation. Conversation memory in the browser is per tab (default) or persistent across visits.
Texts. Input placeholder, waiting text, start / reset / close / launcher button texts, error message and the reply to the reset command can all be set per gate, so the widget can speak your visitors' language.
Like every UnderOcean chat surface, the widget renders markdown and has a multi-line input. Unlike the internal surfaces, it does not show the flow's step-by-step trace or reasoning to anonymous visitors (a deliberate product decision): the visitor sees a "Thinking…" indicator, then the answer and its sources. The trace stays available to you in the gate's message log.
Who is the visitor?
Visitors are anonymous. The server gives each conversation a signed token that proves it owns that conversation
(and its history); there is no account. Messages are rate limited per visitor IP address. A token that has
expired or does not belong to the widget starts a new conversation, and the answer says so (session_renewed).
Turn on Allow file uploads to let visitors attach documents to their messages (a paperclip appears in the chat; off by default, see Files & Attachments).
Slack
A Slack gate answers direct messages to your Slack app and @mentions in channels (a mention starts a thread and the answer is posted in it). It uses your own Slack app, so nothing about your workspace is shared with anyone else.
- In Slack, create an app (Create New App → From a manifest) and install it to your workspace. Copy the
Bot User OAuth Token (
xoxb-…) and the Signing Secret. - In UnderOcean, create a gate with the Slack channel, pick the flow and paste both values. They are stored encrypted and never shown again.
- Open the gate's Setup links (info) button. Paste the Request URL into your Slack app under both Event Subscriptions and Interactivity (or paste the shown app manifest into the app's App Manifest page, which sets everything at once). Slack verifies the URL when you save it, so the gate must be active.
- Subscribe to the bot events
app_mentionandmessage.im, and give the bot the scopesapp_mentions:read,chat:writeandim:history(plusfiles:readif the gate should read shared files). Enable the app's Messages tab so people can write to it.
The Request URL is built from the public address of the app, so that address must be reachable from the internet. Slack must receive an answer within three seconds, so the flow runs in the background and the reply is posted when it finishes; a failed run answers with the gate's error message. Answers are posted as Slack-rendered markdown, and Quick Replies appear as buttons.
Turn on Read shared files to let people share documents with the bot (see
Files & Attachments); apps created before this option need the files:read scope added and
the app reinstalled. Not supported yet: a typing indicator. A follow-up in a channel thread needs a new @mention.
A WhatsApp gate answers messages sent to your own WhatsApp Business number through your own Meta app (the WhatsApp Business Cloud API).
Meta's WhatsApp Business terms restrict general-purpose AI assistants and require an opt-in from every contact, a prompt path to a human, and respect for opt-out requests. Use this channel for a focused business use case such as customer support. You are responsible for complying with Meta's policies.
- In the Meta App Dashboard, add the WhatsApp product to your app and note the Phone number ID, a permanent access token (System User) and the App secret.
- In UnderOcean, create a gate with the WhatsApp channel. Enter the phone number ID, the human escalation message, the three credentials, and a verify token of your choice. Secrets are stored encrypted and never shown again.
- Open the gate's Setup links (info) button. In the Meta dashboard (WhatsApp → Configuration) set the
Callback URL and the same verify token, then subscribe to the
messagesfield. Meta verifies the URL when you save, so the gate must be active.
Behavior worth knowing:
- Human escalation. Anyone who sends one of the escalation keywords (default
human,agent) gets your escalation message instead of a flow run. It is required, because WhatsApp requires automated chats to offer a clear way to reach a person. - Opt-out. Sending
stoporunsubscribeends all replies to that person until they sendstart. These keywords work at any hour, and you can change the keywords and confirmation texts. - Unsupported content. Images, audio, locations and contacts are not read; the sender gets your Reply to unsupported content. Documents get the same reply unless Read shared documents is on, in which case they are read like any other attachment.
- Quick Replies appear as up to three buttons, or as a list of up to ten choices when they don't fit buttons.
- Typing indicator. The message is marked as read and WhatsApp shows "typing" while the flow runs.
- 24-hour window. WhatsApp only allows free-form replies within 24 hours of the user's last message; the bot never starts a conversation on its own.
- One number per app. A Meta app has one webhook URL, so a gate answers only for the phone number you entered.
- Allowed senders are phone numbers in international format, with or without
+.
The Callback URL is built from the public address of the app, which must be reachable from the internet.
Voice (WebRTC gate and Web Widget voice mode)
A WebRTC Voice gate lets people talk to a flow from the browser. It serves a ready-made call page (Public link) and
an embeddable SDK (UoVoice.connect({ gate, token })); the Web Widget can also offer a voice mode next to its chat. A
call runs the flow turn by turn: speech-to-text turns what the caller says into the message, the flow answers, and
text-to-speech speaks the answer sentence by sentence while the flow is still writing. The caller can interrupt
(barge-in), and silence is handled by a no-input timeout with retries.
- Providers. Speech comes from the project's TTS and STT AI Providers; the gate (or a Voice Settings step) picks the provider, voice, language and speed. A flow can switch them mid-call.
- Who may call. List your site under Allowed websites, or turn on Token required and mint a single-use token from
your backend with
POST /v1/gates/{id}/voice-tokens(Consumer API) — only your signed-in users can then start calls. Limits per gate: maximum call length, simultaneous calls and (WebRTC) daily minutes. - Voice steps. Voice Settings, Play Audio and Hang Up work on every voice channel; a flow written for chat keeps working, because other channels ignore them.
- What the flow receives.
input.messageis what the caller said (or the typed text / tapped choice),input.channel.typenames the channel andinput.channel.eventiscall_starton the first turn,no_inputafter a silence. - Observability. The Flow Builder's Voice test runs the draft flow with the microphone and shows the step trace next to the transcript. Public pages show the transcript only when the gate allows it; the Web Widget never shows step traces to visitors.
Phone (SIP)
A Phone (SIP) gate answers calls to a phone number and can place calls from it. You bring the carrier account and the number — UnderOcean never provides lines or numbers.
- Add a Carrier (Carriers, organization admins): the SIP server, transport (UDP or TCP), optional credentials (stored encrypted, never returned), the addresses the carrier calls from, and the audio codecs (G.711 μ-law / A-law). Templates prefill the server of well-known carriers; nothing in them is a credential.
- Create the gate: phone number (E.164), the carrier, the flow and the voice settings. One number belongs to one active gate, and calls from a carrier only reach numbers of gates that use that carrier.
- Point the carrier's inbound routing for the number at the platform's SIP address.
Calls from addresses that are not on the carrier's list are refused. The flow talks to the caller like on any voice channel, plus two phone-only steps: Collect Digits (the caller presses keys, for example a PIN) and Transfer Call (connect the caller to a person; limited to the gate's Allowed transfer prefixes).
Outbound calls are off until the gate's owner turns them on, and always bounded by the gate: allowed destination
prefixes (required), calling hours in a time zone, a daily call limit and the simultaneous-call limit. Your backend starts
a call with POST /v1/gates/{id}/calls (Consumer API, scope gates:connect); the flow runs with call_start once the
call is answered. Consent, recording notices and do-not-call lists are your responsibility. Calls are not recorded by the platform.
What the flow receives
Each message starts a flow run with this input:
| Field | Meaning |
|---|---|
input.message | The visitor's text, extended with the text of attached files (see Files & Attachments) |
input.channel | type, conversation_id, user_id, display_name, attachments of the sender (file name, type and size) |
input.attachments | The files of the conversation as structured data — only when files were sent |
input.history | Recent messages of the conversation — only when Remember the conversation is on (the default for new gates) |
input.history is a list of {"role": "human" | "assistant", "content": "..."}, oldest first, holding at most
Messages kept entries (2–100, default 20). The conversation also keeps one session, so session_storage
values persist between messages.
Rules
Every gate has channel-independent rules. Each channel shows only the ones it supports (the Web Widget supports all except Allowed senders):
- Messages per minute (default 20, per sender). Messages above the limit are rejected.
- Business hours (off by default). Outside them the flow does not run and the sender gets the Out-of-hours message instead. Pick the timezone from the list (new rules start in your own timezone), the From and Until times and the open days. An Until time earlier than From is a shift over midnight (for example 18:00 to 09:00); the selected days are the days the shift starts.
- Reset command (default
/reset) — sending exactly this text (letter case and surrounding spaces are ignored) starts a fresh conversation. The Web Widget then also clears the conversation from the visitor's screen. Leave it empty to turn the command off. - Error message — what the visitor sees if the flow fails (raw errors are never shown to anonymous visitors).
- Remember the conversation — see above.
- Allowed senders — for channels that identify senders (Slack: user IDs such as
U012ABC; WhatsApp: phone numbers). Messages from anyone else are ignored.
Quick Replies
The Quick Replies step offers the user a few tappable choices alongside a message. Each channel shows them natively (the Web Widget shows chips, Slack and WhatsApp show buttons). Tapping a choice sends its title back as the next message, so the flow keeps branching on plain text.
For dynamic choices set Options from to a list built earlier in the flow. In the Web Widget a tapped choice also
sends its id and payload to the flow (input.reply.id, input.reply.payload). Both come from the visitor's browser,
so a flow must treat them as untrusted input.
Cards, events and the host page (Web Widget)
The Cards step shows up to 10 cards under a message; other
channels show the message only. A card has a title, subtitle, https picture, a badge on the picture, a price, a status
(neutral, success, warning or danger), a position number, up to 4 tags and up to 4 actions. Set Layout to carousel
to scroll the cards sideways and Image ratio to 1:1, 4:3 or 16:9. The Event step sends a named, data-only event to the page that embeds the widget.
The loader (widget.js) exposes window.UoWidget to that page (a uo-widget:loaded event fires on window once it exists):
UoWidget.on("cart.updated", (data) => refreshCart(data)); // an Event step
UoWidget.on("action", ({ id, payload }) => addToCart(payload)); // a card action of type `host`
UoWidget.on("ready", () => UoWidget.identify({ customerId: "c-9" }));
UoWidget.on("open", () => document.body.classList.add("chat-open"));
UoWidget.on("turn:end", ({ status }) => hideTyping()); // done | reply | error | interrupted
UoWidget.on("outgoing", ({ text, label }) => track(text));
UoWidget.on("incoming", ({ text }) => track(text));
UoWidget.open(); UoWidget.close(); UoWidget.toggle();
UoWidget.send("ORDER_STATUS", { label: "Where is my order?" }); // visitor sees the label, the flow gets the text
UoWidget.startConversation("hello"); // opens the chat; sends only when no conversation is under way
UoWidget.reset(); // start a fresh conversationThe flow receives the visible text as input.message and the label as input.label. Event step names may not be
open, close, ready, action, outgoing or incoming: the widget uses them itself. startConversation() and the
teaser starter send nothing when a conversation is already under way.
identify(context) data (at most 2,000 characters as JSON) reaches the flow as input.channel.context with every
message. The page and the visitor's browser are the source of that data, so it is untrusted: do not base
authorization on it. Messages travel by postMessage only between the widget and the page that is allowed to frame it,
and events and actions are relayed through the visitor's browser, so never put in them what the visitor may not see.
Observability
Every message in and out is logged per gate (the Message log button of the gate row), including messages that were blocked by a rule. Each reply links to the full step trace of the run that produced it — the trace the end user cannot see in an external channel stays inspectable here. Runs started by a gate are marked as such and use the flow's saved version, so they are reproducible.
Managing gates programmatically
Gates are available in the Consumer API and as MCP tools (list_gates, get_gate, list_gate_channel_types,
list_gate_carriers, list_gate_messages, create_gate, update_gate, and place_outbound_call for phone gates) under the
gates:read, gates:write, gates:delete and gates:connect scopes. The scopes are
opt-in: no key preset includes them except the API-key-only Full access preset, and keys created before scopes existed (legacy_full) do not get them
either. Create a key with "scopes": ["gates:read", "gates:write"] to manage gates. MCP tools never accept credentials, never mint
voice tokens, and there is no delete tool. Voice gates (WebRTC and phone) can be created over MCP too: the speech providers
and voices to use come from list_stt_providers, list_tts_providers and list_provider_voices (scope providers:read),
and a phone gate's carrier from list_gate_carriers. Carriers, provider keys and phone numbers themselves are added in the UI.
Related
MCP (Model Context Protocol)
Connecting agents to external tools and services via an open integration standard.
Files & Attachments
Send documents (PDF, Word, Excel, PowerPoint, text) with a message so the flow or agent can read them — in the app, the API, share links, the Web Widget, Slack and WhatsApp.