Chat gateway (talk to your agents from twelve chat apps)
The chat gateway lets you message your agents from Telegram, Slack, Discord, Mattermost, Matrix, Signal, iMessage, Home Assistant, SMS, WhatsApp, Teams or Google Chat. You make a bot account on the chat app, paste its keys into Settings, and choose who may talk to it. Each chat with the bot is one agent session, the agent's answer comes back in the chat, and you can allow or deny the agent's tool requests from the chat. Nothing is on until you switch it on in Lab.
On this page
What it is
The gateway turns a chat message into work for an agent and the agent's answer into a chat message.
- Named bots. You can run several bots at once (up to 20), each on one chat app account, each with its own keys, lists and limits. One chat app account can drive only one bot.
- Who may talk. A bot answers only people you have allowed. A stranger either gets a one-time pairing code that you approve, or gets no reply at all.
- One session per chat. A direct chat, a group, a channel, a thread or a topic each get their own
agent session. A follow-up goes to the same session;
/newstarts a fresh one. - Answers come back once. The agent's final answer is sent to the chat, split at the app's message limit. Side remarks and tool output never leave your computer through a bot.
- Approvals in chat. When the agent wants to run something that needs your permission, the chat
shows the request with Allow, Allow for this session and Deny (or
/approveand/denywhere the app has no buttons). A chat answer can never allow what Safety refuses. A change to a safety, Lab or feature setting that always raises a card, a restore from a backup, erasing data, rolling the app back or deleting a project is answered only in the app, so the chat just says it is waiting. - Commands and voice. Commands such as
/stopand/modelsteer the session. Voice notes are turned into text first, using your own speech key.
Where to find it
- Lab switch: Settings, Lab, Chat gateway (off by default). Turning it off disconnects every bot, closes the local webhook listener and releases the power hold.
- Bots: Settings, Chat gateway. Add a bot, follow its setup guide, paste the keys, choose who may talk to it, then switch it on. The same screen lists the chats, the allowed senders and groups, pending pairing requests and any open requests waiting on an answer.
- Scheduled jobs: with Scheduled jobs plus on, a job's Deliver to list offers Bot chat.
- Phone: the Omniscio phone app shows pairing requests and can approve or decline them and switch a bot on or off. Adding or removing the people a bot answers, changing a bot's settings, starting a chat over and entering keys can only be done on the computer.
How it behaves
Who may talk to a bot
- Direct messages follow the bot's setting: Pairing (an unknown sender gets a code, you approve it), Allowlist only (no code, only people you listed) or Off. iMessage, Signal and SMS bots offer only Allowlist or Off, so a stranger who texts you never receives a pairing message.
- Empty lists let nobody in. A refusal is silent, except for the pairing code.
- Groups need the group on the bot's group list and the sender on the sender list, and by default an @-mention of the bot or a reply to it. Allow all senders never applies in a group.
- Pairing codes last one hour, at most three are waiting per bot, one per sender, and the code is
shown only to the person who asked. Approve in Settings, or type
/pair <code>in a direct chat with the bot if you are already allowed. The list shows the chat app's fixed id beside the display name, because a name is easy to imitate. - Five wrong codes in an hour lock that sender out for 24 hours with no reply. A declined request is remembered for 24 hours, so the sender cannot ask again or raise another alert.
- Allow all senders is off by default and shown with a warning. Someone admitted only by it starts read-only, unattended sessions and can never answer an approval.
- Bots and your own echo are ignored. Messages the bot sent itself or that another bot sent are dropped before anything happens, and messages older than 24 hours or from before you switched the bot on are dropped too. A new bot never replays a chat's history.
Sessions, costs and limits
- Which project. A bot's sessions run in the project you choose for it, or in a Chat gateway
workspace.
/sethome <project>changes it from a direct chat if you are allowed. - The same sign-in as anywhere. A chat session starts through the normal session start, so your Claude sign-in and every spending gate apply.
- Permission floor. A session started by an allowed person runs at the Guarded level at most; one started by someone admitted only by Allow all runs read-only. Full trust in your settings does not remove the requests of a chat session. In a group, anyone other than the person who started the session is held at Guarded and cannot answer requests.
- Unproven senders. On SMS, Signal and Home Assistant the app cannot prove who wrote a message, so requests are never offered there ("answer in Omniscio") and those sessions start read-only.
- Spending. A chat waits out a cooldown between new sessions (15 seconds by default, 5 seconds to 10 minutes) and a bot stops at a daily cap of new sessions (50 by default, up to 500). Each chat gets 30 turns an hour (up to 120) and each bot 300 turns per UTC day (up to 2,000); a retry counts as a turn. Each refusal is told in the chat.
- Fenced text. Every message, voice transcript, sender name and chat title reaches the agent inside an untrusted-content frame, so a message cannot pose as your own instructions. Text is capped at 16,000 characters.
- Restarts. The app records each event before handling it. A reconnect, a resend or a restart never handles the same message twice, and an unfinished message younger than ten minutes is picked up once.
Replies and requests
- Replies. The final answer of each turn is sent once, with secrets masked, cut at the app's limit (4,096 characters on Telegram, 2,000 on Discord, 3,000 on Slack, 16,000 on Matrix and Mattermost, and so on), and sent again as plain text if the app refuses the formatting. If delivery fails, a note is written into the session and one alert is raised for the bot. An agent's @channel, @here or @everyone is defused so a reply never notifies a whole room.
- Requests. Hardline refusals, never-allow rules and protected folders decide before a chat ever
sees a request. An allowed request is shown with buttons (Telegram, Slack, Discord, WhatsApp, Teams,
Google Chat) or with
/approve <number>,/approve <number> sessionand/deny <number>(Mattermost, Matrix, iMessage). Only an allowed person in that chat can answer. The first answer wins, and a request answered on the desktop is marked "answered in Omniscio" in the chat. - Long requests. A request longer than 500 characters shows its start, an ellipsis and its last 200 characters, and offers only Deny and "answer in Omniscio", so a harmful tail cannot hide under an Allow.
- Desktop-only actions. A command-line action that only you at the desktop may approve is never offered in a chat.
Commands
| Command | What it does |
|---|---|
/new |
Starts a fresh session for this chat. |
/stop |
Stops what the agent is doing in this chat. |
/status |
Says what this chat's session is doing. |
/retry |
Sends your last message again (counts as a turn). |
/usage |
Shows tokens and cost so far. |
/sessions |
Shows this chat's session. |
/model <name> |
Switches the model, checked against the engine's own list. |
/personality <name|default|none> |
Sets the personality. |
/sethome <project> |
Chooses the project for new sessions (allowed person, direct chat). |
/approve <number>, /deny <number> |
Answers a waiting request. |
/pair <code> |
An allowed person approves a pairing request by its code. |
/help |
Lists the commands and up to ten skills. |
/<skill> |
Asks for a skill the bot's project lists. |
Every command acts on this chat's session or this bot only. A word that is not a command or a skill gets the help text, never a paid agent turn.
Voice
- Voice notes in. Notes up to 10 MB and 10 minutes are transcribed with your own speech key and then treated like text. Only a Groq or xAI key can transcribe a recording here (OpenRouter has no transcription); without one the bot says voice notes need such a key. Voice notes are not read on iMessage.
- Spoken replies out are off by default, billed to the bot with a $5 a day cap, sent as an mp3 audio file in addition to the text, and not available on Teams, Google Chat, Home Assistant, SMS, Signal or iMessage.
Staying connected
- Close to tray. Bots connect only while Omniscio runs. When you enable your first bot, Settings offers a one-click card that turns on close-to-tray, so closing the window keeps the app (and the bots) running. The gateway never changes how the window closes by itself.
- Keep running. An optional setting (off by default) keeps the computer from suspending while a chat session is actually running. It never keeps the screen on, and an idle connected bot holds nothing.
- After sleep every bot reconnects at once.
- One bot, one computer. If two computers run the same bot, both answer. Run each bot on one.
Webhook platforms (WhatsApp, Teams, Google Chat)
These apps send messages to an address, so the gateway runs a small listener on this computer only
(127.0.0.1, port 19531 by default, changeable in Settings), and only while a webhook bot is on. It
checks each request's signature or signed token before reading it, accepts bodies up to 1 MB, and rate
limits each bot. The apps need a public address, which you provide with Tailscale Funnel: once the
listener is up and Tailscale is signed in, online and allowed to use Funnel, Settings shows the exact
command, tailscale funnel --bg --https=8443 <port>, and each bot's address (ending in
/hooks/<platform>/<bot id>). You run the command; the app never does. If the listener or Tailscale is not
ready, Settings says which part is missing.
Setting up each app
In every case create the account on the chat app, open Settings, Chat gateway, Add bot, pick the app, and paste the keys it asks for. The app signs in with them before saving. Keys are stored encrypted and are never shown again. Keys that belong to a different account than the bot are refused.
Telegram. Create a bot with @BotFather and paste its token. One account has one listener.
Slack. Create a Slack app with Socket Mode on; paste the bot token (starts
xoxb-) and the app token (startsxapp-). Invite the bot to a channel or message it directly. The Slack app you use for the inbox integration cannot be reused. Senders appear as Slack user ids, not names. In a channel a thread reply without an @-mention is picked up only in threads the bot has posted in since the app last started; @-mention the bot to be sure.Discord. Create an application and bot in the Discord developer portal, turn on the Message Content intent, paste the bot token and invite the bot to your server. The app signs in at most 900 times a day per bot and stops with an alert beyond that.
Mattermost. Create a bot account or personal access token and paste it with your server's address. Use https for a server on the internet.
Matrix. Create an account for the bot, paste its access token, the homeserver address and the full user id (like
@bot:example.org). The bot joins rooms it is invited to. Encrypted rooms are not supported, and Element creates encrypted direct chats by default, so make an unencrypted room or direct chat. Element treats a leading/approveas its own client command: type//approve 3, or choose "send as message".Signal. Run a signal-cli REST service registered to a spare number, then paste its address, the number and an access token if the service asks for one. Signal allows only the allowlist. Requests are answered in Omniscio, and no voice replies are sent. In a group, an @-mention that carries only an id (some newer signal-cli versions) may not count as addressed to the bot, so reply to the bot's message instead.
iMessage (BlueBubbles). Run a BlueBubbles server on a Mac, paste its address and password. Only the allowlist is offered. iMessage has no @-mention, so a group bot with Require mention on never answers: turn it off for iMessage groups. Replies are sent by AppleScript (no Private API), and requests are text only.
Home Assistant. Create a long-lived access token on an administrator account (only administrators can send the reply event) and paste it with your server's address. Fire an
omniscio_messageevent from an automation or script withtext, and optionallyconversation_id(defaults to the user's id),sender_nameandis_bot. The bot answers with anomniscio_replyevent that your automation can read. The event must be fired by a signed-in user; events with no user are dropped. Requests are answered in Omniscio. Example script:script: ask_omniscio: fields: question: description: What to ask sequence: - event: omniscio_message event_data: text: "{{ question }}" conversation_id: kitchen sender_name: Kitchen panel automation: - alias: Speak the agent's reply trigger: - platform: event event_type: omniscio_reply action: - service: notify.persistent_notification data: message: "{{ trigger.event.data.text }}"Open Developer tools, Events, and listen to
omniscio_replyonce to see the exact fields your Home Assistant version delivers.SMS. Needs no keys. It uses the SMS integration you already set up, and answers only phone numbers on the bot's list. It never sends pairing texts, and an ordinary text from anyone else goes to the SMS inbox as before. Replies stop near 1,600 characters with "rest in Omniscio". Pushbullet may cap how many texts you can send.
WhatsApp. Create a Meta app with the WhatsApp Cloud API, paste the permanent access token, the app secret, a verify token you choose, and the phone number id. In Meta's webhook setup, enter the address Settings shows and the same verify token. Message templates are not supported, so the bot can answer only inside WhatsApp's reply window.
Teams. Register an Azure bot, paste the app password, the app id and optionally the tenant id (leave it empty for any organisation), and set the bot's messaging endpoint to the address Settings shows.
Google Chat. Google Chat apps need a Google Workspace account. Create a Chat app in a Google Cloud project, paste the service account JSON key and the project number, and set the app's HTTP endpoint to the address Settings shows.
A bot on a server of your own (Mattermost, Matrix, Signal, BlueBubbles, Home Assistant) must use https when the address is public. Plain http is allowed only on your own network or Tailscale, with a warning, and chat approvals are turned off for that bot.
When something goes wrong
- A rejected key, or a second program listening on the same account, stops that bot and raises one alert, cleared when it reconnects. Replace the keys in Settings to bring it back.
- A bot that cannot start its webhook listener says it needs the webhook; check the port in Settings.
- Deleting a bot removes its chats, lists, pairing requests, requests, counters, keys and alerts. The sessions it started stay in the app.
Limits you will hit
- Text and voice notes only; images and files are not read, and the bot says so.
- Replies arrive as one finished message, not streamed.
- Matrix encrypted rooms and iMessage voice notes are not supported.
- Most platform checks were built from each app's documentation and have not yet been run against live accounts for every app; expect to report rough edges on the webhook apps first.
Related
- Scheduled jobs plus — send a job's report to a bot chat.
- Mobile remote access — the phone app that can approve pairings.
- Safety checks — the rules that decide before any chat request is shown.
- Tray and window — close-to-tray, which keeps bots connected with the window closed.
- Set up the SMS integration — what an SMS bot sends and receives through.
Last verified 2026-10-29