Embedded Signup: Redirect Flow

The redirect flow allows platform developers to embed WhatsApp account connection in their applications using server-side redirects. This is ideal for web applications where you control the backend.

This guide is for platform developers building applications on top of Chirp. If you just want to connect your own WhatsApp Business Account, use the dashboard method.

When to Use This Flow

Choose the redirect flow when:

You have a server-side application that can handle redirects
You want a simple, well-understood OAuth-like pattern
You need to support mobile apps with custom URL schemes
You prefer server-side token exchange over client-side JavaScript

For a client-side popup experience, see the Popup Flow.

How It Works

Create Session - Your server calls the Chirp API to create an embedded signup session
Redirect User - Redirect your user to the session URL
User Completes Signup - User authenticates with Meta and grants permissions
Callback - User is redirected back to your redirect_uri with the result

Creating a Session

Use your Admin Key to create an embedded signup session:

curl -X POST https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://yourapp.com/whatsapp/callback",
    "state": "your-csrf-token-123"
  }'

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const session = await chirp.admin.embeddedSignup.createSession({
  redirect_uri: "https://yourapp.com/whatsapp/callback",
  state: "your-csrf-token-123"
});

// session.id, session.url, session.expiresAt

Response:

Session Response

{
  "id": "wss_abc123...",
  "url": "https://dashboard.chirp.com/embed/connect?token=...",
  "expires_at": "2024-01-15T12:15:00.000Z"
}

Parameters

Parameter	Required	Description
`redirect_uri`	Yes	URL to redirect after completion. Supports HTTPS URLs and mobile app schemas (e.g., `myapp://callback`)
`state`	Yes	CSRF token (max 512 chars). Returned unchanged in the callback
`metadata`	No	JSON object (max 10KB) for storing your internal identifiers (e.g., `externalUserId`, `businessName`)
`prefill`	No	Pre-fill configuration to auto-populate the Meta signup form. See Pre-fill Configuration below

Pre-fill Configuration

You can pre-populate the Meta Embedded Signup form with business information to improve conversion rates. This is especially useful when you already have your user’s business details.

curl -X POST https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://yourapp.com/whatsapp/callback",
    "state": "your-csrf-token-123",
    "prefill": {
      "business": {
        "name": "Acme Corporation",
        "email": "contact@acme.com",
        "website": "https://acme.com",
        "phone": {
          "code": 1,
          "number": "5551234567"
        },
        "address": {
          "streetAddress1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "zipPostal": "94105",
          "country": "US"
        },
        "timezone": "America/Los_Angeles"
      },
      "phone": {
        "displayName": "Acme Support",
        "category": "ENTERTAIN",
        "description": "Customer support for Acme products"
      }
    }
  }'

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const session = await chirp.admin.embeddedSignup.createSession({
  redirect_uri: "https://yourapp.com/whatsapp/callback",
  state: "your-csrf-token-123",
  prefill: {
    business: {
      name: "Acme Corporation",
      email: "contact@acme.com",
      website: "https://acme.com",
      phone: {
        code: 1,
        number: "5551234567"
      },
      address: {
        streetAddress1: "123 Main St",
        city: "San Francisco",
        state: "CA",
        zipPostal: "94105",
        country: "US"
      },
      timezone: "America/Los_Angeles"
    },
    phone: {
      displayName: "Acme Support",
      category: "ENTERTAIN",
      description: "Customer support for Acme products"
    }
  }
});

Pre-fill Fields

Field	Description
`business.name`	Business name (max 255 chars)
`business.email`	Business email address
`business.website`	Business website URL
`business.phone.code`	Country calling code (e.g., `1` for US)
`business.phone.number`	Phone number without country code
`business.address`	Business address with `streetAddress1`, `streetAddress2`, `city`, `state`, `zipPostal`, `country`
`business.timezone`	IANA timezone (e.g., `"America/Los_Angeles"`)
`phone.displayName`	WhatsApp Business display name (max 512 chars)
`phone.category`	Business category
`phone.description`	Business description (max 512 chars)

The country field uses ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE"). The pre-fill data is limited to 10KB total.

Handling the Callback

After the user completes (or cancels) the signup, they’re redirected to your redirect_uri with query parameters: Success:

https://yourapp.com/whatsapp/callback?status=success&state=your-csrf-token-123

Error:

https://yourapp.com/whatsapp/callback?status=error&state=your-csrf-token-123&error=waba_already_connected

Error Codes

Error Code	Description
`session_expired`	The session URL expired (15 minute TTL)
`waba_already_connected`	The WhatsApp Business Account is already connected to this organization
`meta_api_error`	Error from Meta’s API during token exchange
`code_expired`	The authorization code from Meta expired (30 second TTL)
`signup_failed`	General signup failure

Completing an Interrupted Session

If a user completes the Meta signup but the redirect fails (network error, browser closed, etc.), you can complete the session manually using the WABA ID:

curl -X POST https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions/{sessionId}/complete \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wabaId": "123456789"
  }'

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const result = await chirp.admin.embeddedSignup.completeSession(
  "wss_abc123...",
  { wabaId: "123456789" }
);

This is useful when you receive a PARTNER_APP_INSTALLED webhook indicating the user completed signup on Meta’s side but didn’t return to your application.

Security Considerations

Always validate the state parameter in your callback to prevent CSRF attacks. Compare it to the value you originally sent when creating the session.

Session Expiration - Sessions expire after 15 minutes
One-Time Use - Each session can only be completed once
HTTPS Required - Use HTTPS for your redirect_uri in production
State Validation - Always verify the state parameter matches what you sent

Mobile App Integration

For mobile apps, use a custom URL scheme as your redirect_uri:

curl -X POST https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "myapp://whatsapp/callback",
    "state": "mobile-csrf-token"
  }'

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const session = await chirp.admin.embeddedSignup.createSession({
  redirect_uri: "myapp://whatsapp/callback",
  state: "mobile-csrf-token"
});

// Open session.url in a webview or browser

Then handle the callback in your app’s URL handler.

Managing Sessions

List Sessions

curl -X GET https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const sessions = await chirp.admin.embeddedSignup.listSessions();

// With filters
const pendingSessions = await chirp.admin.embeddedSignup.listSessions({
  status: "pending",
  limit: 50
});

Get Session Status

curl -X GET https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions/{sessionId} \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

const session = await chirp.admin.embeddedSignup.getSession("wss_abc123...");

Delete Session

curl -X DELETE https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions/{sessionId} \
  -H "Authorization: Bearer YOUR_ADMIN_KEY"

import ChirpSDK from "@buildwithchirp/sdk";

const chirp = new ChirpSDK({ apiKey: "YOUR_ADMIN_KEY" });

await chirp.admin.embeddedSignup.cancelSession("wss_abc123...");

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Embedded Signup: Redirect Flow

When to Use This Flow

How It Works

Creating a Session

Parameters

Pre-fill Configuration

Pre-fill Fields

Handling the Callback

Error Codes

Completing an Interrupted Session

Security Considerations

Mobile App Integration

Managing Sessions

List Sessions

Get Session Status

Delete Session

Next Steps

API Reference

Popup Flow

​When to Use This Flow

​How It Works

​Creating a Session

​Parameters

​Pre-fill Configuration

​Pre-fill Fields

​Handling the Callback

​Error Codes

​Completing an Interrupted Session

​Security Considerations

​Mobile App Integration

​Managing Sessions

​List Sessions

​Get Session Status

​Delete Session

​Next Steps

API Reference

Popup Flow

When to Use This Flow

How It Works

Creating a Session

Parameters

Pre-fill Configuration

Pre-fill Fields

Handling the Callback

Error Codes

Completing an Interrupted Session

Security Considerations

Mobile App Integration

Managing Sessions

List Sessions

Get Session Status

Delete Session

Next Steps