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

# Sign-Up Units & BSUIDs

> How the WhatsApp BSUID rollout affects sign-up unit flows that rely on phone number matching, and how to adapt them 📲

<Info>
  **Audience:** Account Management, Customer Success, Solutions Engineering — for customers using sign-up units with coupon or welcome message flows.
</Info>

## The problem

Many businesses use a **Sign-Up unit** flow that works like this today:

<Steps>
  <Step title="Phone number collected">
    The website Sign-Up unit collects the user's phone number.
  </Step>

  <Step title="User redirected to WhatsApp">
    The user is redirected to WhatsApp via a `wa.me` link and sends an inbound message to the business.
  </Step>

  <Step title="Bot matches and replies">
    The bot or autoreply matches the inbound phone number against the number collected on the website and sends back the coupon code.
  </Step>
</Steps>

**This breaks with the BSUID rollout.**

Per Meta's BSUID documentation, the phone number is only included in the inbound webhook if the business has interacted with that specific phone number within the **last 30 days** (evaluated per business phone number). For new users — which is exactly who a Sign-Up unit targets — the inbound message will arrive with a BSUID and **no phone number**. The matching in step 3 stops working.

***

## Recommended fix: send the coupon as an API campaign

The business already has the phone number — it was collected on the website in step 1. Instead of waiting for an inbound message and trying to match it, the business's backend sends the coupon directly to that phone number as a business-initiated campaign via Connectly's Campaign Send API.

**New flow:**

<Steps>
  <Step title="Phone number collected">
    Website Sign-Up unit collects the phone number — unchanged.
  </Step>

  <Step title="Backend sends the coupon directly">
    The business's backend calls `POST /v1/businesses/{businessId}/send/campaigns` with that phone number, triggering a pre-approved WhatsApp template that delivers the coupon code.
  </Step>

  <Step title="wa.me redirect (optional)">
    The `wa.me` redirect can stay if desired — but the coupon no longer depends on the inbound message arriving.
  </Step>
</Steps>

<Tip>
  A side benefit: the outbound send counts as a business interaction with that phone number. Per Meta's 30-day rule, subsequent inbound messages from that user will include the phone number again — so any downstream phone-based logic continues to work.
</Tip>

***

## One-time setup

Before the first send, the customer needs:

1. A campaign created in Connectly with an approved WhatsApp template containing the coupon message. Note its `campaignId`.
2. The campaign must be **published** — the API rejects draft campaigns.
3. A Connectly API key with `messaging.send` scope (passed as the `X-API-Key` header).

***

## Example API request

```bash theme={null}
curl -X POST 'https://api.connectly.ai/v1/businesses/{businessId}/send/campaigns' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <API_KEY>' \
  -d '{
    "entries": [
      {
        "client": "+16505551234",
        "campaignId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "variables": {
          "coupon_code": "WELCOME10"
        }
      }
    ]
  }'
```

**Key fields:**

| Field        | Required | Description                                                                                                                                         |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client`     | Yes      | Recipient's phone number in E.164 format — the one collected on the website.                                                                        |
| `campaignId` | Yes      | UUID of the pre-created coupon campaign. `campaignName` also works but is deprecated — don't mix both in the same request.                          |
| `variables`  | No       | Values for the template's variables (e.g. the coupon code). Only needed if the template uses variables.                                             |
| `sender`     | No       | Which business phone number to send from. If omitted, the business's default channel is used. Set explicitly if the business runs multiple numbers. |

<Note>
  By default, the API prevents sending the same campaign to the same phone number twice (`if_duplicate_check_unspecified: allow_one`). This is usually the right behaviour for a sign-up coupon — a customer should only receive it once.
</Note>

**Example response:**

```json theme={null}
{
  "data": [
    {
      "campaignId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "campaignName": "signup_coupon",
      "campaignVersion": "v1.0",
      "sendoutId": "0d300213-1889-448d-b1e5-7503fe4be68f",
      "status": "created",
      "acceptedCount": 1,
      "rejectedCount": 0,
      "error": null
    }
  ]
}
```

***

## Important: pricing impact

<Warning>
  Today's flow replies inside the **24-hour customer-service window**, so the coupon goes out as a free-form service message with no Meta messaging fee.

  The recommended flow sends a **business-initiated template message**, which Meta bills per delivered message according to its rate card (rate depends on template category and destination country).

  Confirm with the customer that they accept this cost before building the integration.
</Warning>

***

## Alternative: request phone number sharing inside WhatsApp

If the cost increase is not acceptable, there is a cheaper option for phone-less users specifically. Meta added a native `REQUEST_CONTACT_INFO` message type that lets businesses ask the user to confirm sharing their phone number inside WhatsApp. The user taps one button, the shared phone number arrives on the webhook, and the existing phone-matching logic works again — all inside the free service window.

<Note>
  Sending this message type from the Connectly Flow Builder is **not yet available**. A dedicated node is planned. Until it ships, this option cannot be self-served through the platform. Contact your Connectly Account Manager for the latest status.
</Note>