Messaging

The screens, step by step: Schedules and channels, in the Guides. For phone calls, see Phone.

Supported platforms

Receive modes

Three platforms can deliver messages two ways, and the choice matters more than it looks.

Polling is the default and needs no public URL — the right mode for a laptop, a LAN install, or anything behind NAT. The adapter holds a connection out to the platform: Telegram long-polls, Discord holds the gateway websocket, Slack holds a Socket Mode websocket.

Webhook holds nothing open. The platform posts to your install, so it needs a publicly reachable HTTPS URL: the Webhook address on the Channels screen (messaging_webhook_base_url) — the public address of the Synapse app, not its backend port; a tunnel URL works for local testing. A Telegram, Discord or Slack channel then shows its Delivery URL, <address>/api/messaging/<platform>/webhook/<channel id>, to paste into the platform. Every delivery is verified before it is trusted — a secret-token header for Telegram, an Ed25519 signature for Discord (its Public Key), the signing secret for Slack.

Sending is identical in both modes — plain REST either way.

Enabling messaging

Set messaging_enabled: true in settings (this is the default). Without it, the messaging adapters won't start.

Configuring a channel

Self-hosted, open Channels and press New channel. On Cloud, Connect a channel offers Slack, Telegram and Discord: Slack and Discord go straight to the platform's own authorize page, and Telegram asks for its bot token.

Fields

Start and Stop, on the channel's row in the list, start and stop its adapter.

A saved secret is never shown again: its field reads Saved — leave blank to keep. A channel that cannot start — a bad token, say — is saved anyway and says so (⚠️ Saved, but it did not start: …); its status reads Error and the reason stays under Last error.

You can also ask Synapse AI to connect a channel. It answers with a card, and pressing it does what the Channels screen does; the model never sees a token. Self-hosted, the card asks for the platform's fields, and for Teams and WhatsApp it then shows the address to paste into the platform. On Cloud, as with Connect a channel, it connects Telegram by its bot token and Slack and Discord through their own sign-in.

A channel is standalone — it is a connection, not an agent's property. You then assign one or more agents to it, and mark one as the default: the agent that answers a plain message.

The same agent can serve several channels, and a channel can front several agents.

---

Telegram

1. Create a bot via @BotFather → /newbot
2. Copy the bot token
3. In SynapseOrch, add a Telegram channel with the bot token
4. Enable the channel → the bot comes online
5. Send a message to your bot — the assigned agent responds

Credentials:

---

Discord

1. Go to discord.com/developers → New Application
2. Create a bot, enable Message Content Intent
3. Invite the bot to your server with bot + applications.commands scopes
4. Copy the bot token and Application ID

Credentials:

---

Slack

1. Create a Slack App at api.slack.com/apps
2. Enable Event Subscriptions and subscribe to message.channels, app_mention
3. Add OAuth scopes: channels:read, chat:write, app_mentions:read
4. Install the app to your workspace

Credentials:

---

Microsoft Teams

Teams uses the Bot Framework webhook model. You need an Azure Bot registration.

1. Create an Azure Bot in the Azure Portal
2. Set the messaging endpoint to https://<your Synapse address>/api/messaging/teams/webhook/<channel id> — the public address of the Synapse app, not the backend port
3. Enable the Microsoft Teams channel
4. Copy the App ID and client secret

Credentials:

---

WhatsApp

WhatsApp connects through Meta's WhatsApp Cloud API only: a Meta Business account and a verified number.

1. Create a Meta Developer App at developers.facebook.com, of type Business
2. Add the WhatsApp product, and pick a test or production number under Phone Numbers
3. Under WhatsApp → Configuration, set the webhook URL to https://<your Synapse address>/api/messaging/whatsapp/webhook/<channel id> — the public address of the Synapse app, not the backend port
4. Type a verify token of your choice there and in Synapse, and subscribe to the messages webhook field
5. Copy the phone number ID, an access token, and the App Secret (App settings → Basic) into the channel

Credentials:

---

How agents respond

When someone messages a connected channel, SynapseOrch identifies the message as addressed to the bot, routes it to the active agent for that conversation, runs the ReAct loop, and replies in the same place.

Session continuity is per user — each person gets their own session id, so an agent remembers the conversation across messages.

Who the senders are

Everyone who messages this bot is a workspace user is on by default: the channel's agents run for a sender as they would for you. With it on, the screen warns who can do what — Anyone who can message this bot can use …, naming the tools and any agent's memory.

Turned off, senders are visitors, as on a chat widget: the agents use only the tools ticked under What senders can use, never their memory, and a sender's reply does not answer a workflow waiting on the channel. Visitors reach an agent's knowledge bases only where the base allows visitors and search_knowledge is ticked. A reply never carries [K#] labels, whoever the sender is.

Nobody on a channel can answer an approval card, so a call that would ask a person does not wait for one. A remember that would ask is refused with its reason, and the agent is told to report the point in its answer instead. A Team member's call that needs approval is not run, and the lead is told and carries on.

If the agent's turn fails — its model refuses or cannot be reached, or an Orchestrator agent's run fails — the reply is "⚠️ Something went wrong answering that. Please try again." The error itself is in the server log and, for someone in the app, on the conversation, which keeps the question answered (The workflow failed before answering.) for a failed run.

Switching agent mid-conversation

Where a channel has more than one agent assigned, two commands work in any chat:

The switch is per conversation, not per channel, so one person changing agent does not change what anyone else is talking to. It resets to the channel default.

Orchestrator agents

An Orchestrator agent on a channel runs its workflow with the message as the input, and the reply is the workflow's output. If the run fails, the reply is the fixed line above. If it pauses for a person, the reply is the question followed by "Answer it in SynapseOrch (run <id>)" — or nothing more, when that Human step already asked its question in this same channel, where a reply answers it.

Human steps

A human gate with Notify messaging channel set posts its question to that channel when the run pauses, and a reply in the channel answers it and resumes the run. While a run waits on a channel, the next message sent to the bot there is taken as the answer, not passed to an agent. Teams replies do not answer a waiting run, and Teams and WhatsApp questions are posted only when the API server is running the channel's adapter. See Human Gates → Messaging notification.

Testing a channel

After starting a channel, click Test on the channel, under Channels (on Cloud, Send test, once the bot has been messaged). For Telegram and Discord, this verifies the bot token is valid. For Teams and WhatsApp, this validates the webhook credential fields.