The server can receive and answer messages through Discord, Telegram, and WhatsApp. A messaging account belongs to the signed-in user who creates it. Each account uses the model, workspace, response language, sender access, and tools that its owner chooses. Its conversations appear in that user's Chat sidebar unless messaging conversations are hidden there.
Messaging conversations do not load personal skills selected in ordinary chats. Set the messaging account's instructions and tools in its own configuration.
Choose a messaging app
Discord connects outward through its Gateway, so normal Discord messages and attachments do not require a public server address. Telegram and WhatsApp deliver incoming messages to webhooks, so their callback routes must be reachable by those providers over public HTTPS. This does not require making the entire WebUI public.
Agent interaction prompts for tool approval, questions, and secure secret entry require an HTTPS
Public Origin on every provider. For Discord, this may remain a private address that the messaging
account owner can reach over the local network or a VPN; it does not need to be reachable from the public internet.
In the SoAI WebUI, an administrator with Configuration changes (CONFIG_PATCH) selects the
Settings button at the right of the header, chooses Settings, selects Advanced in the page
header, opens Server, and sets Public Origin. The setting is
SERVER.PUBLIC_ORIGIN.
For Telegram or WhatsApp, configure the reverse proxy to publish only the required callback routes unless the owner also needs authenticated Chat access through that address. Exposing the complete SoAI interface directly to the public internet is not recommended. Read Network and TLS and Security hardening before enabling a public callback.
Before you add an account
You need the SoAI permissions named Model read access (MODEL_READ),
Public inference API access (OPENAI_API), and MCP usage (MCP_USE) to see Messaging in
Settings. These permissions do not require an external OpenAI account or API key. Ask an
administrator to review your access if the tab is missing. The server also needs at least one available model and access
to the MCP tool catalog before it can open the account editor. See
Users, roles, and sessions for account permissions and
Models catalog for model availability.
Add a messaging account
- In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then select Messaging.
- Select Add account.
- Enter an Account label, choose the provider, and select the Remote response language for SoAI's built-in provider messages.
- Enter the credentials requested for that provider.
- Choose who may send messages, select the model and agent mode, choose a workspace folder, and configure any MCP tools the account may use. Use Edit parameters to set account-specific model parameters.
- Select Save.
Remote response language controls built-in command, status, error, and interaction messages. The model still follows its prompt and conversation context. If it must always answer in a particular language, select Edit parameters under Chat execution and state that requirement in the System prompt.
SoAI checks the provider credentials when you save. For Telegram and WhatsApp, it configures the provider callback (the route that receives incoming messages). The account row shows lifecycle and provider health separately. Active means the account is enabled; Provider connection healthy confirms that the provider connection works. Activation failures show as Degraded. Use Edit, Disable, Enable, or Remove from the account list after setup. You cannot change the provider while editing an account; add another account for a different provider.
Editing an account changes the settings used by all of its messaging conversations on later turns. Disable an account to stop new provider messages and replies without deleting its Chat history. Remove clears the saved credentials and removes the connection from SoAI; this cannot be undone. Existing conversations remain as local Chat transcripts and no longer receive provider messages.
When editing an account, leave every provider credential field blank to keep the saved credentials. To replace them, enter the complete credential set for that provider again.
Control who can use the account
Keep Accept messages from anyone off and enter one exact provider sender ID per line under
Authorized provider senders for restricted access. You may add a label after |. An
empty list means SoAI accepts no senders. Turn on Accept messages from anyone only when everyone
who can reach the bot or business number should be able to start a SoAI conversation.
Allow plaintext secret replies lets a reply from the messaging app answer a SoAI secret request. Keep it off unless you accept the risk of the secret appearing in provider history or notifications. See Secrets vault for how tools request and store credentials.
Send files to SoAI
A user can attach a supported file in Discord, Telegram, or WhatsApp, with or without message text or a caption. The server downloads the file, processes it as a conversation attachment, and includes it in the prompt before the model answers. The message and attachment also appear in the messaging conversation in Chat. Provider and server file limits still apply. See Attachments and file context for supported content and how models use documents, images, audio, and video.
This support is for files sent to the server. It sends its provider reply as text; it does not attach a generated or returned file to the reply in the messaging app. It splits a long text answer into multiple provider messages when it exceeds that provider's message length.
Control a conversation from the messaging app
Send one of these commands as a text-only message:
| Command | What it does |
|---|---|
/cancel |
Requests cancellation of your active messaging request in that conversation. |
/help |
Lists the available messaging commands. |
/new |
Starts a new SoAI Chat conversation for that provider channel, chat, or sender. Earlier provider messages stay in the messaging app, and the old SoAI transcript stays in Chat, but neither is part of the new conversation's model context. |
/status |
Reports whether the conversation is idle, queued, running, or waiting for a response. |
In a Telegram group, address a command to the bot, for example /status@BotUsername. In a Telegram
direct message, Discord, or WhatsApp, use the command without a bot username. A command sent with a file attachment
is treated as a normal prompt instead.
SoAI processes new provider messages. Editing or deleting a message in the provider does not rewrite the SoAI transcript or retract model context; send a new correction instead.
Answer agent questions and approvals
An agent turn can pause and send a question or tool approval request to the same messaging conversation. Follow the
reply format in that message and keep its six-character token in the response when requested. For a tool approval,
reply with yes, y, no, n, or always and include the
token. A direct reply to the provider prompt can also identify the pending request.
Secret questions use a secure link back to the authenticated SoAI Chat page. Vault credential requests do the same by default, and the signed-in owner of the messaging account completes them there. Allow plaintext secret replies changes only vault credential requests: it lets the remote sender provide the credential as provider text, does not save that reply to the vault, and can expose it in provider history or notifications.
Use messaging conversations in Chat
Messaging conversations appear in the Chat sidebar unless you hide them. Their model, workspace, identity, parameters, and tools come from the messaging account, so Chat locks those controls. To change them, or to update the account credentials or sender policy, select the Settings button at the right of the SoAI header, choose Settings, select Messaging, and use Edit for the account.
You can send a message from SoAI Chat while a messaging conversation is open. That message and SoAI's immediate reply stay in SoAI; neither is copied to Discord, Telegram, or WhatsApp. Both remain in the conversation transcript, so the model can use them as context when it answers a later message from the messaging app.
You may also attach files to a message sent from Chat in this conversation. The local message, its files, and SoAI's immediate reply stay in SoAI and can affect later model replies; SoAI does not forward them to the messaging app.
Each account can use a different context length and therefore have its own effective compaction limit. Under Chat execution, select Edit parameters, then set Context length (tokens) under Model settings. Clear it to use the selected model's default. A lower value gives the account a smaller context budget, so SoAI compacts older context sooner. If a smaller model gives worse answers as a conversation grows, lowering this value can keep its active prompt shorter without changing your other messaging accounts.
Automatic context compaction lets the conversation continue without a fixed message-count limit. SoAI keeps recent turns and may replace older details with a summary before sending the next prompt to the model. See Chat for context compaction and other conversation controls.
To hide messaging conversations, select Chat configuration in the Chat header, select Appearance, turn on Hide messaging conversations, then select Save.
If you archive a messaging conversation, the next accepted provider message returns it to the active Chat list.