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).
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.
- Open the bot, then Bot profile → Advanced → Chat apps.
- Tap Connect a chat app.
- Choose the App and give the connection a Name.
- Paste the credentials from the app's developer settings (see the table below). They're stored encrypted and never shown again.
- Under Allowed senders, add one per line: email addresses (or
*@example.comfor a whole domain), phone numbers, or user ids. - Tap Add.
- 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 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 |
| 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 |
Their email address, or *@example.com | |
| SMS | Their phone number in international format, such as +13125550123 |
| Slack | Their Slack user id |
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 |
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 |
| 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.
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.
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.
- In Azure, create an Azure bot and a client secret for it.
- In Casama, connect Microsoft Teams with the bot's App ID and the client secret as App secret.
- 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.
- In the Discord Developer Portal, copy the application's Application ID and Public key, and the bot's token.
- In Casama, connect Discord with those as App ID, Public key and Bot token.
- Paste the Webhook address as the application's Interactions Endpoint URL.
- 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
- 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.
- In Linear's settings, add a webhook for Issues and Comments pointing to the Webhook address, and copy its signing secret.
- In Casama, connect Linear with The bot's user ID in the tracker, the API key and the Signing secret.
Jira Cloud
- Create an Atlassian account for the bot and an API token for it.
- 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.
- 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.
iMessage
iMessage has no bot API, so your own Mac does the work through the desktop app.
- On your Mac, open the desktop app and turn on Use this computer for bots.
- Under What bots may do, allow Messages (iMessage).
- Give the desktop app Full Disk Access in macOS System Settings, so it can read Messages.
- 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.
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_URLso signatures and webhook addresses use your public address. See Configuration.