# How to Integrate Bolt.new with Flock

- Tool: Bolt.new
- Difficulty: Intermediate
- Time required: 25 minutes
- Last updated: April 2026

## TL;DR

Integrate Bolt.new with Flock by creating an app at dev.flock.com, getting an API token, and sending messages to channels via a Next.js API route. Flock's REST API supports channel messaging, user management, and bot creation with simpler setup than Slack. Outbound API calls and channel messages work in Bolt's WebContainer preview; Flock webhook events and slash command responses require a deployed public URL.

## Building Flock Team Notifications and Bots from Bolt.new Apps

Flock is a team communication platform that is particularly popular among startups and technology companies in India and Southeast Asia. With approximately 5 million users and backing from Tiger Global, it competes with Slack in the SMB segment but with a significantly lower price point and a simpler integration API. For Bolt developers building apps used by teams in these regions, or teams that have chosen Flock for cost reasons, integrating notifications and bots is a practical requirement.

Flock's API is simpler than Slack's in both capability and setup. There is no complex OAuth flow for basic integrations — you create an app in Flock's developer portal, get a token, and use it to call REST endpoints. The main difference from Slack is scope: Flock's API has fewer event types, fewer interactive component options, and a smaller ecosystem of third-party integrations. For basic use cases — channel notifications, message formatting with buttons, user lookups, and simple bots — Flock's API covers everything you need.

All Flock outbound API calls (sending messages, fetching channel info) are standard HTTPS requests that work from Bolt's WebContainer preview. You can build and test notification workflows entirely without deploying. The functionality that requires a deployed public URL includes: slash command handlers (Flock sends a POST request to your server when a user runs a slash command) and interactive message buttons that trigger server-side callbacks. For unidirectional notification apps, development in the Bolt preview is entirely sufficient.

## Before you start

- A Flock account and team workspace (free plan available at flock.com)
- A Flock app created at dev.flock.com with a bot token generated
- The bot token from your Flock app (displayed in the app settings after creation)
- The channel token or channel ID for the Flock channel where you want to send messages
- A Next.js project in Bolt.new — prompt 'Create a Next.js app' if starting fresh

## Step-by-step guide

### 1. Create a Flock app and get your API credentials

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.

```
// .env.local
FLOCK_BOT_TOKEN=your_bot_token_here
FLOCK_CHANNEL_TOKEN=your_channel_token_here

// lib/flock.ts
export async function flockFetch(
  endpoint: string,
  method: 'GET' | 'POST' = 'GET',
  body?: Record<string, unknown>
): Promise<Response> {
  const token = process.env.FLOCK_BOT_TOKEN!;
  const url = `https://api.flock.com/v2${endpoint}`;

  return fetch(url, {
    method,
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
  });
}

type FlockAttachment = {
  title?: string;
  description?: string;
  color?: string;
  actions?: Array<{ name: string; url: string }>;
};

export async function sendFlockMessage(
  channelToken: string,
  text: string,
  attachments?: FlockAttachment[]
) {
  const body: Record<string, unknown> = {
    token: channelToken,
    text,
    ...(attachments ? { attachments: JSON.stringify(attachments) } : {}),
  };

  return flockFetch('/chat.sendMessage', 'POST', body);
}
```

**Expected result:** Your Flock app is created at dev.flock.com, .env.local contains FLOCK_BOT_TOKEN and FLOCK_CHANNEL_TOKEN, and the flockFetch/sendFlockMessage utilities are ready to use.

### 2. Send formatted messages and notification widgets to Flock

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.

```
// app/api/flock/notify/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { sendFlockMessage } from '@/lib/flock';

const SEVERITY_COLORS: Record<string, string> = {
  success: '#28a745',
  error: '#dc3545',
  warning: '#ffc107',
  info: '#17a2b8',
};

export async function POST(request: NextRequest) {
  const {
    title,
    message,
    severity = 'info',
    actionUrl,
    actionLabel,
  } = await request.json();

  if (!title || !message) {
    return NextResponse.json(
      { error: 'title and message are required' },
      { status: 400 }
    );
  }

  const channelToken = process.env.FLOCK_CHANNEL_TOKEN!;
  const color = SEVERITY_COLORS[severity] ?? SEVERITY_COLORS.info;

  const attachment: Record<string, unknown> = {
    title,
    description: message,
    color,
  };

  if (actionUrl && actionLabel) {
    attachment.actions = [{ name: actionLabel, url: actionUrl }];
  }

  const response = await sendFlockMessage(
    channelToken,
    `${title}`,
    [attachment as { title?: string; description?: string; color?: string; actions?: Array<{ name: string; url: string }> }]
  );

  if (!response.ok) {
    const error = await response.json();
    return NextResponse.json({ error }, { status: response.status });
  }

  const data = await response.json();
  return NextResponse.json({ success: true, uid: data.uid });
}
```

**Expected result:** POST /api/flock/notify with a title, message, and severity sends a color-coded widget message to your Flock channel. The message appears in Flock within 1–2 seconds with the correct accent color and optional action button.

### 3. Fetch channel information and user details

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.

```
// app/api/flock/channels/route.ts
import { NextResponse } from 'next/server';
import { flockFetch } from '@/lib/flock';

export async function GET() {
  const response = await flockFetch('/channels.list');

  if (!response.ok) {
    return NextResponse.json({ error: 'Flock API error' }, { status: response.status });
  }

  const data = await response.json();

  const channels = (data.channels ?? []).map((c: Record<string, unknown>) => ({
    id: c.uid,
    name: c.name,
    memberCount: c.memberCount ?? 0,
    description: c.description ?? '',
  }));

  return NextResponse.json({ channels, total: channels.length });
}
```

**Expected result:** GET /api/flock/channels returns a list of all channels in your Flock workspace that the bot has access to, with their IDs, names, and member counts.

### 4. Set up slash commands and interactive responses after deployment

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.

```
// app/api/flock/slash/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  // Flock sends slash command data as URL-encoded form or query params
  const { searchParams } = new URL(request.url);
  const token = searchParams.get('token');
  const userId = searchParams.get('userId') ?? '';
  const text = searchParams.get('text') ?? '';
  const channelId = searchParams.get('channelId') ?? '';

  // Verify this request came from Flock
  if (token !== process.env.FLOCK_SLASH_TOKEN) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const command = text.trim().toLowerCase();

  if (command === 'status' || command === '') {
    return NextResponse.json({
      text: 'App Status',
      attachments: JSON.stringify([
        {
          title: 'System Status',
          description: 'All systems operational',
          color: '#28a745',
          actions: [
            { name: 'View Dashboard', url: process.env.NEXT_PUBLIC_BASE_URL ?? '#' },
          ],
        },
      ]),
    });
  }

  // Default: show help
  return NextResponse.json({
    text: 'Available commands:\n• `/bolt status` — Check app status\n• `/bolt help` — Show this message',
  });
}
```

**Expected result:** After deploying and registering the slash command in dev.flock.com, typing /bolt status in a Flock channel triggers a POST to your deployed endpoint and returns a status widget card in the channel.

## Best practices

- Store FLOCK_BOT_TOKEN and FLOCK_CHANNEL_TOKEN as server-side environment variables only — never use NEXT_PUBLIC_ prefix as they would be exposed in the browser bundle and allow anyone to post to your Flock channels.
- Cache frequently used channel tokens in separate environment variables (FLOCK_ENGINEERING_CHANNEL, FLOCK_ALERTS_CHANNEL) rather than fetching them from the API on every request — channel tokens are stable identifiers.
- Respond to Flock slash commands within 3 seconds — if your logic takes longer, send an immediate acknowledgment response and post the full result asynchronously via a separate sendFlockMessage call.
- Test all channel notification logic (message formatting, widget colors, action buttons) in Bolt's WebContainer preview — sending messages to Flock channels is an outbound HTTPS call that works without deployment. Only deploy when you need slash commands or interactive button callbacks.
- Use severity color coding consistently in your notification widgets — standardize colors across your team (green for success, red for errors, yellow for warnings) so team members can visually parse alerts at a glance.
- Include a direct action URL in notification widgets whenever possible — a 'View Details' button linking to the relevant page in your Bolt app reduces the friction of investigating alerts and makes notifications more actionable.
- Verify incoming slash command requests using the FLOCK_SLASH_TOKEN parameter — check it against your stored token to confirm requests are genuinely from Flock before processing them.

## Use cases

### App event notification system for team channels

Send formatted notifications to a Flock channel when important events occur in your Bolt app — new user signups, form submissions, payment completions, or error alerts. Messages use Flock's rich text formatting and attachment widgets to display structured data with action buttons.

Prompt example:

```
Create a /api/flock/notify route that sends a formatted message to a Flock channel when called. The message should have a title, body text, a color-coded widget (green for success, red for error), and an optional button with a link. Test it by sending a sample notification from the UI.
```

### Deployment pipeline status updates

Post build and deployment status messages to your engineering team's Flock channel automatically. When a Vercel deployment succeeds or fails, your webhook handler posts a card to Flock with the project name, status, commit message, and a link to the deployment.

Prompt example:

```
Build a /api/flock/deploy-status route that accepts POST with projectName, status (success/failed), deploymentUrl, commitMessage, and branch. Send a Flock widget message with an appropriate title, color-coded status badge, and 'View Deployment' button to the FLOCK_CHANNEL_TOKEN env variable.
```

### Daily digest bot for team metrics

Create a scheduled bot that sends a daily summary message to a Flock channel with key metrics from your app — daily active users, signups, revenue, or support tickets. The bot runs on a schedule and pulls data from your database before formatting it into a Flock message.

Prompt example:

```
Create a /api/flock/daily-digest route that fetches summary metrics from /api/metrics/daily and sends a formatted Flock message with today's stats: new signups count, active users, and top page. Format numbers with proper commas and percentage changes from yesterday. Add a 'View Dashboard' button.
```

## Troubleshooting

### Message sending returns 'invalid_token' error even with a freshly generated bot token

Cause: The bot token is being used to send to a channel token that the bot does not have access to, or the tokens were confused — bot token used as channel token or vice versa. Flock has separate bot tokens (for authentication) and channel tokens (for identifying target channels).

Solution: Verify that FLOCK_BOT_TOKEN is the bot authentication token from dev.flock.com and FLOCK_CHANNEL_TOKEN is the destination channel token from your Flock admin settings. These are different values. In the sendFlockMessage function, the Authorization header uses the bot token while the body token field uses the channel token.

```
// Correct: bot token in header, channel token in body
const body = {
  token: channelToken,  // destination channel
  text: message,
};
fetch(url, {
  headers: { Authorization: `Bearer ${botToken}` }, // authentication
});
```

### Slash command returns a 404 or connection refused error in Flock when the command is invoked

Cause: The slash command endpoint URL is pointing to the Bolt WebContainer preview URL, which is not publicly accessible from Flock's servers, or the endpoint path does not match what was registered in dev.flock.com.

Solution: Deploy your app to Netlify or Vercel first, then register the slash command endpoint with your deployed domain URL (e.g., https://your-app.netlify.app/api/flock/slash). The Bolt preview URL ending in .webcontainer-api.io is only accessible from your local browser session.

### Channel messages appear but with no formatting — plain text instead of colored widget cards

Cause: The attachments parameter is not being JSON-stringified correctly, or the attachment object structure does not match Flock's expected format. Flock silently drops malformed attachments and sends only the plain text.

Solution: Ensure the attachments value is a JSON-stringified string when passed in the request body: attachments: JSON.stringify([{ title, description, color }]). Verify the color field uses a valid hex color with the # prefix (e.g., '#28a745'). Test the attachment JSON structure with the Flock API playground at dev.flock.com.

```
// Correct: JSON-stringified attachments
const body = {
  token: channelToken,
  text: 'Notification',
  attachments: JSON.stringify([{ title: 'Alert', description: 'Details here', color: '#dc3545' }]),
};
```

## Frequently asked questions

### Does Bolt.new have a native Flock integration?

No. Flock is not one of Bolt's native connectors. You build the integration manually using Next.js API routes and the Flock REST API. Bolt's AI can generate the boilerplate code when you describe what messaging features you need, but you manage the Flock app registration and credentials yourself.

### Can I send Flock messages from Bolt's development preview without deploying?

Yes. Sending messages to Flock channels and fetching channel data are outbound API calls that work perfectly from Bolt's WebContainer — they are standard HTTPS requests to Flock's API servers. The features that require deployment are slash command handlers and interactive button callbacks, which need Flock to be able to POST requests back to your server. For unidirectional notification integrations, development in the Bolt preview is fully functional.

### How is Flock different from Slack for API integration?

Flock's API is simpler with fewer steps to get a token and start sending messages, but it has a smaller feature set. Flock's interactive components (action buttons, slash commands) are more limited than Slack's Block Kit. Flock's webhook and event subscription systems are less comprehensive than Slack's Events API. For basic notifications and simple bots, Flock is faster to integrate; for complex interactive workflows, Slack has better developer tooling and documentation.

### What are Flock channel tokens and where do I find them?

Flock uses two types of tokens: bot tokens (for authentication, obtained from dev.flock.com) and channel tokens (for identifying message destinations, found in your Flock workspace admin settings). To find channel tokens, go to your Flock workspace → Admin → Integrations → API → Channel Tokens. Each channel has a unique token that you use in the token field of the chat.sendMessage body. The bot token goes in the Authorization header.

### Does Flock have a free plan for API integrations?

Yes. Flock's free plan includes 10,000 message history, unlimited channels, and access to the REST API. Custom app integration and bot creation through dev.flock.com work on the free plan. Flock's Pro plan ($4.50/user/month) adds unlimited message history, video calls, and additional admin features but the API access is available on all plans.

---

Source: https://www.rapidevelopers.com/bolt-ai-integrations/flock
© RapidDev — https://www.rapidevelopers.com/bolt-ai-integrations/flock