How to Integrate Bolt.new with Flock

Navigate to dev.flock.com in your browser and sign in with your Flock account. If you do not have a Flock developer account, you will need to create one — it uses the same credentials as your Flock workspace login. Once signed in, click Create App. Fill in the app name (e.g., 'Bolt Integration'), description, and choose an icon if desired. After creating the app, navigate to the Bot section in your app settings. Enable the Bot feature and configure the bot username — this is the name that will appear in Flock channels when your integration sends messages. Flock bots can post messages to channels, respond to direct messages, and handle slash commands. In the Token section of your app, generate a Bot Token. This is the credential your server will use to call the Flock API. Copy it — it looks like a long alphanumeric string. Store it as FLOCK_BOT_TOKEN in your Bolt project's .env.local file. To send messages to a specific channel, you need the channel's token. You can find channel tokens in Flock's admin settings: go to your Flock workspace → Admin → Apps & Integrations → API → Channel Tokens. Each channel has a unique token that identifies it in API calls. Alternatively, you can fetch channels programmatically via GET https://api.flock.com/v2/channels.list with your bot token. Store your primary notification channel's token as FLOCK_CHANNEL_TOKEN in .env.local. The Flock REST API base URL is https://api.flock.com/v2/ and all endpoints accept the token as either a query parameter (?token=your_token) or as an Authorization: Bearer header. The Bearer header approach is cleaner for server-side use.

1// .env.local
2FLOCK_BOT_TOKEN=your_bot_token_here
3FLOCK_CHANNEL_TOKEN=your_channel_token_here
4
5// lib/flock.ts
6export async function flockFetch(
7  endpoint: string,
8  method: 'GET' | 'POST' = 'GET',
9  body?: Record<string, unknown>
10): Promise<Response> {
11  const token = process.env.FLOCK_BOT_TOKEN!;
12  const url = `https://api.flock.com/v2${endpoint}`;
13
14  return fetch(url, {
15    method,
16    headers: {
17      Authorization: `Bearer ${token}`,
18      'Content-Type': 'application/json',
19    },
20    ...(body ? { body: JSON.stringify(body) } : {}),
21  });
22}
23
24type FlockAttachment = {
25  title?: string;
26  description?: string;
27  color?: string;
28  actions?: Array<{ name: string; url: string }>;
29};
30
31export async function sendFlockMessage(
32  channelToken: string,
33  text: string,
34  attachments?: FlockAttachment[]
35) {
36  const body: Record<string, unknown> = {
37    token: channelToken,
38    text,
39    ...(attachments ? { attachments: JSON.stringify(attachments) } : {}),
40  };
41
42  return flockFetch('/chat.sendMessage', 'POST', body);
43}

Flock supports rich message formatting through its Widgets system — JSON objects that define structured cards with titles, descriptions, color accents, and action buttons. Widgets are passed as the attachments parameter (a JSON-stringified array) when calling chat.sendMessage. A Flock widget object can have: title (bold heading), description (body text, supports basic HTML-like formatting), color (hex color for the left accent stripe, e.g., '#28a745' for green), and actions (an array of button objects with name and url). Widgets are more visually structured than plain text messages and are ideal for notifications that need to convey status, include data, and provide a direct link. The chat.sendMessage endpoint accepts these key parameters: token (the channel token for the target channel), text (plain text message shown above any attachment widgets), attachments (JSON-stringified array of widget objects), and sendAs (optional, to override the bot display name for this message). All Flock API calls in this step are outbound POST requests from your server-side Next.js route to Flock's API servers. They work perfectly in Bolt's WebContainer — no CORS issues, no deployment required. You can test sending messages to your Flock channel directly from the development preview and verify they appear in Flock in real time. This is useful for iterating on message formatting quickly: change the widget JSON, trigger the API call from Bolt's preview, and immediately see how the message looks in Flock.

1// app/api/flock/notify/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { sendFlockMessage } from '@/lib/flock';
4
5const SEVERITY_COLORS: Record<string, string> = {
6  success: '#28a745',
7  error: '#dc3545',
8  warning: '#ffc107',
9  info: '#17a2b8',
10};
11
12export async function POST(request: NextRequest) {
13  const {
14    title,
15    message,
16    severity = 'info',
17    actionUrl,
18    actionLabel,
19  } = await request.json();
20
21  if (!title || !message) {
22    return NextResponse.json(
23      { error: 'title and message are required' },
24      { status: 400 }
25    );
26  }
27
28  const channelToken = process.env.FLOCK_CHANNEL_TOKEN!;
29  const color = SEVERITY_COLORS[severity] ?? SEVERITY_COLORS.info;
30
31  const attachment: Record<string, unknown> = {
32    title,
33    description: message,
34    color,
35  };
36
37  if (actionUrl && actionLabel) {
38    attachment.actions = [{ name: actionLabel, url: actionUrl }];
39  }
40
41  const response = await sendFlockMessage(
42    channelToken,
43    `${title}`,
44    [attachment as { title?: string; description?: string; color?: string; actions?: Array<{ name: string; url: string }> }]
45  );
46
47  if (!response.ok) {
48    const error = await response.json();
49    return NextResponse.json({ error }, { status: response.status });
50  }
51
52  const data = await response.json();
53  return NextResponse.json({ success: true, uid: data.uid });
54}

Beyond sending messages, the Flock API provides endpoints to read channel data and look up users — useful for dashboards that show team activity or for routing messages to the right channel dynamically. To list all channels your bot has access to, call GET /channels.list with your bot token. The response includes an array of channel objects with their id, name, and member count. This is how you discover the channel tokens for different channels in your workspace without going through the admin UI. To fetch details about a specific channel including its members, call GET /channels.info?token={botToken}&channelId={id}. For user information, GET /users.info?token={botToken}&userId={id} returns the user's name, email, profile picture, and online status. For direct messages, use chat.sendMessage with a userId instead of a channel token in the token parameter — Flock routes the message as a direct message to that user. This requires the bot to have been added to the workspace and the user to have messaged the bot first (or be in a shared channel). These API calls are all outbound HTTPS GET and POST requests that work from Bolt's WebContainer. Build your channel listing and user directory features entirely in the development preview before deploying. The data is real — it reflects your actual Flock workspace structure — so you can verify the API responses match what you expect before writing the frontend components.

1// app/api/flock/channels/route.ts
2import { NextResponse } from 'next/server';
3import { flockFetch } from '@/lib/flock';
4
5export async function GET() {
6  const response = await flockFetch('/channels.list');
7
8  if (!response.ok) {
9    return NextResponse.json({ error: 'Flock API error' }, { status: response.status });
10  }
11
12  const data = await response.json();
13
14  const channels = (data.channels ?? []).map((c: Record<string, unknown>) => ({
15    id: c.uid,
16    name: c.name,
17    memberCount: c.memberCount ?? 0,
18    description: c.description ?? '',
19  }));
20
21  return NextResponse.json({ channels, total: channels.length });
22}

Flock's slash commands allow users to trigger actions in your Bolt app directly from Flock's message input. When a user types /your-command in Flock, Flock POSTs a request to your server with the command name and any arguments. Your server processes the request and responds with a message to display in the channel. Like all incoming HTTP connections, slash command requests from Flock cannot reach Bolt's WebContainer — the WebContainer has no public URL and runs inside a browser tab. You must deploy your app to Netlify or Vercel first, then register your slash command endpoint. To register a slash command: go to your Flock app at dev.flock.com → your app → Slash Commands. Add a new slash command with the name (e.g., 'status'), description, and the endpoint URL (https://your-deployed-app.netlify.app/api/flock/slash). Flock will POST to this URL when any workspace member runs the command. Your slash command handler receives a POST request with query parameters: token (a verification token to confirm the request came from Flock), userId, userName, channelId, text (the arguments after the command name), and flockEvent. Return a JSON response with text and optional attachments — this response is posted to the channel where the command was used. For interactive buttons on messages (buttons that trigger server-side actions when clicked), Flock uses Action URLs — URLs embedded in the button definition that Flock calls when the button is clicked. These also require a deployed server endpoint. Add action URLs to your Flock widget attachments after deploying.

1// app/api/flock/slash/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function POST(request: NextRequest) {
5  // Flock sends slash command data as URL-encoded form or query params
6  const { searchParams } = new URL(request.url);
7  const token = searchParams.get('token');
8  const userId = searchParams.get('userId') ?? '';
9  const text = searchParams.get('text') ?? '';
10  const channelId = searchParams.get('channelId') ?? '';
11
12  // Verify this request came from Flock
13  if (token !== process.env.FLOCK_SLASH_TOKEN) {
14    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
15  }
16
17  const command = text.trim().toLowerCase();
18
19  if (command === 'status' || command === '') {
20    return NextResponse.json({
21      text: 'App Status',
22      attachments: JSON.stringify([
23        {
24          title: 'System Status',
25          description: 'All systems operational',
26          color: '#28a745',
27          actions: [
28            { name: 'View Dashboard', url: process.env.NEXT_PUBLIC_BASE_URL ?? '#' },
29          ],
30        },
31      ]),
32    });
33  }
34
35  // Default: show help
36  return NextResponse.json({
37    text: 'Available commands:\n• `/bolt status` — Check app status\n• `/bolt help` — Show this message',
38  });
39}