# Chat apps

Chat apps let people reach a bot from the messaging tools they already use: Telegram, email, SMS,
Slack, WhatsApp, Messenger, Feishu, iMessage, Microsoft Teams and Discord. The bot answers in the
same thread, and every conversation also shows up in the Casama app. Linear and Jira work the same
way: assign an issue to the bot and it replies with a comment (see
[Give a bot a Linear or Jira issue](#give-a-bot-a-linear-or-jira-issue)).

## How it works

- Each chat app is connected to one bot.
- A bot only answers people on the chat app's **Allowed senders** list. Messages from anyone else
  get no reply and are logged in the chat app's **Activity** as "Ignored: not on the allowed list".
- Each outside thread becomes one Casama conversation, titled with the app and the sender or
  subject, such as "Telegram: Ana". Follow-up messages in that thread continue the same
  conversation.
- Each message reaches the bot prefixed with where it came from, such as
  `(Telegram, from Ana)`, and starts a run. When the run finishes, its final reply goes back to
  the thread.
- If an app delivers the same message twice (Slack retries after a few seconds, for example), the
  bot answers it once.
- The conversation belongs to the person who connected the chat app, and runs act for them. That
  person sees these chats in the app.

## Connect a chat app

You need to manage the bot to connect a chat app.

1. Open the bot, then **Bot profile** → **Advanced** → **Chat apps**.
2. Tap **Connect a chat app**.
3. Choose the **App** and give the connection a **Name**.
4. Paste the credentials from the app's developer settings (see the table below). They're stored
   encrypted and never shown again.
5. Under **Allowed senders**, add one per line: email addresses (or `*@example.com` for a whole
   domain), phone numbers, or user ids.
6. Tap **Add**.
7. Casama shows the **Webhook address**. Paste it into the app's webhook settings. Telegram is the
   exception: Casama sets its webhook for you.

| App       | What you paste                                                                  | Where the webhook goes                                     |
| --------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Telegram  | **Bot token** from @BotFather                                                   | Set automatically                                          |
| Email     | **Email address**, Resend **API key**, and the webhook's **Signing secret**     | A Resend inbound webhook for received email                |
| SMS       | Twilio **Phone number**, **Account SID** and **Auth token**                     | The number's incoming-message webhook in Twilio            |
| Slack     | **Bot token** and **Signing secret**                                            | Event Subscriptions request URL, subscribed to `message.im` and `app_mention` |
| WhatsApp  | **Phone number ID**, **Access token** and **App secret** from the Cloud API      | Meta webhook callback URL, with the **Verify token**       |
| Messenger | **Page access token** and **App secret**                                        | Meta webhook callback URL, with the **Verify token**       |
| Feishu    | **App ID**, **App secret**, **Encrypt key** and **Verification token**          | The app's event subscription request URL                   |
| iMessage  | Nothing; pick your **Mac**                                                      | None                                                       |
| Microsoft Teams | The Azure bot's **App ID** and client secret (**App secret**)             | The Azure bot's messaging endpoint                         |
| Discord   | **App ID** (application id), **Public key** and **Bot token**                   | The application's Interactions Endpoint URL                |
| Linear    | **The bot's user ID in the tracker**, an **API key** and the webhook's **Signing secret** | A Linear webhook for issues and comments           |
| Jira      | **Site address (https://…)**, **Account email**, **The bot's user ID in the tracker**, an **API key** (API token) and the webhook's **Signing secret** | A Jira webhook for issue created, issue updated and comment created |

For WhatsApp and Messenger, Casama generates a **Verify token** for Meta's setup and shows it once,
right after you connect. Copy it then.

Each app's requests are checked before anything happens: Telegram's secret token, the Svix-style
signature on email, Twilio's signature on SMS, Slack's signed requests, Meta's
`X-Hub-Signature-256`, Feishu's request signature, Microsoft's signed token on Teams, Discord's
Ed25519 signature, `Linear-Signature` and Jira's `X-Hub-Signature`. A request that fails the check
is refused. Feishu must have an encrypt key set; Casama decrypts its messages.

> **Tip**
>
> Not sure what a sender's id looks like? Ask them to message the bot first. The message shows in
> **Activity** as ignored, with their id. Add that id to **Allowed senders**.

## Allowed senders

Matching is exact and ignores case. `*@example.com` matches any email address at that domain.

| App       | Use                                                                    |
| --------- | ---------------------------------------------------------------------- |
| Telegram  | The person's numeric Telegram user id                                  |
| Email     | Their email address, or `*@example.com`                                |
| SMS       | Their phone number in international format, such as `+13125550123`     |
| Slack     | Their Slack user id                                                    |
| WhatsApp  | Their WhatsApp number as Meta sends it: digits only, no `+`            |
| Messenger | Their page-scoped sender id                                            |
| Feishu    | Their open id                                                          |
| iMessage  | The phone number or email address they message from                    |
| Microsoft Teams | Their Microsoft Entra object id                                  |
| Discord   | Their Discord user id                                                  |
| Linear    | Their Linear user id                                                   |
| Jira      | Their Atlassian account id                                             |

To change the list later, tap the chat app on the **Chat apps** screen, edit **Allowed senders**
and tap **Save**.

## Threads and replies

| App       | One conversation per                                         | How the reply goes back                       |
| --------- | ------------------------------------------------------------ | --------------------------------------------- |
| Telegram  | Chat                                                         | A message in the same chat                    |
| Email     | Sender plus subject (`Re:` and `Fwd:` are ignored)           | A reply email with `Re:` and threading headers |
| SMS       | Phone number                                                 | A text message                                |
| Slack     | Slack thread                                                 | A reply in that thread                        |
| WhatsApp  | Phone number                                                 | A WhatsApp message                            |
| Messenger | Sender                                                       | A Messenger message                           |
| Feishu    | Chat                                                         | A message in the same chat                    |
| iMessage  | Handle                                                       | An iMessage from your Mac                     |
| Microsoft Teams | Teams chat or channel conversation                     | A reply in the same conversation              |
| Discord   | Channel                                                      | A reply to the `/ask` command, or a channel message after 15 minutes |
| Linear    | Issue                                                        | A comment on the issue                        |
| Jira      | Issue                                                        | A comment on the issue                        |

Long replies are sent in parts, split at a paragraph, line, sentence or word, so nothing is cut
off. Each part fits the app's limit: 1,600 characters on SMS, 2,000 on Messenger and Discord,
4,096 on Telegram and WhatsApp, 10,000 on Feishu, 25,000 on Teams, 39,000 on Slack, 30,000 on Jira
and 50,000 on Linear.

When someone sends a photo, file or voice note, the bot gets the caption, if there is one, and a
note that the attachment doesn't come through yet, so it can ask them to describe it or send it in
the Casama app.

If a reply can't be sent, the error shows on the chat app in the list and in its **Activity**.

## Bots sending first

A bot can start a new message through one of its chat apps, for example to tell you a long job is
done. It can only message people on that chat app's allowed list, and sending is a high-risk action,
so under the default autonomy it asks you first. See [Autonomy and approvals](https://docs.casama.ai/guide/autonomy.md).

## Routines on messages

A routine can start when a matching message arrives. Filter by chat app, sender (`*@example.com`
works), subject or message text. Without a sender filter, a routine only hears people on the chat
app's allowed list. With one, it also hears that sender when they aren't on the list: for example, a
routine can file every invoice a vendor emails, although the vendor can't chat with the bot. A
message that starts a routine isn't also answered. In the routine sheet, choose **Messages**. See
[Routines](https://docs.casama.ai/guide/routines.md).

## Slack

In Slack, people can message the bot directly or @mention it in a channel. The mention is removed
before the bot reads the message. An eyes reaction on the message shows it arrived.

When a run started from a Slack thread needs your approval, the request is also posted in that
thread with **Approve** and **Deny** buttons. Only people on the chat app's allowed list can press
them; the decision counts as made by the person who connected the chat app, and the message then
says who approved or denied it. The usual notification and the card in the app still work.

To use the buttons with your own Slack app, turn on **Interactivity** in the Slack app's settings
and set its request URL to the **Webhook address** followed by `/interact`. Give the bot token the
scopes `app_mentions:read`, `chat:write`, `im:history`, `im:read` and `reactions:write`.

### Install Casama's Slack app

A server can run its own Slack app, so people connect Slack with one click instead of pasting a bot
token. Whoever runs the server registers the Slack app and sets `SLACK_CLIENT_ID`,
`SLACK_CLIENT_SECRET` and `SLACK_SIGNING_SECRET`. The Slack app's addresses are, on the server's
public API address:

| Slack setting              | Address                |
| -------------------------- | ---------------------- |
| OAuth redirect URL         | `/hooks/slack/oauth`   |
| Event Subscriptions        | `/hooks/slack/events`  |
| Interactivity request URL  | `/hooks/slack/interact` |

`GET /v1/channels/slack/install?bot_id=…` returns Slack's sign-in address. After you approve it in
Slack, the chat app is made for that bot, with you on its allowed list. Each Slack workspace talks
to one Casama bot through the server's app; installing again for another bot moves it. Without
those settings the request answers that the server has no Slack app, and you connect your own
Slack app with a bot token as above. The app has no install button yet.

## Microsoft Teams

People message the bot in Teams chats and channels. In a channel, @mention it; the mention is
removed before the bot reads the message.

1. In Azure, create an Azure bot and a client secret for it.
2. In Casama, connect **Microsoft Teams** with the bot's **App ID** and the client secret as
   **App secret**.
3. Paste the **Webhook address** as the Azure bot's messaging endpoint, and add the Teams channel
   to the Azure bot.

## Discord

Discord only delivers ordinary messages to bots that keep a live connection open, which a webhook
server doesn't. So people talk to the bot through a slash command, such as `/ask`, with one text
option for the question.

1. In the Discord Developer Portal, copy the application's **Application ID** and **Public key**,
   and the bot's token.
2. In Casama, connect **Discord** with those as **App ID**, **Public key** and **Bot token**.
3. Paste the **Webhook address** as the application's **Interactions Endpoint URL**.
4. Register a slash command for the application with one string option.

Discord shows "thinking…" while the bot works. The reply answers the command if it's ready within
15 minutes, and otherwise arrives as a message in the channel.

## Give a bot a Linear or Jira issue

Connect Linear or Jira as a chat app and you can hand a bot an issue the way you would a teammate.

- **Assign an issue** to the tracker user that stands for the bot, or create it assigned. The bot
  starts work with the issue's title and description.
- **Comment** on an issue the bot holds to continue the conversation. Each issue is one Casama
  conversation, so the bot keeps the context.
- **The bot's reply** is posted as a comment on the issue. Changes the bot makes itself are
  ignored, so it doesn't answer its own comments.

People who assign issues or comment need to be on the **Allowed senders** list, by their Linear user
id or Atlassian account id.

### Linear

1. Create a Linear user for the bot and copy its user id. Create a personal **API key** for that
   user; the bot comments with it.
2. In Linear's settings, add a webhook for **Issues** and **Comments** pointing to the
   **Webhook address**, and copy its signing secret.
3. In Casama, connect **Linear** with **The bot's user ID in the tracker**, the **API key** and
   the **Signing secret**.

### Jira Cloud

1. Create an Atlassian account for the bot and an API token for it.
2. In Casama, connect **Jira** with your **Site address (https://…)**, the bot account's
   **Account email**, its account id as **The bot's user ID in the tracker**, the API token as
   **API key**, and a **Signing secret** you make up.
3. In Jira's system settings, add a webhook to the **Webhook address** with that secret, for issue
   created, issue updated and comment created.

The bot doesn't move the issue's status as it works; it says where things stand in its comment.

To have a bot use Linear or Jira as a tool instead (search issues, file new ones), connect the app
from [Apps and connections](https://docs.casama.ai/guide/connections.md).

## iMessage

iMessage has no bot API, so your own Mac does the work through the desktop app.

1. On your Mac, open the desktop app and turn on **Use this computer for bots**.
2. Under **What bots may do**, allow **Messages (iMessage)**.
3. Give the desktop app Full Disk Access in macOS System Settings, so it can read Messages.
4. In the bot's **Chat apps**, connect **iMessage** and pick your **Mac**.

Your Mac reads new messages and sends replies through Messages. Casama checks for new messages every
minute. The first check only takes a starting point, so old messages are never answered. Only the
Mac's owner can connect it, and only bots allowed on that Mac can use it. See
[Your own computer](https://docs.casama.ai/guide/companion.md).

## Manage a chat app

On the **Chat apps** screen:

- Use the switch next to a chat app to turn it off and on.
- Tap a chat app to see its **Webhook address**, edit **Allowed senders**, and read its
  **Activity**: answered, sent, started a routine, ignored or failed.
- Tap **Disconnect** to remove it. Its saved credentials are deleted.

## Limits

- Text only: attachments and images aren't passed on yet. The bot is told one was sent.
- Feishu has no one-click install. Slack has one only on servers that run their own Slack app, and
  only through the API for now.
- Approval buttons are in Slack only. In Teams and Discord, approvals arrive in the app as usual.
- On Discord, the bot hears only its slash command, not ordinary messages.
- Group chats on WhatsApp and iMessage aren't supported.
- iMessage needs your Mac to be on, with the desktop app running.
- The adapters follow each provider's public docs and have been tested against stand-ins, not yet
  against every live provider. Teams and Discord have been tested with signed test requests only.
- If your server sits behind a proxy, set `PUBLIC_API_URL` so signatures and webhook addresses use
  your public address. See [Configuration](https://docs.casama.ai/self-hosting/configuration.md).

## Related

- [Chat](https://docs.casama.ai/guide/chat.md)
- [Routines](https://docs.casama.ai/guide/routines.md)
- [Your own computer](https://docs.casama.ai/guide/companion.md)
- [Autonomy and approvals](https://docs.casama.ai/guide/autonomy.md)
- [Voice and calls](https://docs.casama.ai/guide/voice.md)
