# 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.

Source: https://docs.thalovant.com/manage/chat-apps/

---
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:

| Network | The bot answers in | Status |
| --- | --- | --- |
| Telegram | Groups, and the private chats you allow | Available |
| Discord | The channels of a server | Available |
| Matrix | Rooms without encryption, on any homeserver |  |
| Mattermost | The channels of your Mattermost server |  |
| Twitch | Channel chats |  |

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.

## What You Need

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](#how-many-bots-and-requests).

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.

## Make a Telegram Bot

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.

## Make a Discord Bot

1. **Open the [Discord Developer Portal](https://discord.com/developers/applications)**
   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.

## Make a Matrix Bot :badge[Beta]{variant=caution}

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:

   ```sh
   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`.

## Make a Mattermost Bot :badge[Beta]{variant=caution}

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.

## Make a Twitch Bot :badge[Beta]{variant=caution}

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](https://dev.twitch.tv/console/apps). 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:

   ```txt
   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:

   ```sh
   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.

## Connect the Bot to a Hub

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**.

### Telegram and Discord

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.

### Matrix, Mattermost and Twitch

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.

## How It Answers

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.

### On Telegram

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.

### On Discord

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.

### On Matrix :badge[Beta]{variant=caution}

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.

### On Mattermost :badge[Beta]{variant=caution}

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.

### On Twitch :badge[Beta]{variant=caution}

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.

## How Many Bots and Requests

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](/workspace/billing-and-plans/) has the rest of
each plan. Pausing and deleting a bot always work, whatever your plan.

## Keep the Token Secret

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.

  Never paste a bot token into a chat, a support thread or a screenshot. If one
  leaks, send `/revoke` to @BotFather (on Discord, select **Reset Token** on the
  Bot page), then paste the new token with **Replace token**.

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**.

## Who Can Ask, and What It Can't Do

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](/manage/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.

## What Thalovant Keeps

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](/trust/#what-the-hub-keeps).

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](/account/profile-security/#export-and-retention) lists your bots with
their chats and settings, never their tokens or credentials. Deleting a bot
removes them from Thalovant.

## Look After a Bot

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.

### Edit a Matrix, Mattermost or Twitch Bot

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.

## When the Bot Doesn't Answer

**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](/workspace/billing-and-plans/).

**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](#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](/concepts/hubs/).

If the drawer says the bot couldn't start because of a problem on Thalovant's
side and it lasts, [get support](/account/get-support/).

## Messages in the Console

**"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](#how-many-bots-and-requests), 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.
