Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
FAQ/Channels & Messaging

Channels & Messaging

Slack, Telegram, WhatsApp, public links, progress indicators, proactive consent, voice, phone calls. Short, grounded answers with links to the full documentation.

41 questions

How do I connect my Trinity instance to Slack?

Connection happens in two stages. First, a platform admin sets up the Slack app under Settings → Integrations → Slack Integration, following the checklist shown inline: under OAuth Credentials, enter the app's Client ID, Client Secret and Signing Secret and click Save Credentials; under Transport Connection, paste the app-level token (xapp-...) and click Connect to start Socket Mode (the badge reads Socket Mode, Webhook or Disconnected); then click Install to Workspace (Reinstall to Workspace once a workspace is connected) to complete OAuth and obtain the bot token. The client secret, signing secret and app token are stored encrypted at rest. Second, each agent is bound to Slack from its own detail page: open the Channels tab, click Configure on the Slack row, and click Create Channelto create a dedicated channel bound to that agent — a public link's Connect Slack button is a shortcut into the same binding (see the Sharing, Access & Monetization FAQ). Only one Slack workspace can be connected per Trinity instance. See Slack Integration.

After I click Install to Workspace, Slack sends me to a page that doesn't load. Did the install fail?

Probably not. After Slack's consent screen Trinity redirects you to FRONTEND_URL if it is set, otherwise to the Public URL under Settings → General. Only when neither is set does it fall back to http://localhost, which does not load on a server install even though the install succeeded. Set the Public URL (or FRONTEND_URL) and go back to Settings → Integrations → Slack Integration to confirm the workspace is connected. See Slack Integration.

What is the difference between Socket Mode and webhook mode for Slack?

Socket Mode is the default transport: Trinity opens an outbound WebSocket connection to Slack, so your instance needs no public URL — it works even on a laptop behind NAT. Webhook mode is the HTTP fallback for production environments where Slack posts events to your server, which requires a publicly accessible URL. If you can use Socket Mode, it is the simpler option. See Slack Integration.

Can multiple agents share one Slack workspace?

Yes. Each agent gets its own dedicated Slack channel via Create Channelin the agent's Channels tab, and @mentions in that channel route to the bound agent. Direct messages to the bot go to a single workspace-wide DM-default agent instead. Replies post with each agent's own name and avatar, so multiple agents in one workspace stay visually distinct. See Slack Integration.

Can each agent have its own Slack bot identity instead of sharing one?

By default all agents share one workspace bot and are told apart by their per-message name and avatar. Giving an agent its own dedicated Slack bot— one people can DM directly and @mentionby name, alongside other agents in the same channel — is an enterprise-tier capability, configured from the agent's Channels tab. See Slack Integration.

Can I control whether an agent posts to a Slack channel on its own?

Yes. Proactively posting to a Slack channel requires a per-channel consent toggle, separate from the per-recipient consent for DMs — a newly bound channel denies proactive posts until you enable it in the Slack channel panel. Replying inline to someone's message never needs consent. See Slack Integration.

Which agent answers when someone DMs the Slack bot?

DMs are routed to the workspace's DM-default agent. The first agent bound to the workspace becomes the DM default automatically, but you can reassign it anytime: open the target agent's Channels tab → Slack section and click Set as DM Default— the change takes effect immediately, no restart needed. Only one agent per workspace can be the DM default, and you cannot unbind the current DM-default agent while other agents are still bound; reassign the default first. See Slack Integration.

Why does my agent keep replying in a Slack thread without being @mentioned?

That is thread tracking working as designed. Once an agent has been @mentioned in a channel (or a thread starts from one of the bot's own messages), replies in that thread route to the same agent automatically, so people can hold a conversation without re-mentioning the bot on every message. Thread tracking only applies to threads started by a bot message or an @mention — the bot does not join arbitrary threads. See Slack Integration.

How does my agent show its own name and avatar in Slack?

Trinity posts each reply with the agent's name and its Trinity avatar as the per-message bot icon, using Slack's chat:write.customizescope. This applies to both replies and proactive messages, so in a multi-agent workspace you can always tell which agent is speaking. The agent also sees who is talking and where — channel messages arrive with a prefix like [Channel: #engineering] / [From: John Smith (@johndoe)], while DMs stay clean. See Slack Integration.

How do I connect an agent to Telegram?

Create a bot first: message @BotFather on Telegram, send /newbot, choose a name and a username ending in bot, and copy the bot token. Then open the agent's Channels tab, click Configure on the Telegram row, paste the token, and click Connect Bot — Trinity validates the token and registers the webhook. Each agent needs its own dedicated bot; bots cannot be shared across agents. If the dialog shows the yellow "Bot connected, but Telegram can't deliver messages to it yet", either no Public URL is set under Settings → General(set it to your instance's public HTTPS address; the webhook registers automatically once saved), or Telegram has not accepted the webhook — check the address is reachable from the internet and press Verify, which re-registers the webhook, answers Operationalonly when Telegram can deliver, and otherwise shows Telegram's own reason. See Telegram Integration.

Why doesn't my Telegram bot see every message in a group?

Two settings control this. In Trinity, each group has a trigger mode: Mention only(the default — the bot responds to @mentions and replies) or All messages. For "all messages" to work, you must also disable Telegram's Privacy Mode via @BotFather (/setprivacy→ Disable), because with Privacy Mode on, Telegram simply never delivers non-mention group messages to the bot. Critically, if the bot is already in the group, you must remove and re-add it after changing Privacy Mode — Telegram only applies the change to newly joined groups. See Telegram Integration.

Does my Telegram agent know what the group said before it was tagged?

Yes, when the bot can see the group's messages. The agent remembers who said what — the last 40 messages within 24 hours by default — and answers a tagged message in that context, so "@agent summarise what we decided" works without re-pasting the thread. Un-tagged messages are only remembered: the agent still speaks only per the group's trigger mode, and remembering costs no agent turn. With Privacy Mode on, the bot sees only tagged messages and replies; the group's status in the Channels tab says which case applies and what to do. Turn Group context off for a group that should not be remembered, and what was already stored is deleted. See Telegram Integration.

Can users send voice messages to my Telegram bot?

Yes. Voice notes are automatically transcribed with Gemini and delivered to the agent as text prefixed with a 🎙️ emoji — users just send voice notes normally. Limits: 5 minutes duration and 10 MB file size, and the platform needs a Gemini key (next question). If transcription fails or no key is configured, the agent receives a placeholder such as [Voice message received — transcription failed] instead, so the conversation still progresses. See Telegram Integration.

Which Gemini model transcribes Telegram voice notes, and where does the key come from?

gemini-3.5-flash by default; set GEMINI_TRANSCRIPTION_MODELon the backend to use another. The key is the platform Gemini key — saved from the browser under Settings → Integrations → API Keys (or the Other keys step of first-run setup), with GEMINI_API_KEY in the server's .env as the fallback when nothing is saved in Settings. It must start with AIza, and it is the same key that powers voice conversations and generated avatars, so adding it once switches all three on. See Telegram Integration and Platform Keys.

Does my agent's Markdown render properly in Telegram, and what happens to long replies?

Yes. Replies are converted to Telegram formatting — bold, italic, strikethrough, inline code and fenced code blocks, headings, links, lists, spoilers, and blockquotes (long ones collapse as expandable quotes); tables become preformatted text. The conversion escapes first, so a literal <, >, or &in a code snippet, an HTML tag, or a comparison survives instead of breaking the message. A reply longer than Telegram's 4,096-character limit is split into several messages, and formatting that straddles a cut is closed at the end of one chunk and reopened in the next, so no chunk arrives mangled. Proactive messages and completion reports use the same rendering. See Telegram Integration.

Why did a long Telegram reply arrive as several messages?

Because Telegram caps a message at 4,096 characters and the reply was longer. Trinity splits it at a paragraph, sentence or word boundary, closes any formatting that straddles the cut and reopens it in the next message, and sends the pieces in order — code blocks stay inline rather than being turned into file attachments. If Telegram refuses a piece and it cannot be confirmed (after one bounded rate-limit wait and a plain-text fallback), delivery stops there rather than resending what already arrived. See Telegram Integration.

How do I connect an agent to WhatsApp?

Trinity connects to WhatsApp through Twilio — you bring your own Twilio account. Open the agent's Channels tab, click Configure on the WhatsApp row, and enter your Twilio Account SID, Auth Token (stored encrypted), and WhatsApp sender number in the form whatsapp:+15551234567. After connecting, copy the generated webhook URL into your Twilio console so inbound messages reach Trinity. You also need Settings → General → Public URL set to your public domain, and if you route traffic through a Cloudflare Tunnel, an ingress rule sending /api/whatsapp/webhook/* to the backend service (not the frontend). See WhatsApp Integration.

Should I use the Twilio sandbox or a production WhatsApp sender?

Use the sandbox for development: it is free and uses Twilio's shared sender whatsapp:+14155238886, but every tester must first opt in by sending join <your-sandbox-keyword>to that number. For production, register a dedicated sender in the Twilio console — this requires linking a Meta Business Manager account, and display-name approval takes 24–48 hours. Trinity auto-detects the sandbox from the well-known sender number. See WhatsApp Integration.

Can my agent join WhatsApp group chats?

No. Twilio's WhatsApp API supports direct messages only, so WhatsApp groups are not available — this is a Twilio/WhatsApp platform limitation, not a Trinity setting. If you need group conversations, Telegram and Slack both support them. See WhatsApp Integration.

Is Discord supported?

Not as a built-in channel. The channels Trinity connects out of the box are Slack, Telegram and WhatsApp (through Twilio), plus public chat links and the Workspace. To reach an agent from another platform, have that system call the agent through Trinity's chat API, or fire one of its schedules through a webhook trigger. See Webhook Triggers and the MCP & API FAQ.

How do users verify their email from Telegram or WhatsApp?

Users send /login user@example.com to the bot, receive a 6-digit code at that address, and reply /login 123456 to complete verification. /whoami shows the currently verified email and /logoutclears it. On Slack no command is needed — the workspace OAuth already provides each user's email. Verification matters for agents with a restricted access policy: unverified users are prompted to log in before the agent responds. See Access Control.

Why does my Telegram or WhatsApp bot say "Too many sign-in code requests"?

Sign-in code emails are rate-limited so a chat cannot be used to flood a mailbox. Over 10 minutes, each chat sender may request 5 codes, each email address 3, and each Telegram bot, WhatsApp number or Slack workspace 20. Over a cap the bot replies Too many sign-in code requests. Try again in 10 minutes. and sends no email; the user waits out the window and sends /login again. The per-address cap is shared with the web and MCP email sign-in, so requests for one address count together wherever they came from. See Access Control.

How do I let people chat with my agent without a Trinity account?

Create a public link: open the agent's Channels tab, go to Distribution → Public links, and click Create Public Link. You can configure email verification on or off, rate limits, and a custom welcome message, then share the generated URL. Recipients open it and chat immediately — no login required. See Public Links.

Can I use a different model for public and channel conversations?

Yes. The Public chat modelsetting on the agent's Channels tab overrides the model for public-facing surfaces only: public links, Slack/Telegram/WhatsApp channels, and paid chat. Your own authenticated chats and scheduled runs are unaffected, and the default option inherits the platform-wide model. This is useful for putting a cheaper or faster model in front of outside audiences. See Agent Sharing & Access.

Can I give my agent extra instructions that only apply to strangers?

Yes. The Additional instructions — public & channel chats only field on the Channels tab (up to 4,000 characters) is injected into the agent's system prompt for outside audiences only: public links, Slack/Telegram/WhatsApp, and paid chat. It never affects your own authenticated chats, scheduled runs, loops, or agent-to-agent calls, so you can set tone, disclosure rules, or scope limits for strangers without touching the agent's core instructions. Leave it empty to disable. See Agent Sharing & Access.

Can my agent speak its replies as voice notes?

Yes, one reply at a time. Voice is a per-message choice the agent makes during a channel turn by calling the send_voice_reply tool — replies stay text unless it asks, and there is no always-on voice mode. Delivery uses each channel's native format: an OGG/Opus voice note on Telegram, an inline MP3 clip in the Slack thread, and an OGG voice note via Twilio media on WhatsApp. Setup is one platform key plus one per-agent configuration: an admin stores the ElevenLabs key under Settings → General → Voice (ElevenLabs) (encrypted, never echoed back, with an optional platform default voice), then the owner turns Voice replies on for the agent on its Settings tab and picks a voice (or relies on the platform default), and allows it per channel with the Voice repliestoggle inside each channel's dialog on the Channels tab — a channel left off stays text-only. Voice replies do not cover the web chat or public links. See Voice Replies.

Why did my agent's voice reply arrive as plain text?

Because voice is opt-in per message and fails soft — a voice problem never loses a message. The most common cause is simply that the agent did not call send_voice_replyfor that reply. Otherwise the reply falls back to text when voice replies are off for the agent, when that channel's allow flag is off, when the platform has no ElevenLabs key, when the reply exceeds the character cap (TTS_MAX_CHARS, default 1,500), or when synthesis, transcoding, hosting, or upload fails for any reason. If it happens consistently, check the key in Settings, the agent-level toggle, and the per-channel flag. See Voice Replies.

Can my agent place real phone calls?

Yes — agents can dial a number through Twilio and hold a live, interruptible spoken conversation powered by Gemini Live. VoIP is off by default: the platform needs VOIP_ENABLED=true plus a Gemini key, the Public URLset in Settings, and a publicly reachable deployment (Twilio must open a WebSocket to your instance). The agent owner then configures a per-agent Twilio voice binding in the Channels tab's Voice calls row, and calls are placed via the call_userMCP tool or the API. This release is outbound only — agents do not answer incoming calls. See VoIP Telephony.

What limits apply to agent phone calls, and what happens after a call?

Calls are rate-limited to 5 per owner and destination number per 60 seconds, capped by a per-agent daily call limit (default 50, overridable on the binding), and hard-capped at 10 minutes each. Calls bill to the agent owner's own Twilio account. After the call ends, the full transcript is saved to the agent's chat history with source voice and, by default, dispatched back to the agent as a task so it can follow up on what was discussed; unanswered calls skip this. See VoIP Telephony.

How does Trinity know who is messaging my agent from a channel?

The verified email is the identity across every channel: a user verified on Telegram, WhatsApp, or a public link, or identified via Slack workspace OAuth, is the same person to Trinity everywhere. That email is checked against the agent's access policy — open access lets anyone chat, while restricted agents admit only the owner, admins, and emails on the shared-access list, with everyone else generating a pending access request. Approving a user once admits them on all channels. The Channels tab also shows a client roster of external channel users who have messaged the agent. For the approval flow and policy details, see Access Control.

Can I change how many proactive messages my agent can send?

Yes. An admin can tune the anti-spam caps on agent-initiated ("proactive") sends under Settings → General → Proactive message limits: Slack per-channel and per-agent, Telegram per-group and per-agent, and proactive direct messages per recipient — each a per-hour limit. The shipped defaults are 10/hour per channel/group/recipient and 100/hour per agent, so nothing changes until you raise them. Setting a value to 0makes that cap unlimited (the guardrail is disabled and the save warns you). Changes take effect immediately, with no restart. This is the setting to raise for a legitimate high-volume agent — for example, one that posts a Slack message for each inbound support request.

Note: these caps apply only to messages the agent starts. Replies to inbound messages (a DM, an @mention, or a thread reply through a channel) are never limited by them. See Slack Integration.

Does Telegram show anything while a long task is running?

Yes, three layers, all fail-soft and on by default per bot binding. A 👀 reaction lands on your message the moment the agent picks it up (and is cleared when the turn ends), the standard typing indicator fires, and past 30 seconds the bot posts a quiet “⏳ Working on it — N min elapsed” note (sent without a notification) that it edits about once a minute and deletes when the turn finishes. Turn it off in the Telegram dialog on the agent's Channels tab. In groups it only fires on @mentions and replies — a bot in observe mode stays silent, since a visible reaction would reveal that it is listening. See Telegram Integration.

An agent delegated my Telegram request to another agent — will I hear back?

Usually, yes — when the agent hands the work off in the background. An agent that delegates long work with chat_with_agent(..., parallel=true, async=true)reports back into the conversation by default; a plain sequential delegation (the agent waits for the other agent's reply and answers you itself) reports back only when the platform stopped waiting and handed the agent a receipt instead of the reply — when it answers in time, the agent has the reply and nothing extra is posted — and the agent can opt a call out with execution_id="manual". When work that started from Telegram finishes later — because it was delegated or run in the background — the result is posted back into the originating chat, threaded to your original message and sent by the same bot you were talking to. Failures report honestly rather than vanishing. An ordinary chat turn already answers inline, so it is never double-posted. Group chats have a per-group consent flag, allow_proactive(on by default), that suppresses these when turned off; direct messages are consented by construction. Slack behaves the same way, gated on the channel's proactive-consent toggle — a channel that denies proactive posts gets no completion note. The same report-back also reaches the Workspace chat a job was started from. See Telegram Integration, Slack Integration, and Event Subscriptions.

Why can't my agent use all its tools when replying in Slack?

Because channel replies run with a restricted tool set: by default only WebSearch and WebFetch, with Readadded automatically when the message carries readable files, and a 120-second execution timeout. Those are platform settings — channel_allowed_tools for the tools, channel_rate_limit_max and channel_rate_limit_windowfor the per-Slack-user rate limit (30 messages per 60 seconds by default) — so an admin can widen the list for an agent that genuinely needs more. Rate limits are per Slack user, not per agent. See Slack Integration.

Why won't my agent post to a Telegram group on its own?

Most likely the group's proactive consent is off. Every connected group carries an allow_proactiveflag — on by default — that governs whether the bot may post there without being asked: agent-initiated messages via send_group_message(channel_type: "telegram") and the completion report-back for delegated work. Turn it back on with PUT /api/agents/{name}/telegram/groups/{id}(a human-only route). If the flag is on, check that the group hasn't been removed (deactivated) in the Channels tab's Telegram Groups section and that the agent's proactive caps under Settings → General → Proactive message limits haven't been hit. Direct messages never need consent — the user started the conversation. See Telegram Integration.

A file someone sent my agent in Slack never arrived. Why?

Inbound Slack files are downloaded through a host allow-list: the authenticated first request may only reach Slack's own API host, and redirects are followed only to Slack's file and edge-CDN hosts, over HTTPS, with each hop re-checked and a bounded hop count. A download to any other host is refused — and logged as an error, so a refusal is visible in the platform log rather than silently dropped. Check platform.json for the refusal before assuming the message never arrived. See Slack Integration.

How do I stop a recurring agent from sending the same message every run?

Give the send an idempotency key. send_message, send_group_message (Telegram and Slack) and call_user accept an optional idempotency_key — a stable name for what the agent is telling them, such as gcp-ceiling-correction — and an optional idempotency_ttlin seconds (60–86400, default 86400). Two sends with the same agent, recipient and key inside that window deliver once, even from different runs; the message text is never part of the key. Change the key when the information changes. Without a key, each run's send goes out as before. See MCP Server → Sending once across runs.

Why did my agent's message come back with sent: false?

An earlier send with the same idempotency key already reached that recipient inside the key's window, so nothing was delivered this time. The result says suppressed_by: "idempotency_key" and carries first_sent_at and first_execution_id for the send that did go out. The suppression is written to the audit log, and a system note labelled Trinityis added to the first send's conversation. The agent should record it and move on, not resend under a new key. A 409 instead means another run is sending the same key right now; retry with the same key. See MCP Server → Sending once across runs.

Can my agent post into an existing Slack thread on its own?

Yes. send_group_message(channel_type: "slack", chat_id, message, thread_ts) posts into the thread named by thread_ts; leave it out to start a new message in the channel. Find the agent's bound channels with list_channel_groups(channel_type: "slack"). The post needs the channel's proactive consent and counts toward the proactive rate limits. See Slack Integration → Proactive Channel Messages.

Can my agent start a WhatsApp conversation on its own?

No. Proactive messages go to Telegram, Slack or the web: send_message and POST /api/agents/{name}/messages accept auto, telegram, slack or web, and autonever falls back to WhatsApp. Twilio also allows freeform messages only within 24 hours of the user's last message. On WhatsApp the agent replies inline to messages users send. See WhatsApp Integration → Limitations.