> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded Signup

> Connect WhatsApp Business Accounts using Meta's Embedded Signup flow

Embedded Signup allows you to quickly connect WhatsApp Business Accounts to Chirp through a streamlined OAuth-based flow powered by Meta.

## Overview

The Embedded Signup flow enables you to:

* Connect existing WhatsApp Business Accounts
* Create new WhatsApp Business Accounts
* Register phone numbers for WhatsApp messaging
* Grant Chirp permission to send and receive messages on your behalf
* Support coexistence mode (use WhatsApp Business App alongside Cloud API)

<Info>
  Embedded Signup requires Meta credentials that are configured by Chirp. Contact Chirp support to enable Embedded Signup for your organization.
</Info>

### Coexistence Mode

Coexistence mode allows businesses to use the WhatsApp Business App alongside the Cloud API. When a user completes signup through the WhatsApp Business App onboarding flow, their account is marked for coexistence, enabling:

* Continued use of the WhatsApp Business App for direct conversations
* Cloud API access for automated messaging through Chirp
* Shared phone number between both platforms

<Tip>
  Coexistence is automatically detected during signup. No additional configuration is required.
</Tip>

## How It Works

1. **Initiate Connection** - Click "Connect Account" in the Chirp dashboard
2. **Authenticate with Meta** - Log in to your Meta/Facebook account
3. **Select Business** - Choose or create a WhatsApp Business Account
4. **Grant Permissions** - Authorize Chirp to access your WhatsApp Business Account
5. **Complete Setup** - Chirp automatically syncs your phone numbers and templates

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Dashboard
    participant Meta
    participant Chirp API

    User->>Dashboard: Click "Connect Account"
    Dashboard->>Meta: Redirect to OAuth
    Meta->>User: Login & authorize
    User->>Meta: Grant permissions
    Meta->>Dashboard: Return with auth code
    Dashboard->>Chirp API: Exchange code for token
    Chirp API->>Meta: Fetch account details
    Chirp API->>Dashboard: Account connected
```

## Prerequisites

Before connecting a WhatsApp Business Account:

1. **Meta Business Account** - You need a verified Meta Business Account
2. **WhatsApp Business Account** - Either existing or created during signup
3. **Phone Number** - A phone number to register with WhatsApp (cannot already be registered with WhatsApp)
4. **Chirp Credentials** - Contact Chirp support to enable Embedded Signup

## Connecting an Account

### Step 1: Navigate to WhatsApp Accounts

In the Chirp dashboard, go to **WhatsApp > Accounts** or **Settings > WhatsApp Accounts** and click **Connect Account**.

### Step 2: Authenticate with Meta

You'll be redirected to Meta's login page. Sign in with the Facebook account that has access to your Meta Business Account.

### Step 3: Select Your Business

Choose the Meta Business Account you want to use. If you don't have one, you can create a new WhatsApp Business Account during this flow.

### Step 4: Grant Permissions

Authorize Chirp to:

* Manage your WhatsApp Business Account
* Send and receive messages
* Manage message templates
* Access phone number information

### Step 5: Complete Setup

After authorization, Chirp will:

* Create a WhatsApp Business Profile in your organization
* Sync your phone numbers
* Sync your existing message templates
* Set up webhook connections for real-time messaging

## After Connecting

Once your account is connected, you can:

<CardGroup cols={2}>
  <Card title="Send Messages" icon="paper-plane" href="/whatsapp/sending-messages/text">
    Start sending WhatsApp messages through the API
  </Card>

  <Card title="Manage Templates" icon="file-lines" href="/whatsapp/templates">
    Create and manage message templates
  </Card>

  <Card title="Configure Webhooks" icon="webhook" href="/whatsapp/webhooks-setup">
    Set up webhooks to receive incoming messages
  </Card>

  <Card title="Manage Numbers" icon="phone" href="/whatsapp/managing-numbers">
    View and configure your phone numbers
  </Card>
</CardGroup>

## For Platform Developers

If you're building a platform and want to allow your users to connect their WhatsApp Business Accounts directly within your application, Chirp provides two API-based flows:

<CardGroup cols={2}>
  <Card title="Redirect Flow" icon="arrow-right-arrow-left" href="/whatsapp/embedded-signup-redirect">
    Server-side redirect flow. Best for web applications where you control the backend.
  </Card>

  <Card title="Popup Flow" icon="window-restore" href="/whatsapp/embedded-signup-popup">
    Client-side popup flow using Meta's FB.login(). Best for seamless in-app experiences.
  </Card>
</CardGroup>

## Token Management

The connection uses a long-lived token that Chirp manages automatically:

* **Token Duration** - Tokens are valid for 60 days
* **Auto-Refresh** - Chirp refreshes tokens before expiration when possible
* **Expiration Alerts** - The dashboard shows token status and expiration warnings

<Warning>
  If a token expires, you may need to reconnect the account. Monitor the "Token Status" in your WhatsApp Accounts list.
</Warning>

## Troubleshooting

### "Business verification required"

Meta requires business verification for some WhatsApp features. Complete verification in [Meta Business Manager](https://business.facebook.com/settings/security).

### "Phone number already registered"

The phone number is already registered with WhatsApp (personal or another business account). Use a different number or migrate it through Meta's phone number migration process.

### "Permission denied"

Ensure you're signing in with an account that has admin access to the Meta Business Account.

### Token expired

If your token has expired:

1. Go to **WhatsApp > Accounts**
2. Find the account with the expired token
3. Click **Reconnect** to re-authenticate

## Getting Help

For assistance with Embedded Signup:

* **Enable Embedded Signup** - Contact [support@chirp.com](mailto:support@chirp.com) to get Meta credentials configured
* **Connection Issues** - Check Meta Business Manager for account status
* **API Questions** - See the [API Reference](/api_reference/introduction)

<Tip>
  For production deployments, ensure your Meta Business Account is verified to unlock higher messaging limits and additional features.
</Tip>