Skip to main content
POST
/
v1
/
organization
/
embedded-signup
/
sessions
cURL
curl --request POST \
  --url https://api.buildwithchirp.com/v1/organization/embedded-signup/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "redirect_uri": "https://example.com/whatsapp/callback",
  "state": "abc123-csrf-token",
  "metadata": {
    "externalUserId": "user_123",
    "businessName": "Acme Corp"
  },
  "prefill": {
    "business": {
      "name": "Acme Corp",
      "email": "contact@acme.com",
      "website": "https://acme.com",
      "address": {
        "streetAddress1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "zipPostal": "94102",
        "country": "US"
      },
      "phone": {
        "code": 1,
        "number": "4155551234"
      },
      "timezone": "America/Los_Angeles"
    },
    "phone": {
      "displayName": "Acme Support",
      "category": "Automotive",
      "description": "Official Acme Corp WhatsApp support channel"
    }
  }
}
'
{
  "id": "wss_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "url": "https://dashboard.chirp.com/embed/connect?token=abc123...",
  "expires_at": "2024-01-15T12:30:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Admin API key (format: sk_admin_*) for organization-level operations

Body

application/json
​
redirect_uri
string

The URL to redirect the user to after completing or failing the signup. Required for redirect flow, optional for popup flow.

Minimum string length: 1
Example:

"https://example.com/whatsapp/callback"

​
state
string

A CSRF protection token that will be returned unchanged in the redirect. Required for redirect flow.

Required string length: 1 - 512
Example:

"abc123-csrf-token"

​
metadata
object

Developer-provided metadata for filtering sessions by internal user IDs. Useful for platforms with multiple end-users. Maximum size: 10KB.

Example:
{
  "externalUserId": "user_123",
  "businessName": "Acme Corp"
}
​
prefill
object

Pre-fill configuration for Facebook Embedded Signup. Auto-populates business information in the signup form. This can improve conversion by reducing manual data entry.

Example:
{
  "business": {
    "name": "Acme Corp",
    "email": "contact@acme.com",
    "website": "https://acme.com",
    "address": {
      "streetAddress1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zipPostal": "94102",
      "country": "US"
    },
    "phone": { "code": 1, "number": "4155551234" },
    "timezone": "America/Los_Angeles"
  },
  "phone": {
    "displayName": "Acme Support",
    "category": "Automotive",
    "description": "Official Acme Corp WhatsApp support channel"
  }
}

Response

Session created successfully

​
id
string
required

WhatsApp Signup Session ID

Example:

"wss_2DbBs7GWhGvVNJGrDXr5RG0mBWI"

​
url
string<uri>
required

The URL to redirect the user to for completing the WhatsApp Business signup

Example:

"https://dashboard.chirp.com/embed/connect?token=abc123..."

​
expires_at
string<date-time>
required

When this session URL expires (15 minutes from creation)

Example:

"2024-01-15T12:30:00.000Z"