Connect Slack

• A Slack workspace where you can create and install apps.
• An agent with a promoted production version; see Release an agent.

lua channels

lua channels list

​

Signing secret

​

Update an existing app

1. Open App Manifest in Slack, switch to JSON and keep a copy of what’s there. Pasting it back and reinstalling undoes the update.
2. Apply Lua’s manifest on the same JSON tab and Save Changes. It keeps your app’s name and every permission the app already has. If your app has features of its own, such as slash commands, shortcuts or agent mode switched on in Slack, the dialog first asks for your current manifest and gives you a merged one that keeps them, with a list of what it changes in Slack.
3. Save the signing secret.
4. Reinstall: a public app with Install in Slack; a private app with the banner Slack shows, or Install App → Reinstall to Workspace. The bot keeps its token and keeps answering.
5. Open the bot’s DM in Slack. Slack sends Lua a signed event that confirms both the signing secret and the new manifest, and the dialog says Done.

​

When the app is uninstalled

​

Settings

curl -X PATCH "https://api.heylua.ai/admin/agents/<agentId>/channels/<channel>/settings" \
  -H "Authorization: Bearer <api key>" -H "Content-Type: application/json" \
  -d '{"changes":{"slack.responseMode":"mentions_only","slack.reactions.enabled":false}}'

​

While the agent works

​

Agent mode

• A new app: in the Create your Slack app step, tick Agent mode. Check the description (filled in from the agent, up to 300 characters, shown in Slack’s Agents & tools list) and add up to four prompts, each a button label and the message a click sends. The create link carries them.
• An app you already have: tick Agent mode on the step where you paste its values.
• A connected app: open the connection’s settings and select Set up next to Agent mode. Save it there, then apply the updated manifest in Slack and reinstall, as in Update an existing app. The same step changes the prompts or turns agent mode off.
• CLI (from the lua-cli release after 3.42.0-beta.1): lua channels asks about agent mode when you connect Slack; on a connection, Turn agent mode on or off, or change its prompts saves it and prints the manifest to apply.

​

Home tab and greetings

• the bot’s name and one line about it;
• how to reach it: a message in the Messages tab (left out when the bot answers mentions only), a mention in a channel it’s in (it answers in the thread), or /invite to add it to a channel;
• example questions, under Try asking;
• a support line, when you wrote one;
• the note “Answers come from AI and can be wrong.”

​

Conversations

• Later messages are context. After the first mention, every message in that thread or group DM joins the transcript without a reply, so the next mention knows the whole discussion. In a channel the agent follows the thread, not later top-level messages.
• Edits and deletes follow Slack. When someone edits a message, the stored copy is replaced by (edited) <new text>; the old wording is gone. When someone deletes a message, including the first message of a thread that has replies, it stays in the transcript as [message deleted], with its sender and time. This applies in channel threads, group DMs and direct messages, to the agent’s memory, the admin dashboard, and your org memory. An edit never gets a reply, even when it adds a mention. What is not changed: the agent’s own earlier replies (edit or delete them in Slack), messages sent before 29 September 2026 (a delete or edit of those is not applied), a long conversation’s summary notes, files already copied when the message arrived, and facts the agent saved to a person’s memory (remove them from memory settings).
• Speakers are named. Each message reaches the agent with the sender’s name, and people mentioned in it appear by name. Posts from other Slack apps, such as alerts or reports, are kept as context under the app’s name, and an app that mentions the agent gets an answer. An auto-respond channel answers people only, so two agents there never answer each other. A message an app posts for someone with their own Slack sign-in shows in Slack as theirs, and the agent treats it as theirs: it answers it, remembers it under their name, and follows their edits. Slackbot’s own posts, such as reminders, are not kept.
• Who each person is. Lua knows a Slack person by their own workspace and Slack member id (their organisation, on Enterprise Grid). The first time the bot sees them, the email Slack shows for them links them to the Lua account with that email; after that the member id decides, so a changed or hidden email never turns them into someone new. People from other companies are recognised the same way. Only the person talking to the bot counts as signing in: others writing in the thread, people mentioned, earlier authors and people you message from code are recorded without it. Each other app is one Lua user, whichever way Slack names it. If Slack can’t say who someone is, their message in a thread isn’t kept, and a person talking to the bot is asked to send it again.
• Slack Connect. People from other workspaces in a shared channel are answered like anyone else, unless People from other companies says otherwise (see Settings), and the files they attach reach the agent too. A file the bot can’t open reaches the agent as a note naming it, even when the message also has text, so the agent can tell the person.
• Personal memory stays personal. Nothing a person told the agent in a direct message is brought into a channel or group DM. Each channel thread is its own conversation: nothing carries over from one thread to another, or from a thread into direct messages.
• Direct messages. To continue a conversation, reply in the thread under the agent’s answer; a new top-level message starts a fresh conversation. Each thread has its own transcript, though an agent with personal memory can still recall what it learned about the person earlier. link-me-to:<agentId> and remove-my-link work in a direct message; see Test an agent on Lua’s channels.
• Your code sees the room. In a tool, a condition, or a processor, Lua.request.conversation lists the people in a channel thread or group DM and marks the current speaker. It is undefined in a direct message. Its externalId is the thread’s key, T…:A…:C…:threadTs (workspace, app, channel, thread), or T…:A…:G… for a group DM; pass it to Channels.send as to: { conversationId } to post there later through the same bot (Post from code).
• One reply per message. Slack sometimes delivers the same event twice, and a mention in a channel arrives both as a mention and as a message; the agent answers each message once. When a turn fails, the agent posts a short notice instead of staying silent.
• The admin dashboard shows the room. Activity → Group chats lists each Slack thread and group DM, titled #channel · opening words or Group DM · opening words, with its transcript and the people in it. The tab is read-only. Direct-message conversations appear under Conversations.
• Rooms close when the agent leaves. Disconnecting Slack in the dashboard archives the connection’s threads and group DMs (Disconnected in Group chats); removing the app from a channel archives that channel’s threads (Bot removed), and uninstalling the app in Slack archives them all (Uninstalled). Their transcripts are kept, and a mention in the same thread after the app is back reopens the room with its memory. Someone who leaves a channel leaves its threads, and a renamed channel renames them. The channel events behind this reach apps created from, or updated to, the current manifest.

​

Channel behavior

​

Files

• With files:write (in the manifest since 29 September 2026; see Update an existing app), each file stored on Lua’s CDN, up to 25 MB and 10 per message, is uploaded as a Slack file under a 📎 line naming the files. People preview and download it in Slack, under Slack’s access rules.
• Without it, and for a file hosted elsewhere, larger than 25 MB, or one Slack refuses (a workspace that blocks uploads or that file type), the message lists each file as a link: 📎 Loan Agreement (loan_agreement.pdf). A CDN link opens for anyone who has it.
• After you re-apply the manifest, the first answer can still send links; the agent learns the new permission from that answer’s post and uploads from the next one.
• The agent remembers the block it wrote: the file’s name and link. Each uploaded file message has its own delivery record, keyed by Slack’s file id.

​

Post from code

• A post into a thread or group DM where someone has already mentioned the bot is recorded in that conversation, so the next mention knows what the agent posted. The result has persisted: true.
• Where nobody has mentioned the bot yet, the result has persisted: false and a warning. When someone later mentions the bot in that thread, the history read at the first mention brings in the bot’s earlier posts.
• A DM is recorded under the person’s Lua user, in the conversation of the post’s own thread: a reply in that thread continues with the context, and a new top-level message starts a fresh conversation, as with any direct message.
• Posts your code makes by calling Slack’s API directly are not recorded. Use Channels.send when the agent should remember them.

import { LuaTool, Channels } from 'lua-cli';
import { z } from 'zod';

// The #support-leads channel; the bot must be a member.
const LEADS_CHANNEL = 'C0123ABCDEF';

export default class EscalateToLeadsTool implements LuaTool {
  name = 'escalate_to_leads';
  description = 'Tell the support leads in Slack about a problem that needs them';
  inputSchema = z.object({ summary: z.string() });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const sent = await Channels.send({
      channel: 'slack',
      to: { conversationId: LEADS_CHANNEL },
      text: `Escalation: ${input.summary}`,
    });
    return { posted: sent.delivered, messageId: sent.messageId };
  }
}

​

Limits

• Permissions: twelve required, eight optional, and chat:write.public, listed with what each is for on Slack permissions.
• One private connection per workspace and app; one public connection per App ID per agent.
• images renders up to 10 images.
• documents uploads up to 10 files per answer, each up to 25 MB and stored on Lua’s CDN; the rest arrive as links.
• Channels.send posts about one message per second per channel, Slack’s own limit for the bot.
• Link commands (link-me-to:, remove-my-link) and the links they create apply to direct messages only, not to channels or group DMs.

​

Troubleshooting

​

Next steps