Skip to content
Console
Try one

    Answer in Chat Apps

    Connect your own Telegram, Discord, Matrix, Mattermost or Twitch bot to a hub, so the hub answers in the chats you choose.

    Make a bot on a chat network, give its token to the Thalovant console, and your hub answers in the groups, channels or rooms you pick. To the hub, the bot is one more connection. To the people in the chat, it’s a member they mention when they want an answer.

    The console calls these Chat apps. There are five:

    NetworkThe bot answers inStatus
    TelegramGroups, and the private chats you allowAvailable
    DiscordThe channels of a serverAvailable
    MatrixRooms without encryption, on any homeserverBeta
    MattermostThe channels of your Mattermost serverBeta
    TwitchChannel chatsBeta

    Matrix, Mattermost and Twitch are in beta. Their bots answer the same way and count against the same limits, but the console does less for you: it can’t check their credentials before the bot starts, list the places the bot can answer in, or send a test message. You type where the bot answers, and the bot’s state tells you whether it signed in. Their setup may still change.

    You need a paid plan. Free and Connect don’t include chat apps, and the console shows a Paid plan badge on the chat app cards there. Most paid plans include two bots; the full list is below.

    You also need a hub you manage, since only those can run a bot, and an account on the network. To bring the bot in, you need the right to add members to the Telegram group, the Manage Server permission on the Discord server, the right to invite people to the Matrix room, or the right to add members to the Mattermost channel. A system admin of the Mattermost server creates its bot account. A Twitch bot needs a Twitch account of its own and a Twitch developer application, which is free to register.

    One bot answers for one hub. To answer for a second hub, make a second bot. A bot counts against your plan’s chat apps, not against its connections, whatever its network.

    1. Open @BotFather in Telegram. It’s Telegram’s own bot for making bots.
    2. Send /newbot. Choose a name, then a username that ends in “bot”, such as KitchenHubBot.
    3. Copy the token BotFather sends back. It looks like 123456789:AAH…: a number, a colon, then letters.
    1. Open the Discord Developer Portal and select New Application. Give it the name the bot should have.
    2. Open its Bot page and select Reset Token. Discord shows the token once, so copy it straight away.
    3. Leave the privileged gateway intents off, Message Content included. The bot only reads messages that mention it or reply to it, and Discord hands a bot those without any special intent.

    A Matrix bot is an ordinary account on a homeserver, yours or a public one. Getting its access token takes a terminal for one command (macOS or Linux; on Windows, use WSL).

    1. Create an account for the bot, such as @kitchenbot:example.org, and give it a display name. People mention the bot by that name.

    2. Note the homeserver address. In Element, signed in as anyone on that server, open Settings, then Help & About: it’s under Advanced, such as https://matrix-client.matrix.org. It has to be an https address on port 443 that’s reachable from the internet.

    3. Sign the bot in once to get its access token, with the homeserver address, the bot’s username and its password:

      Terminal window
      curl -X POST https://matrix-client.matrix.org/_matrix/client/v3/login \
      -H 'Content-Type: application/json' \
      -d '{"type": "m.login.password", "identifier": {"type": "m.id.user", "user": "kitchenbot"}, "password": "THE_BOT_PASSWORD", "initial_device_display_name": "Thalovant"}'

      Keep the access_token from the answer. It lasts until that session is signed out, so never sign out the session named “Thalovant”. Don’t use the access token Element shows in its settings instead: it ends when Element signs out, and on some servers it’s renewed every few minutes.

    4. Make each room without encryption. The bot can’t read end-to-end encrypted rooms. Element encrypts new private rooms and direct messages by default, and a room’s encryption can’t be turned off later, so create the room with Enable end-to-end encryption off. Then invite the bot.

    5. Copy each room’s id from the room’s settings, under Advanced: the Internal room ID, such as !AbCdEfGh:example.org. The console takes ids, not room addresses like #kitchen:example.org.

    1. Turn on bot accounts. A system admin opens System Console, Integrations, Bot Accounts and turns on Enable Bot Account Creation, then, under Integration Management, Enable Personal Access Tokens.
    2. Create the bot. From the main menu, open Integrations, Bot Accounts, Add Bot Account, and pick a username such as kitchenbot. Leave its role as Member; never make it a system admin. Mattermost shows the bot’s access token once: copy it.
    3. Add the bot to the team, and to each channel it should answer in, with Add Members in the channel’s menu. A bot sees only the channels it belongs to.
    4. Copy each channel’s id. Select the channel’s name, then View Info. An id is 26 letters and digits, such as 6ru4o9giafff9fdm56kb5cqmje.

    You’ll also need your server’s address, such as https://chat.example.com. It has to use https on port 443 and be reachable from the internet.

    A Twitch bot signs in with a refresh token, which it uses to get its own short-lived access. Making one takes a terminal for one command (macOS or Linux; on Windows, use WSL).

    1. Pick the bot’s Twitch account. Its login is the lowercase name in twitch.tv/<login>, such as kitchenbot.

    2. Register an application on the Twitch developer console. Set OAuth Redirect URLs to http://localhost:3000 and Client Type to Confidential: a confidential application’s refresh token doesn’t expire. Copy the Client ID, then create a Client Secret and copy it too. Twitch asks for two-factor authentication on your account before it registers one.

    3. Give the bot’s consent. Signed in to Twitch as the bot, open this address with your client id in it, and approve:

      https://id.twitch.tv/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000&scope=chat%3Aread+chat%3Aedit

      Your browser then opens a localhost page that doesn’t load. That’s expected: copy the code from its address.

    4. Exchange the code for a refresh token, straight away, since a code works only once:

      Terminal window
      curl -X POST https://id.twitch.tv/oauth2/token \
      -d client_id=YOUR_CLIENT_ID -d client_secret=YOUR_CLIENT_SECRET \
      -d code=THE_CODE -d grant_type=authorization_code \
      -d redirect_uri=http://localhost:3000

      Keep the refresh_token from the answer.

    5. Make the bot a VIP or a moderator in each channel it answers in, so the channel’s chat settings, such as slow mode or followers-only chat, don’t hold it back. Some channels also let only accounts with a verified phone number chat.

    Go to Connections, select Add connection, and under Chat apps pick the network’s card. Matrix, Mattermost and Twitch carry a Beta badge. You can also start a Telegram or Discord bot from a hub: open its drawer, go to the Chat apps tab, and select Add a Telegram bot or Add a Discord bot.

    1. Choose the hub whose assistant should answer.
    2. Paste the token and select Check the token. The console checks it with Telegram or Discord, then shows the bot the way people will see it: its picture, its name and its @username. Nothing runs yet.
    3. Invite the bot. On Telegram, select Add to a group and pick the group, or scan the QR code with your phone. On Discord, select Add to a server and pick the server. Discord’s page asks for three permissions and nothing more: View Channels, Send Messages and Read Message History.
    4. Choose where it answers. On Telegram, first send /start@YourBot in each group (the console shows the exact line, with a copy button), then select Refresh. Telegram lists the chats that wrote to the bot in the last 24 hours. On Discord, every text and announcement channel the bot can see is listed under its server. Pick at least one, and up to 50.
    5. Select Start answering. The bot reads Starting for a minute or two, then Connected.

    You’ll know it worked when the bot’s drawer says Connected and lists the chats it answers in. Select Send a test message to have it post a short “connected” line in one of them, or mention it in the group and ask something.

    1. Choose the hub whose assistant should answer.
    2. Fill in the settings and credentials, then select Connect. The console shows the network’s own setup steps above the form. It then says the bot is set up; select Continue. Nothing runs yet.
    3. Add where it answers. Type each room id, channel id or channel name, then select Add or press Enter. Add at least one, and up to 50.
    4. Select Start answering. The bot reads Starting for a minute or two, then Connected.
    Network Settings Credentials Where it answers
    Matrix Homeserver, and Bot user id if you like, such as @kitchenbot:example.org Access token Room ids
    Mattermost Server address Bot token Channel ids
    Twitch Bot login and Client id Client secret and Refresh token Channel names, such as kitchenstream (#KitchenStream works too)

    When you select Connect, the console checks each address: https, port 443, and a public address on the internet, not a private or local one. It can’t check the credentials: the bot signs in when it starts, and if the network refuses any of them (a token, a client id or a secret), its drawer says Needs attention and the bot stays stopped until you replace them. A Matrix bot user id, when you give one, has to be the account the token belongs to, and a Twitch bot login has to be the account that gave its consent.

    You’ll know it worked when the drawer says Connected. There’s no test message for these networks: mention the bot in one of its rooms or channels and ask something.

    In a group, a channel or a room, the bot answers only messages that mention it, such as @KitchenHubBot what's the weather, or that reply to one of its messages. Everything else in the chat passes it by. It answers only where you allowed it.

    Each person gets their own conversation with the hub, even in the same group, so one person’s question doesn’t run into another’s. Under Advanced, while you choose where it answers, you can pick One conversation per chat instead, and everyone in a chat shares one thread.

    A Telegram bot answers only in the chats you allowed. People can also write to it in a private chat, which it answers once you’ve allowed that chat too, and it answers every message there without a mention.

    To have it answer every message in its groups too, turn off In groups, answer only when mentioned under Advanced. The console warns you when you do: the bot then answers everything said in those groups, and uses the daily allowance faster.

    A Discord bot always answers only when it’s mentioned or replied to. That’s how a Discord bot reads messages without the Message Content intent, so there’s no switch for it. It ignores direct messages.

    A Matrix bot joins the rooms on its list when it’s invited, and answers people who mention it, by its display name or with a mention pill, or reply to it. In a room where it’s alone with one person, it answers every message. It can’t answer in encrypted rooms, and so not in direct messages started from Element.

    A Mattermost bot answers in the channels on its list when someone mentions its @username, or replies in the thread under one of its answers. It answers in the channel, or in the thread if the question was in one, starting with the asker’s @username, and never notifies @channel, @all or anyone else. It ignores direct messages.

    A Twitch bot joins the channels on its list and answers messages that mention it, such as @kitchenbot what time is it, or that reply to it. Its answer is a reply to that message. It never answers whispers.

    On Matrix, Mattermost and Twitch, you can turn off Answer only when mentioned under Advanced. The bot then answers every message where it’s allowed, and uses the daily allowance faster; a busy Twitch channel can use it up fast.

    Requests that come from a chat count against the hub owner’s daily allowance, the same Intents per day as every other connection. On top of that, each bot answers at most 500 requests a day, and each person at most 6 requests a minute. With one conversation per chat, the whole chat shares those six. Past any of these, the bot’s requests are turned down until the count resets.

    Your plan sets how many bots you can run, across all your hubs and networks:

    Plans Bots
    Free, Connect None
    Home, Family, Maker, Workspace, Business, Civic, Pilot, Fleet, and the older Private, Team and On Demand 2
    Site Pack, Municipality 10
    Private Edge, Enterprise 20

    When every bot your plan includes is in use, the console says so on the chat app cards. Billing and Plans has the rest of each plan. Pausing and deleting a bot always work, whatever your plan.

    The token is the bot. Anyone holding it can post as your bot and read what’s sent to it. The same goes for a Matrix access token, a Mattermost bot token, and a Twitch client secret and refresh token.

    The console sends the token to Thalovant once, when you select Check the token (or Connect, on Matrix, Mattermost and Twitch). Thalovant keeps it, and it’s never shown again, not even to you. To change it later, open the bot and use Replace token, or Replace credentials on the beta networks. A new Telegram or Discord token has to belong to the same bot; a token for a different bot means adding a new bot.

    On the beta networks, revoke a leaked credential where it was made: sign out the bot’s “Thalovant” Matrix session, delete the bot’s token in Mattermost, or create a new client secret on the Twitch developer console. For a leaked Twitch refresh token, disconnect the application in the bot account’s Twitch settings, under Connections, and give consent again. Then enter the new one with Replace credentials.

    Anyone in an allowed chat can ask your hub questions, and each request spends your allowance. Allow only chats whose members you trust with that.

    People in a chat aren’t you, and the hub treats them that way:

    • personal memory is off for them, so the hub doesn’t remember them, and it never acts as the owner on their behalf;
    • a chat app can never control your home. Requests to Home Assistant from a chat are refused.

    Messages to the bot travel through the chat network, under its own terms (on Matrix and Mattermost, through the server you chose), and through a bot you own. The hub’s answers are posted in the chat, where everyone in it can read them.

    When someone asks your hub through a bot, Thalovant counts the request in your hub’s activity: which bot, which network, and when. It doesn’t store what they wrote, their IP address or location, or a session that ties their requests together. Their requests are never counted as yours or as one of your devices’, and the hub keeps no conversation history for them, unlike your own requests.

    About the bot itself, Thalovant keeps what you gave it: its token or credentials, which are never shown again, not even to you; the bot’s name and username, on Telegram and Discord; its settings, such as a server address; the chats you allowed; and how it answers. Your account export lists your bots with their chats and settings, never their tokens or credentials. Deleting a bot removes them from Thalovant.

    Open a bot from the Connections list, or from the hub’s Chat apps tab. Its drawer shows the chats it answers in, how it answers, and its state:

    • Setting up: the bot has no chats yet. Choose them to start it.
    • Starting: it’s on its way, usually within a minute or two.
    • Connected: it’s answering in its chats.
    • Paused: it doesn’t answer until you resume it, or until Thalovant starts it again (see below).
    • Needs attention: it isn’t answering, and the drawer says why.

    You’ll see Pausing for a moment after you pause it.

    Thalovant pauses a bot itself in two cases, and the drawer says which:

    • When your plan includes fewer bots than you run, after a downgrade for example. Your oldest bots keep answering and the newer ones pause. A paused one starts again on its own, within a few minutes, once your plan has room for it: after an upgrade, or after you pause or delete another bot.
    • When your account is suspended. Every running bot pauses. When the account is reactivated, they start again as far as your plan has room.

    You can’t resume a bot Thalovant paused; it starts again on its own. Nothing is deleted while a bot is paused.

    From the drawer you can send a test message, replace the token, edit the chats, pause or resume the bot, and delete it. The test message is written in the hub’s language: “Connecté à …” for a French hub, “Connected to …” otherwise.

    Edit chats works a little differently on each network. Telegram lists new chats only while the bot is paused, so select Pause and look for new chats, send /start@YourBot in the new group, then select Refresh. Saving resumes the bot. On Discord, Edit channels works while the bot runs. The same window has Advanced, where you change how the bot answers: the mention rule (except on Discord), and one conversation per person or per chat.

    The drawer of a beta bot shows its settings under Connection, and the version it runs. There’s no test message. Instead of the token and chat buttons, it has:

    • Use Edit settings to change the homeserver, the server address, the bot user id, the bot login or the client id. The bot restarts with the new settings.
    • Use Replace credentials to enter a new access token, bot token, client secret or refresh token. Fill in only the ones that changed; the others stay as they are. The bot restarts with them.
    • Use Edit list to add or remove room ids, channel ids or channel names, with Advanced for the mention rule and the conversations.

    Delete stops the bot answering for the hub and removes its token or credentials from Thalovant. The bot itself stays in your Telegram account, or the application in your Discord Developer Portal; delete it there if you no longer need it. A Matrix, Mattermost or Twitch account stays as it is too. Deleting a hub deletes its bots.

    Nobody mentioned it. In a group, a channel or a room, mention the bot in the message or reply to one of its messages. On Discord there’s no other way.

    The chat isn’t allowed. Open the bot and check the chats it answers in. A group you added the bot to later isn’t on the list until you add it with Edit chats, or Edit list on the beta networks.

    A daily limit is reached. The hub owner’s daily allowance, the bot’s 500 requests a day, or a person’s six a minute. Wait for the count to reset, or look at your plan on Billing.

    The bot was removed from the group or server. Invite it again from the bot’s drawer. When this is the cause, a test message to that chat fails with “Check that the bot is still in that chat and may post there.” On Matrix, invite it to the room again; on Mattermost, add it to the channel again.

    The Matrix room is encrypted. The bot stays silent there. Make a room without encryption, invite the bot, and add the new room’s id.

    The id isn’t the right kind. A Matrix room address like #kitchen:example.org, or a Mattermost channel’s name, isn’t an id: copy the id as described above. On Twitch, use the login in the channel’s address.

    A Twitch bot stays on Starting. One of its channel names is mistyped, or the channel was renamed: Twitch ignores a channel that doesn’t exist, and the bot waits for it. Check the names with Edit list.

    The token was revoked or reset. The drawer shows Needs attention and says Telegram or Discord refused the bot’s token, or that the bot stopped answering. Paste the new token with Replace token.

    The credentials were refused. On the beta networks, the drawer shows Needs attention and says the network refused its credentials: a token, a client id or a secret. The bot stays stopped until you replace them. Make new ones: a Matrix access token (was the bot’s session signed out?), a Mattermost bot token, or on Twitch a new consent and refresh token, or the current client id and secret. Enter them with Replace credentials or Edit settings (the Twitch client id is a setting).

    The bot is paused. If you didn’t pause it, the drawer says why: your plan has no room for it, or the account is suspended. See Look After a Bot.

    The bot can’t reach its hub. The drawer says so under Needs attention. Check that the hub is running on Hubs.

    If the drawer says the bot couldn’t start because of a problem on Thalovant’s side and it lasts, get support.

    “This bot already answers for a hub, and one bot serves one hub.” Make another bot with @BotFather or the Developer Portal, or open the one you have. On the beta networks, those credentials already serve a bot: open it, or use a separate account.

    “That does not look like a Telegram bot token.” Copy the whole token BotFather sent, from the number through the last letter.

    “Telegram did not accept this token.” Copy it again from @BotFather, or send /token there for a fresh one. On Discord, reset it on the Bot page and paste the new one.

    “This token belongs to a different bot.” Replace token takes only a new token for the same bot. To use the other bot, add it as a new one.

    “This bot has no username, so Telegram cannot make an invite link.” Give it a username with @BotFather, then replace the token.

    “Telegram is still delivering this bot’s messages elsewhere.” Another program is reading this bot’s messages. Wait a minute and refresh. If it lasts, stop the other program or make a new bot for Thalovant.

    “It must be an https address, such as https://chat.example.org.”, “It must be an https address on port 443: other ports cannot be reached.” or “It must be a public address on the internet, not a private or local one.” The bot reaches a Matrix or Mattermost server over the internet, on port 443 only. Use the address your Matrix or Mattermost app connects to; a server on a private network or another port can’t be used.

    “That address could not be found. Check the spelling.” The server’s name doesn’t exist on the internet as typed.

    ”“#kitchen:example.org” does not have the form this chat app expects.” What you typed isn’t a Matrix room id, a Mattermost channel id or a Twitch channel login. Copy it again as described above.

    “Telegram bots come with paid plans” or “Your plan includes 2 bots, and they are all in use.” See how many bots each plan includes, or delete a bot you no longer use.

    “Your plan allows 2 running bots, and they are all in use.” You tried to resume a bot, or to save its chats after pausing it, while your plan’s bots are all answering. Pause or delete another bot first.