How to Integrate Bolt.new with Buffer

Buffer's developer portal is at buffer.com/developers. The application registration process is straightforward compared to many social media APIs — no review process, instant credential generation, and a free developer account. Log into your Buffer account, then go to buffer.com/developers/apps/create (or navigate via the developer portal). Fill in the application name (visible to users during OAuth authorization), website URL, and description. The most important field is the OAuth Callback URL — enter your deployed app's callback URL in the format https://yourapp.netlify.app/api/auth/buffer/callback. You can only have one callback URL per app; for multiple environments, either create separate apps (one for development, one for production) or use a single deployed URL for all testing. After creating the application, Buffer shows you the Client ID (called 'client_id') and Client Secret ('client_secret'). Add these as BUFFER_CLIENT_ID and BUFFER_CLIENT_SECRET to your Bolt project's .env file. Also add BUFFER_REDIRECT_URI set to your callback URL. Buffer's OAuth 2.0 implementation uses the standard authorization code flow with one notable difference: Buffer's authorization endpoint URL is https://bufferapp.com/oauth2/authorize (not api.bufferapp.com). The token exchange endpoint is https://api.bufferapp.com/1/oauth2/token.php. Note the .php extension — this is a legacy detail of Buffer's API implementation. Scopes: Buffer's API uses a single scope model — there are no granular read/write scopes. Authorization grants full access to the user's Buffer account (profiles, updates, analytics). This means your app can read and write posts for all connected social profiles once the user authorizes. Communicate this clearly in your app's authorization prompt. Buffer access tokens do not expire — they remain valid until the user revokes access from their Buffer account settings. This simplifies token management significantly compared to APIs that require token refresh.

1// lib/buffer/config.ts
2export const BUFFER_AUTH_URL = 'https://bufferapp.com/oauth2/authorize';
3export const BUFFER_TOKEN_URL = 'https://api.bufferapp.com/1/oauth2/token.php';
4export const BUFFER_API_BASE = 'https://api.bufferapp.com/1';
5
6export function buildAuthUrl(state: string): string {
7  const params = new URLSearchParams({
8    client_id: process.env.BUFFER_CLIENT_ID ?? '',
9    redirect_uri: process.env.BUFFER_REDIRECT_URI ?? '',
10    response_type: 'code',
11    state,
12  });
13  return `${BUFFER_AUTH_URL}?${params.toString()}`;
14}
15
16export function getBufferHeaders(token: string): Record<string, string> {
17  return {
18    Authorization: `Bearer ${token}`,
19    'Content-Type': 'application/x-www-form-urlencoded',
20  };
21}
22
23export interface BufferProfile {
24  id: string;
25  service: 'twitter' | 'facebook' | 'linkedin' | 'instagram' | 'pinterest' | 'tiktok';
26  service_username: string;
27  service_id: string;
28  avatar_https: string;
29  formatted_service: string;
30  default: boolean;
31  paused: boolean;
32  disconnected: boolean;
33}
34
35export interface BufferUpdateStatistics {
36  reach?: number;
37  clicks?: number;
38  retweets?: number;
39  likes?: number;
40  comments?: number;
41}
42
43export interface BufferUpdate {
44  id: string;
45  created_at: number; // Unix timestamp
46  day: string;
47  due_time: string;
48  due_at: number;
49  profile_id: string;
50  profile_service: string;
51  status: 'buffer' | 'sent' | 'service_update_sent';
52  text: string;
53  text_formatted?: string;
54  statistics?: BufferUpdateStatistics;
55}

Buffer's OAuth flow follows the standard authorization code pattern. The user clicks 'Connect Buffer,' is redirected to Buffer's authorization page, approves your app, and is redirected back to your callback URL with an authorization code. You exchange this code for a permanent access token. The authorization initiation route (GET /api/auth/buffer) generates a random state string for CSRF protection, stores it in a cookie, and redirects to Buffer's OAuth authorization page. Use the buildAuthUrl function from your config module to construct the full URL with client_id, redirect_uri, response_type=code, and state. The callback route (GET /api/auth/buffer/callback) handles the return from Buffer. It validates the state cookie, extracts the authorization code from query params, and POSTs to Buffer's token endpoint to exchange the code for an access token. Buffer's token endpoint accepts application/x-www-form-urlencoded data (not JSON) with fields: client_id, client_secret, redirect_uri, code, and grant_type=authorization_code. Buffer returns a JSON response with an access_token field and a token_type of 'bearer'. There is no refresh_token (Buffer tokens are permanent) and no expires_in. Store the access token in an HTTP-only cookie or your Supabase database. After getting the token, verify it works by calling GET /1/user.json — this returns the Buffer user object with the user's name, email, and account details. If this call succeeds, the token is valid and the OAuth flow is complete. Set the access token in a secure HTTP-only cookie and redirect to the dashboard. Error handling: Buffer redirects to your callback with an error parameter if the user denies access or if something goes wrong. Check for the error query param in your callback route and handle it with an appropriate redirect to your auth error page. As with all OAuth flows in Bolt.new: the callback URL must be publicly accessible. Deploy to Netlify or Bolt Cloud before testing the full OAuth flow. For development, you can generate a personal access token through Buffer's API and store it directly in BUFFER_ACCESS_TOKEN to skip OAuth during development.

1// app/api/auth/buffer/callback/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { BUFFER_TOKEN_URL } from '@/lib/buffer/config';
4
5export async function GET(request: NextRequest) {
6  const { searchParams } = new URL(request.url);
7  const code = searchParams.get('code');
8  const state = searchParams.get('state');
9  const error = searchParams.get('error');
10  const stateCookie = request.cookies.get('buffer_oauth_state')?.value;
11
12  // Handle user denying access
13  if (error) {
14    return NextResponse.redirect(
15      new URL(`/auth/error?reason=${encodeURIComponent(error)}`, request.url)
16    );
17  }
18
19  // CSRF validation
20  if (!state || state !== stateCookie) {
21    return NextResponse.redirect(new URL('/auth/error?reason=invalid_state', request.url));
22  }
23  if (!code) {
24    return NextResponse.redirect(new URL('/auth/error?reason=no_code', request.url));
25  }
26
27  try {
28    // Exchange authorization code for access token
29    const tokenResponse = await fetch(BUFFER_TOKEN_URL, {
30      method: 'POST',
31      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
32      body: new URLSearchParams({
33        client_id: process.env.BUFFER_CLIENT_ID ?? '',
34        client_secret: process.env.BUFFER_CLIENT_SECRET ?? '',
35        redirect_uri: process.env.BUFFER_REDIRECT_URI ?? '',
36        code,
37        grant_type: 'authorization_code',
38      }),
39    });
40
41    if (!tokenResponse.ok) {
42      const errorText = await tokenResponse.text();
43      console.error('Buffer token exchange failed:', errorText);
44      return NextResponse.redirect(new URL('/auth/error?reason=token_exchange', request.url));
45    }
46
47    const tokenData = await tokenResponse.json() as { access_token: string; token_type: string };
48    const accessToken = tokenData.access_token;
49
50    if (!accessToken) {
51      return NextResponse.redirect(new URL('/auth/error?reason=no_token', request.url));
52    }
53
54    // Set token in secure HTTP-only cookie
55    const response = NextResponse.redirect(new URL('/dashboard', request.url));
56    response.cookies.set('buffer_token', accessToken, {
57      httpOnly: true,
58      secure: process.env.NODE_ENV === 'production',
59      maxAge: 60 * 60 * 24 * 365, // Buffer tokens don't expire — 1 year for cookie
60      sameSite: 'lax',
61      path: '/',
62    });
63    response.cookies.delete('buffer_oauth_state');
64
65    return response;
66  } catch (err) {
67    console.error('Buffer OAuth callback error:', err);
68    return NextResponse.redirect(new URL('/auth/error?reason=server_error', request.url));
69  }
70}

After OAuth authorization, the first useful API call is fetching the user's connected social media profiles. Buffer profiles represent each connected social account — a Twitter account, a LinkedIn page, a Facebook Page, etc. These profiles are the target for creating new posts. The profiles endpoint is GET /1/profiles.json. With the Bearer token in the Authorization header, it returns an array of profile objects. Each profile has: id (the Buffer profile ID used in all subsequent calls), service (the social network name: 'twitter', 'facebook', 'linkedin', 'instagram', 'pinterest', 'tiktok'), service_username (the username on that network), service_id (the native ID on that network), avatar_https (profile picture URL), formatted_service (display name like 'Twitter'), and paused/disconnected booleans. For the profiles selector UI, display profiles as a grid of cards or a select dropdown. Show the social network name and icon (using the service field to pick an icon), the username or page name, and the profile picture avatar. Use distinct colors per network: Twitter/X in black, LinkedIn in blue, Facebook in dark blue, Instagram in gradient, etc. These visual cues help users quickly identify which accounts they are scheduling to. Filter out disconnected and paused profiles in your API route response. Disconnected profiles are social accounts that have been removed from Buffer or whose tokens have expired on the network side — they cannot receive new posts. Paused profiles are temporary pauses the user set — they can be resumed but posts won't publish while paused. For multi-profile post scheduling (posting the same content to multiple networks simultaneously), collect all selected profile IDs in an array. Buffer's create update endpoint accepts profile_ids as an array, allowing one API call to schedule a post across multiple profiles. Store the fetched profiles in React state or SWR/React Query cache with a 5-minute revalidation. Profiles rarely change during a session, so re-fetching on every render is unnecessary.

1// app/api/buffer/profiles/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { BUFFER_API_BASE, getBufferHeaders, type BufferProfile } from '@/lib/buffer/config';
4
5export async function GET(request: NextRequest) {
6  const token = request.cookies.get('buffer_token')?.value;
7
8  if (!token) {
9    return NextResponse.json({ error: 'Not authenticated with Buffer' }, { status: 401 });
10  }
11
12  try {
13    const response = await fetch(`${BUFFER_API_BASE}/profiles.json`, {
14      headers: getBufferHeaders(token),
15    });
16
17    if (response.status === 401) {
18      return NextResponse.json(
19        { error: 'Buffer token invalid or revoked — re-authorize' },
20        { status: 401 }
21      );
22    }
23
24    if (!response.ok) {
25      return NextResponse.json(
26        { error: `Buffer API error: ${response.status}` },
27        { status: response.status }
28      );
29    }
30
31    const profiles: BufferProfile[] = await response.json();
32
33    // Filter usable profiles
34    const usable = profiles
35      .filter((p) => !p.disconnected)
36      .map((p) => ({
37        id: p.id,
38        service: p.service,
39        username: p.service_username,
40        avatar: p.avatar_https,
41        formattedService: p.formatted_service,
42        paused: p.paused,
43      }));
44
45    return NextResponse.json({ profiles: usable });
46  } catch (error) {
47    const message = error instanceof Error ? error.message : 'Request failed';
48    return NextResponse.json({ error: message }, { status: 500 });
49  }
50}

Creating a post in Buffer's queue is a POST to /1/updates/create.json. This is the core functionality that makes Buffer integrations valuable — from any form in your Bolt app, you can add content to the social media scheduling queue without leaving your product. The create update request requires two fields: profile_ids (array of Buffer profile ID strings) and text (the post content). Optional fields include: media (object with link, thumbnail, picture, photo URLs for link previews and image attachments), scheduled_at (Unix timestamp for specific scheduling time — if omitted, Buffer places the post in the optimal queue slot), now (boolean, if true posts immediately), retweet (for Twitter retweets), and attachment (boolean for link attachment metadata generation). Buffer returns a response with updates array — one update object per profile_id you specified. Each update has the Buffer update ID, the profile_id it was scheduled for, status ('buffer' for queued, or 'sent' if posted immediately), and the scheduled due_at timestamp. Character limits vary by social network: Twitter/X is 280 characters, LinkedIn allows 3,000 for personal profiles and 700 for company pages, Facebook allows much longer posts. Buffer does not enforce these limits in the API — exceeding a network's limit results in the post failing to publish (Buffer will mark it as failed in the queue). Add client-side character counting to your post creation form. Media attachments for image posts require an accessible image URL. Buffer does not accept binary file uploads — the image must be hosted at a public URL. For apps where users upload images, first upload to Supabase Storage (which provides public URLs) or another CDN, then pass the public URL to Buffer's media.picture field. Link preview generation is automatic when you include a URL in the text field — Buffer detects it, fetches the open graph metadata, and creates a link preview card. Set attachment: false in the create request if you want the URL to appear as plain text without a preview card.

1// app/api/buffer/posts/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { BUFFER_API_BASE, getBufferHeaders } from '@/lib/buffer/config';
4
5interface CreatePostBody {
6  profileIds: string[];
7  text: string;
8  scheduledAt?: number; // Unix timestamp in seconds
9  mediaUrl?: string;
10  mediaThumbnailUrl?: string;
11  postNow?: boolean;
12}
13
14export async function POST(request: NextRequest) {
15  const token = request.cookies.get('buffer_token')?.value;
16
17  if (!token) {
18    return NextResponse.json({ error: 'Not authenticated with Buffer' }, { status: 401 });
19  }
20
21  const body: CreatePostBody = await request.json();
22
23  if (!body.text?.trim()) {
24    return NextResponse.json({ error: 'Post text is required' }, { status: 400 });
25  }
26  if (!body.profileIds?.length) {
27    return NextResponse.json({ error: 'At least one profile must be selected' }, { status: 400 });
28  }
29
30  try {
31    // Buffer create update uses form-encoded data
32    const formData = new URLSearchParams();
33    formData.append('text', body.text);
34    body.profileIds.forEach((id) => formData.append('profile_ids[]', id));
35
36    if (body.postNow) {
37      formData.append('now', 'true');
38    } else if (body.scheduledAt) {
39      formData.append('scheduled_at', String(body.scheduledAt));
40    }
41
42    if (body.mediaUrl) {
43      formData.append('media[picture]', body.mediaUrl);
44    }
45    if (body.mediaThumbnailUrl) {
46      formData.append('media[thumbnail]', body.mediaThumbnailUrl);
47    }
48
49    const response = await fetch(`${BUFFER_API_BASE}/updates/create.json`, {
50      method: 'POST',
51      headers: getBufferHeaders(token),
52      body: formData,
53    });
54
55    if (!response.ok) {
56      const error = await response.json().catch(() => ({ error: response.statusText }));
57      return NextResponse.json(
58        { error: error.error ?? `Buffer API error: ${response.status}` },
59        { status: response.status }
60      );
61    }
62
63    const result = await response.json();
64    const updates = result.updates ?? [];
65
66    return NextResponse.json({
67      success: true,
68      updates: updates.map((u: { id: string; profile_service: string; due_at: number; status: string }) => ({
69        id: u.id,
70        service: u.profile_service,
71        scheduledAt: u.due_at,
72        status: u.status,
73      })),
74    }, { status: 201 });
75  } catch (error) {
76    const message = error instanceof Error ? error.message : 'Failed to create post';
77    return NextResponse.json({ error: message }, { status: 500 });
78  }
79}