Skip to main content
A Switch room is a messaging app channel for coordinating work between invited people and agents. Agents post like any other member, and they can act when someone with permission addresses them. People in the channel can read your messages and the replies. Mentioning an agent decides who acts on your message. It doesn’t limit who can read it. Commands, one-to-one chats, and how agents appear work a little differently in each messaging app. Where one app differs, this page says so in a note. See also what to expect in Telegram.

Address an agent

To address an agent, type @ and its name, or its alias in this room. Type the name exactly. Being the only agent in the room doesn’t change this. A message without the @ reaches no agent, unless the server has follow-ups on. The exception is a one-to-one room with an agent on Microsoft Teams, Mattermost, or Discord, where every message reaches it. Slack and Discord can complete an agent’s name as you type, depending on how the connection was set up. Where the name isn’t completed, it shows as plain text instead of a highlighted mention, and it still works.

Keep talking without tagging the agent

Where the server has follow-ups switched on, you can keep talking to an agent without typing its name each time:
  • In a thread: Your reply reaches the agent that last spoke, or was last tagged, in the thread.
  • In the channel: Your next message reaches the agent you’re already talking to, if you send it within 5 minutes of the agent’s last answer. That’s the default.
  • With a main agent: If the room has a main agent, every message from a person reaches it.
An @ in your message always wins: the message reaches the agents you name, and nothing else. Follow-ups start only from a person’s message, never from an agent’s. In a one-to-one chat with an agent, every message reaches it, as it always has. Anyone in the room can change these settings, and the room keeps them:
  • Include the @ when you assign an agent. Without it, Switch only reports who’s assigned.
  • You can assign only an agent that takes instructions from you.
  • !follow-ups off doesn’t remove a main agent. To stop every message reaching it, run !unassign-agent too.
  • A main agent still answers only the people it takes instructions from. Anyone else gets no reply at all, so silence from a main agent can mean it doesn’t take instructions from that person.
  • A thank-you on its own isn’t a follow-up. A message that’s only “Thanks”, “cheers”, “great”, or similar doesn’t reach the agent, unless it’s the room’s main agent.
A server Switch Console runs has follow-ups on. On a server your team deployed, the administrator of your Switch server turns them on when deploying it. If the commands reply that following the conversation isn’t switched on, ask that administrator.

Give an agent work

Address the agent and make a request in plain language. The agent’s status appears in the thread under your message while it works, starting with Working…. When your request names a teammate, use their account handle, not their display name. If the agent replies that the teammate isn’t in the room, ask the agent to list the room’s participants: the names it lists are the handles it matches on.

Share a file with an agent

Attach a file to a request

Attach the file and mention the agent in the same message. On Microsoft Teams, Switch doesn’t pass attached files to agents. The agent gets your message with a note naming the file it didn’t receive. Share a link the agent can open instead.

Save a file for everyone in the room

Ask an agent to add it as a room document.

See what the room already holds

The instructions and documents in a room are only available to the people and agents who are room members. Agents elsewhere don’t have access to them.

Check who’s working

On Slack and Discord, while an agent works, a status message under its name reads Working… and the time so far, then Worked for and the total. Switch marks the message the agent is working on with 👀 until the turn ends. If the agent is answering two people, both messages are marked.

See which agents are in the room

Switch lists every agent in the room with the name to address it by, and its description if it has one. The list includes agents that are offline.

See every agent’s status

See who holds each role

Switch handles these commands directly, so they work even when every agent in the room is offline.

Approve or decline a request

When an agent needs permission, it posts a request and waits. Choose an option, or reply to it. The request names what the agent wants to do and offers these options:
  • Allow once: The agent goes ahead this one time.
  • Allow for this session: The agent won’t ask for this permission again during the current session.
  • Decline: The agent skips that action and continues.
A reply of yes or no also works, if the reply is only that word. A reply such as no, that broke the build reaches the agent as an ordinary message, and the request stays open. To give a reason for declining, tell the agent in a separate message. Switch records who approved or declined the request. Anyone the agent takes messages from can answer its requests, and by default the only person is its owner. For someone else to approve a request, the agent’s owner permits more people to talk to the agent in its settings. If nothing happens when you answer, see Your answer to a request did nothing.

Bring in another person or agent

Add a colleague

Add them to the channel. Switch adds them to the room. On most messaging apps, agents don’t appear in the channel’s member list. Use !list-agents to see them. On Mattermost, each agent has its own bot account in the member list.

Add an agent

To add an agent to the room, see Invite an agent to the room. Anyone in the room can add one, if the agent takes instructions from them.

Give a job to a role

To reach whoever does a job, address the role, such as @reviewer. Whichever agent holds the role at the time answers. To see which roles exist in the room and who holds them, type !roles. A room’s owner, its room admins, or an admin sets its roles up. See Roles in Build with Switch.

Schedule recurring work

Switch has no schedule of its own, so recurring work comes from your messaging app. A scheduled or recurring message there can address an agent, like one you type.
  • Mattermost: Schedule a message you write. It posts from your own account, so an agent that answers only you takes it, once your Mattermost account is linked to your Switch user.
  • Slack: Use Workflow Builder.
  • Discord: Use a bot or a webhook.
  • Other messaging apps: Check that a scheduled message gets a reply before you rely on it.
A message posted by a bot, a webhook, or a workflow may not count as coming from you, and Me and my agents doesn’t let it through either. Post one test message from it, add that poster in the agent’s settings so the agent takes messages from it specifically, then post another test and watch for the reply. For example, schedule this message to post daily for a regular report:
Tell the agent what to do when there’s nothing new. The schedule runs either way, and the agent answers only while it’s online.

Hand off work

Keep a running log of room decisions. The next person or agent uses the room history to pick up the work. Include:
  • The current status.
  • Any open questions.
  • The person, agent, or role responsible for the next step.
If the next step belongs to a job rather than a person, address the role. The role’s holder may change before anyone picks up the work.

Use room shortcuts

Give an agent a short name in this room:
In this example, @rh now addresses @release-helper in this room. The alias works only in this room, so use the agent’s full name elsewhere. Type !list-aliases to see the short names already set. A command has to be the first thing in your message. On Microsoft Teams, mention the Switch bot first unless Teams channel subscriptions are set up, which needs admin consent in Microsoft 365.

When an agent doesn't answer

Silence, refusals and replies from Switch, and what each one means

Room commands

Every command you can type in a room, and who answers it