Appearance
Build an app ​
This page builds a small "deploy bot" from start to finish: it posts into a channel, answers /deploy <env>, asks for a click on a card, and listens to events, with every request verified.
Your own apps need the Team plan. The examples use https://connect.example.com as your server and placeholders like $CONNECT_TOKEN for secrets.
What you build ​
Ana types /deploy staging in #deploys. The bot posts a card, "Deploy staging?", with a button. When Ben clicks it, the bot replaces the card with "Deployed to staging." The bot also hears when someone reacts to a message.
Steps ​
- Write the manifest
- Install it and choose a channel
- Post a message with the app's token
- Run the handler: verify, then answer a command
- Send a card and handle the click
- Hear other events
- Replay deliveries
1. Write the manifest ​
A manifest says who the app is, what it may do and where Connectdary sends events. Save it as manifest.json. It can be at most 16 KB, and a field Connectdary doesn't know is refused.
json
{
"manifestVersion": 1,
"name": "Deploy bot",
"description": "Deploys from chat and reports back.",
"publisher": { "name": "Acme", "domain": "acme.example" },
"icon": { "emoji": "🚀" },
"scopes": {
"required": ["messages:read", "messages:write", "events:read", "reactions:read"],
"optional": []
},
"commands": [{ "name": "deploy", "description": "Deploy to an environment", "usage": "<env>" }],
"events": {
"url": "https://deploy-bot.example.com/connect",
"types": ["command.invoked", "action.invoked", "reaction.added"]
},
"components": ["button"],
"redirectUrl": "https://deploy-bot.example.com/oauth/callback"
}What the fields do:
scopes.requiredis what the app always gets;optionalones show up as switches when someone installs it.commandsadds/deploy. A name is lowercase letters, digits,-and_, and each name belongs to one app per workspace.events.urlmust be HTTPS. It must be a public address: Connectdary never reaches a private network unless the operator allows it.events.typeslists what the app hears. Each type needs the scope that decides who may hear it:reaction.addedneedsreactions:read, and anyeventsentry needsevents:read.componentssays the app posts buttons, selects or forms. These needevents:readtoo, because clicks arrive as events.redirectUrlis where Connectdary sends people after they sign in to the app. It is matched exactly.
2. Install it and choose a channel ​
- Open Settings › Integrations and choose Install from a manifest.
- Paste the manifest (or give the link it is published at) and choose Review.
- Pick
#deploys. Connectdary shows, in plain words, what the app will do there: "Post messages in #deploys", "Add /deploy", "Send what it hears to deploy-bot.example.com". - Choose Allow. Connectdary shows the app's Token and Signing secret once. Copy both.
The channel you picked is the app's first grant: it can read and post there, and nowhere else. To add #releases later, open the app's page in Settings › Integrations and choose Add to a channel.
INFO
Only admins are handed the token and the signing secret. When a member installs an app, the app itself gets its token by signing in (OAuth).
3. Post a message with the app's token ​
Every message needs a topic: give an existing topic's topic, or a topic_ref you choose plus a title. The same topic_ref always reaches the same topic.
bash
curl https://connect.example.com/api/v1/messages \
-H "Authorization: Bearer $CONNECT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"conversation": "<channel id>",
"topic_ref": "deploys",
"title": "Deploys",
"text": "Deploy bot is online. Try /deploy staging."
}'The message shows the app's name and icon with an App label. Posting where the app has no grant is refused.
4. Run the handler ​
Connectdary signs every event it sends. The Connect-Signature header looks like this:
text
Connect-Signature: t=1793290739,v1=5257a869e7ecebeda32af...v1 is the hex HMAC-SHA256, keyed with the signing secret, of the timestamp, a dot and the raw request body: t + "." + body. While you rotate a secret, the header carries two v1 values (the new and the old one), so accept a request if any of them matches. Reject old timestamps to stop replays.
Each request also carries Connect-Delivery (the same id on every retry, so you can drop duplicates) and Connect-Event (the event type).
This handler runs on Bun. It verifies the signature, then answers /deploy later through the responseUrl in the event. Run it with CONNECT_URL, CONNECT_TOKEN and SIGNING_SECRET set.
ts
// handler.ts
import { createHmac, timingSafeEqual } from "node:crypto";
const connect = process.env.CONNECT_URL!; // https://connect.example.com
const token = process.env.CONNECT_TOKEN!;
const secret = process.env.SIGNING_SECRET!;
function verified(body: string, header: string | null) {
const parts = (header ?? "").split(",").map((p) => p.split("="));
const t = parts.find(([k]) => k === "t")?.[1] ?? "";
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest();
return parts.some(
([k, v]) =>
k === "v1" &&
v?.length === expected.length * 2 &&
timingSafeEqual(Buffer.from(v, "hex"), expected),
);
}
const post = (url: string, headers: Record<string, string>, json: unknown) =>
fetch(url, {
method: "POST",
headers: { "content-type": "application/json", ...headers },
body: JSON.stringify(json),
});
export default {
port: Number(process.env.PORT ?? 3000),
async fetch(req: Request) {
const body = await req.text();
if (!verified(body, req.headers.get("connect-signature")))
return new Response("bad signature", { status: 401 });
const { type, data } = JSON.parse(body);
if (type === "command.invoked") {
const env = data.text.trim() || "staging";
// Not awaited: any 2xx answer acknowledges the delivery.
void post(data.responseUrl, {}, { text: `Deploying to ${env}...` });
}
return new Response("ok");
},
};Start it with bun handler.ts, and make it reachable at the events.url from your manifest.
When Ana runs /deploy staging, Connectdary answers her at once and sends your app a command.invoked event. It carries text (staging), userId, and a responseUrl. The responseUrl has its own secret, so it needs no Authorization header. Post to it up to five times within 30 minutes; after that Connectdary says the command has expired.
The text body takes response_type:
ephemeral(the default): only Ana sees the answer.in_topic: the answer appears in the topic as "Ana used /deploy staging", followed by your text. Only an app that is in that channel may do this.
If the app isn't in the channel where Ana ran the command, the event has no conversationId or topicId, and the app can answer only Ana, privately.
5. Send a card and handle the click ​
Extend the command.invoked branch to post a card with a button into the topic where the command ran:
ts
if (data.conversationId)
void post(
`${connect}/api/v1/messages`,
{ authorization: `Bearer ${token}` },
{
conversation: data.conversationId,
topic: data.topicId,
text: `Deploy ${env}?`, // shown in notifications and by clients without cards
components: [
{
type: "actions",
buttons: [{ id: "go", label: `Deploy to ${env}`, style: "primary", value: env }],
},
],
},
);Besides actions, a message can carry status cards, tables, selects, choices and context lines. A context line is small print at the foot of the message, above its buttons: who asked, how long it took, a link to the logs. It takes inline Markdown (links, bold, italic, code) and up to 300 characters, and needs no entry in the manifest's components:
ts
{ type: "context", text: "Requested by Ana · 9s · [logs](https://ci.example/42)" }A choice asks one person to pick between two and ten options, as a vertical list. Each option has a label (up to 80 characters) and, if you like, a one-line description under it. It has an id, unique in the message like a button's, and its values are unique too. List choice in the manifest's components:
ts
{
type: "choice",
id: "next",
options: [
{ label: "Ship it", value: "ship", description: "Release to everyone now" },
{ label: "Wait", value: "wait" },
],
}When someone picks one, action.invoked carries action: { id: "next", type: "choice", value: "ship" }. Answer it like a button's action.
When Ben clicks Deploy to staging, Connectdary sends your app an action.invoked event:
- You acknowledge it by answering the request with any 2xx within 10 seconds. Otherwise Ben is told the app didn't respond, and can try again.
- You then have 30 minutes to answer through the event's
responseUrl, once. After that Connectdary says the action has expired. data.action.valueis thevalueyou gave the button; people never choose it.data.user.nameis there only if the app has thepeople:readscope.
Add this branch to the handler:
ts
if (type === "action.invoked") {
void post(
data.responseUrl,
{},
{
text: `Deployed to ${data.action.value}.`, // replaces the message text
components: null, // removes the button
result: "Deployed", // "Deployed by Ben · 9:42" at the foot of the card
},
);
}Ben sees the card change to "Deployed to staging." A retry of the same click reuses the same action, so your app never deploys twice; the Connect-Delivery header is the same each time.
People who can't read the channel can't use the button. If an admin switches the app off, the button stops working.
6. Hear other events ​
You already subscribed in the manifest. reaction.added arrives as a signed request like the others:
ts
if (type === "reaction.added") console.log(data.emoji, data.messageId);Polls ​
An app that posts a poll through POST /messages with a poll hears two events about it, and only about its own polls:
poll.votedeach time someone votes or takes their vote back.data.userIdsays who, with thepeople:readscope, and is never there for an anonymous poll.poll.closedonce, when the app closes the poll withPOST /messages/{id}/poll/closeor when itsclosesAtpasses, whichever comes first.
Both carry data.poll: messageId, conversationId, topicId, question, multiple, anonymous, closed, closesAt, options (id, label, votes), voters and winnerIds (the options with the most votes, once it is closed). votes and voters are null while an anonymous poll in a small room hides its counts, until it closes.
An app hears only what its grants cover, never its own actions, and never anything in a channel it hasn't been granted. A failed delivery is retried for a day. If every try fails for a whole day, Connectdary switches the subscription off and notes it in the audit log.
To point events at another address, or change which events arrive, open the app's page in Settings › Integrations and edit its outgoing events. Send test there sends a signed ping.
To rotate the signing secret, choose Rotate secret on that row. Both secrets sign for 24 hours, so you can deploy the new one without a gap, and a second rotation within that day is refused.
7. Replay deliveries ​
Connectdary keeps deliveries for 30 days. If your handler was down, replay them.
Redeliver one. In Settings › Developer, find the delivery and choose Redeliver. Or from your app:
bash
curl -X POST https://connect.example.com/api/v1/deliveries/$DELIVERY_ID/redeliver \
-H "Authorization: Bearer $CONNECT_TOKEN"Replay from a time. In Settings › Developer, choose Replay… and pick a time, or from your app give a time in milliseconds since the epoch:
bash
curl -X POST https://connect.example.com/api/v1/subscriptions/$SUBSCRIPTION_ID/replay \
-H "Authorization: Bearer $CONNECT_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"from\": $(( ($(date +%s) - 3600) * 1000 ))}"Connectdary answers with how many events it will send, then sends them in order. Check on it with GET /api/v1/replays/<id>; its status is running, then done.
Things to know:
- Replays go back 30 days at most, and cover at most 5,000 events. A later start time fixes "too many".
- Commands and button clicks are not replayed: they belong to a moment that has passed.
- A replay sends events again with the same
Connect-Deliveryid and aConnect-Redelivery: 1header, so de-duplicate on the id. - A replay leaves out channels the app has lost its grant on.
- Each app may start 5 replays an hour.
What to read next ​
- Use the API for reading messages, topics and more with a token.
- Apps and integrations for how admins install, limit and switch off apps.