Actions

Actions let you handle button clicks, dropdown selections, and other interactive events from cards. Register handlers with onAction to respond when users interact with your cards.

Handle a specific action

bot.onAction("approve", async (event) => {
  await event.thread.post(`Order approved by ${event.user.fullName}!`);
});

Handle multiple actions

bot.onAction(["approve", "reject"], async (event) => {
  const action = event.actionId === "approve" ? "approved" : "rejected";
  await event.thread.post(`Order ${action} by ${event.user.fullName}`);
});

Catch-all handler

Register a handler without an action ID to catch all actions:

bot.onAction(async (event) => {
  console.log(`Action: ${event.actionId}, Value: ${event.value}`);
});

ActionEvent

The event object passed to action handlers:

Pass data with buttons

Use the value prop on buttons to pass extra context to your handler:

<Button id="report" value="bug">Report Bug</Button>
<Button id="report" value="feature">Request Feature</Button>

bot.onAction("report", async (event) => {
  if (event.value === "bug") {
    // Open bug report flow
  } else if (event.value === "feature") {
    // Open feature request flow
  }
});

Read a text box on the card

On Teams, a card can carry a TextInput. What the user typed arrives on the action as event.values, keyed by input ID, in the same shape as ModalSubmitEvent.values:

<Card title="Deploy to production?">
  <TextInput id="notes" label="Notes" multiline optional />
  <Actions>
    <Button id="approve" style="primary">Approve</Button>
  </Actions>
</Card>

bot.onAction("approve", async (event) => {
  const notes = event.values?.notes?.trim().slice(0, 500) ?? "";
  await recordApproval({ userId: event.user.userId, notes });
  await event.thread?.post("Approved");
});

recordApproval stands in for your own storage or deploy logic. values is absent on platforms that cannot put an input on a card, and on cards that have none.

Treat event.values as untrusted user input. Teams enforces optional and maxLength in its own UI, but a value can still arrive missing, empty, or longer than the limit, so validate it in the handler. If you post a value back into the thread, the platform renders any markdown the user typed, such as a link, in a message that appears to come from the bot. Wrapping the value in a code span or sending it as { raw } does not prevent this, so store or process the value instead of echoing it.

Open a modal from an action

Use event.openModal() to open a modal in response to a button click:

import { Modal, TextInput, Select, SelectOption } from "chat";

bot.onAction("feedback", async (event) => {
  await event.openModal(
    <Modal callbackId="feedback_form" title="Send Feedback" submitLabel="Send">
      <TextInput id="message" label="Your Feedback" multiline />
      <Select id="category" label="Category">
        <SelectOption label="Bug" value="bug" />
        <SelectOption label="Feature" value="feature" />
      </Select>
    </Modal>
  );
});

Callback URLs

Buttons accept a callbackUrl prop. When a user clicks the button, the action data is POSTed to that URL in addition to firing any onAction handler. With a webhook-based workflow engine, you can build approval flows without an onAction handler:

bot.onNewMention(async (thread) => {
  const approveUrl = "https://example.com/webhook/approve";
  const denyUrl = "https://example.com/webhook/deny";

  await thread.post(
    <Card title="Deploy v2.4.1?">
      <Actions>
        <Button callbackUrl={approveUrl} id="approve" style="primary">
          Approve
        </Button>
        <Button callbackUrl={denyUrl} id="deny" style="danger">
          Deny
        </Button>
      </Actions>
    </Card>
  );
});

Callback tokens are bound to the button action and conversation, expire after seven days, and are consumed on first use. A repeated click or an attempt to move the token to another conversation does not trigger the callback URL again.

Callback payload

The POST body sent to the callbackUrl:

{
  "type": "action",
  "actionId": "approve",
  "user": { "id": "U123", "name": "alice" },
  "threadId": "slack:C123:1234567890.123",
  "messageId": "1234567890.456",
  "receipt": "3f2b8c1e-5d4a-4e7b-9c6f-1a2b3c4d5e6f"
}

If the button also has a value prop, it is included in the payload as "value".

If the card carried inputs, the payload includes what the user typed as "values", keyed by input ID. This is the same object the handler reads as event.values, and it is omitted when the card has no inputs:

{
  "type": "action",
  "actionId": "approve",
  "values": { "notes": "ship it" },
  "user": { "id": "U123", "name": "alice" },
  "threadId": "teams:MTk6YWJjMTIzQHRocmVhZC50YWN2Mg:aHR0cHM6Ly9zbWJhLnRyYWZmaWNtYW5hZ2VyLm5ldC9hbWVyLw",
  "messageId": "1700000012345",
  "receipt": "8a7d6c5b-4e3f-4a2b-8c1d-0e9f8a7b6c5d"
}

receipt is an opaque identifier for a record of the click that Chat SDK stores in your state adapter for 24 hours, built from the platform's verified event rather than from this body. If Chat SDK can't store the receipt, it doesn't call the callback URL, and the button keeps working so the user can click again. Anyone who knows a callback URL can POST to it, so a request arriving at the URL doesn't prove that someone clicked the button, and a receiver that acts on who clicked shouldn't trust fields like user or actionId from the body. For approvals, use requestApproval, which redeems the receipt and verifies each click for you. Chat SDK doesn't export a way to redeem receipts in your own receivers.

For modals, see callbackUrl on modals.