Skip to content

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.

  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.
AppWhat you pasteWhere the webhook goes
TelegramBot token from @BotFatherSet automatically
EmailEmail address, Resend API key, and the webhook's Signing secretA Resend inbound webhook for received email
SMSTwilio Phone number, Account SID and Auth tokenThe number's incoming-message webhook in Twilio
SlackBot token and Signing secretEvent Subscriptions request URL, subscribed to message.im and app_mention
WhatsAppPhone number ID, Access token and App secret from the Cloud APIMeta webhook callback URL, with the Verify token
MessengerPage access token and App secretMeta webhook callback URL, with the Verify token
FeishuApp ID, App secret, Encrypt key and Verification tokenThe app's event subscription request URL
iMessageNothing; pick your MacNone
Microsoft TeamsThe Azure bot's App ID and client secret (App secret)The Azure bot's messaging endpoint
DiscordApp ID (application id), Public key and Bot tokenThe application's Interactions Endpoint URL
LinearThe bot's user ID in the tracker, an API key and the webhook's Signing secretA Linear webhook for issues and comments
JiraSite address (https://…), Account email, The bot's user ID in the tracker, an API key (API token) and the webhook's Signing secretA 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.

AppUse
TelegramThe person's numeric Telegram user id
EmailTheir email address, or *@example.com
SMSTheir phone number in international format, such as +13125550123
SlackTheir Slack user id
WhatsAppTheir WhatsApp number as Meta sends it: digits only, no +
MessengerTheir page-scoped sender id
FeishuTheir open id
iMessageThe phone number or email address they message from
Microsoft TeamsTheir Microsoft Entra object id
DiscordTheir Discord user id
LinearTheir Linear user id
JiraTheir 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 ​

AppOne conversation perHow the reply goes back
TelegramChatA message in the same chat
EmailSender plus subject (Re: and Fwd: are ignored)A reply email with Re: and threading headers
SMSPhone numberA text message
SlackSlack threadA reply in that thread
WhatsAppPhone numberA WhatsApp message
MessengerSenderA Messenger message
FeishuChatA message in the same chat
iMessageHandleAn iMessage from your Mac
Microsoft TeamsTeams chat or channel conversationA reply in the same conversation
DiscordChannelA reply to the /ask command, or a channel message after 15 minutes
LinearIssueA comment on the issue
JiraIssueA 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 settingAddress
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.

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.

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.