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

# WhatsApp Integration

> How Referbro sends automated referral messages via WhatsApp

Referbro connects to the **WhatsApp Business API** to send automated referral messages at key moments in the customer journey. This page covers how templates work and how to configure them.

For the in-app setup flow, follow [How to Configure WhatsApp Templates in Referbro](https://scribehow.com/viewer/How_to_Configure_WhatsApp_Templates_in_Referbro__UZFYf1rdTy6GsTengQCjag).

## How It Works

1. You create a **Message Template** on your WhatsApp provider's platform (e.g., Pragma, Meta).
2. Meta **approves** the template (required for all business-initiated messages).
3. You **map** the approved template in Referbro by entering its ID and parameters.
4. Referbro **sends messages** using your template whenever a trigger fires (e.g., customer shares, order placed).

***

## Template Types

Referbro supports **8 different template slots**, each triggered at a different point in the customer journey. You can find ready-to-use examples for all of these in our [Template Library](/docs/features/whatsapp/template-library):

| Template Type                      | Trigger                                       | Purpose                                                  |
| :--------------------------------- | :-------------------------------------------- | :------------------------------------------------------- |
| **Referral Invitation**            | Customer clicks "Share on WhatsApp" in widget | First-person referral invite                             |
| **Order Confirmation**             | After a customer places an order              | Encourage sharing while the customer is happy            |
| **Delivery Notification**          | Order is marked as delivered                  | Prompt sharing after the customer receives their order   |
| **Post Delivery Followup**         | Configured time after delivery                | Follow-up message to encourage repeat sharing            |
| **Post-Referral Follow-up**        | After a successful referral is made           | Confirm the referral and encourage more sharing          |
| **Referrer Delivery Notification** | Referred friend's order is delivered          | Notify the referrer that their friend received the order |
| **Reward Notification**            | Referrer earns a reward                       | Notify the referrer of their earned reward               |
| **Nudge Reminder**                 | Scheduled reminder                            | Re-engage customers who haven't shared yet               |

<Tip>
  You don't need to configure all 8 templates to get started. Begin with **Referral Invitation** and **Order Confirmation** — these are the highest-impact touchpoints.
</Tip>

***

## Template Parameters

When mapping a template in Referbro, you provide a JSON object with parameter keys and values.

### Parameter Key Format

| Key Pattern                                  | Meaning                                             | Example                                  |
| :------------------------------------------- | :-------------------------------------------------- | :--------------------------------------- |
| `body.<index>`                               | Body text parameter at position `<index>` (1-based) | `"body.1": "Get ₹150 OFF!"`              |
| `body.<index>.<name>`                        | Named body parameter (alias for readability)        | `"body.1.message": "Hey! Share this..."` |
| `button.url.<btnIndex>.<paramIndex>`         | URL button parameter                                | `"button.url.0.1": "{{REFERRAL_CODE}}"`  |
| `button.quick_reply.<btnIndex>.<paramIndex>` | Quick reply button parameter                        | `"button.quick_reply.0.1": "Share Now"`  |
| `languageCode`                               | Template language code                              | `"languageCode": "en"`                   |

<Note>
  **For Pragma users:** Button parameters use the format `button.url.<index>.value` instead of `button.url.<index>.<paramIndex>`. See the [Pragma section](/docs/features/whatsapp/providers#pragma) for details.
</Note>

### Available Placeholders

Use these placeholders in your parameter values. Referbro only resolves variables that are available in the current trigger context.

| Placeholder          | Replaced With                                     | Example Output                                                              | Available In                                                                                                            | When It Is Available                                                                                                                |
| :------------------- | :------------------------------------------------ | :-------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `{{REFERRAL_CODE}}`  | The customer's unique referral code               | `JOHN-AB12`                                                                 | All template slots                                                                                                      | Always available in automated sends (and test sends, where fallback is `TEST123`)                                                   |
| `{{REFERRAL_LINK}}`  | Full referral link URL                            | `https://yourstore.com?ref=JOHN-AB12`                                       | Order Confirmation, Delivery, Referrer Delivery, Post-Referral, Post-Delivery Follow-up, Nudge, Share-link message flow | Auto-injected in automated WhatsApp sends for these touchpoints, and also resolved in the widget share URL flow (`/whatsapp/share`) |
| `{{FRIEND_REWARD}}`  | Friend offer text                                 | `₹150 OFF`                                                                  | Order Confirmation, Delivery, Referrer Delivery, Post-Referral, Post-Delivery Follow-up, Nudge, Share-link message flow | Auto-injected in automated WhatsApp sends for these touchpoints, and also resolved in the widget share URL flow (`/whatsapp/share`) |
| `{{FIRST_NAME}}`     | Customer's first name                             | `John`                                                                      | Order Confirmation, Delivery, Referrer Delivery, Post-Referral, Post-Delivery Follow-up, Nudge, Reward Notification     | Auto-injected in all automated template sends; falls back to `there` when the customer's name is unavailable                        |
| `{{REFERRER_NAME}}`  | Referrer's name                                   | `John`                                                                      | Reward Notification                                                                                                     | Available for all reward notifications                                                                                              |
| `{{GIFT_CODE}}`      | Gift card code                                    | `GIFT-123`                                                                  | Reward Notification                                                                                                     | Available only when reward type is Gift Card                                                                                        |
| `{{PRODUCT_NAME}}`   | Gift product title                                | `Free Coffee Mug`                                                           | Reward Notification                                                                                                     | Available only when reward type is Gift Card                                                                                        |
| `{{GIFT_URL}}`       | Auto-apply gift cart URL                          | `https://yourstore.com/cart/{variant_id}:1?discount={code}&storefront=true` | Reward Notification                                                                                                     | Available only when reward type is Gift Card                                                                                        |
| `{{DISCOUNT_CODE}}`  | Discount code reward                              | `SAVE-123`                                                                  | Reward Notification                                                                                                     | Available only when reward type is Flat Amount or Percentage Discount Code                                                          |
| `{{DISCOUNT_VALUE}}` | Discount text                                     | `₹150 off` / `15% off`                                                      | Reward Notification                                                                                                     | Available only when reward type is Flat Amount or Percentage Discount Code                                                          |
| `{{DISCOUNT_URL}}`   | Auto-apply discount URL                           | `https://yourstore.com/discount/SAVE-123`                                   | Reward Notification                                                                                                     | Available only when reward type is Flat Amount or Percentage Discount Code                                                          |
| `{{CREDIT_AMOUNT}}`  | Referrer reward text / issued store credit amount | `₹150` / `150.00`                                                           | Order Confirmation, Delivery, Referrer Delivery, Post-Referral, Post-Delivery Follow-up, Nudge, Reward Notification     | Auto-injected in referral campaign automation sends; in Reward Notification it is available only when reward type is Store Credit   |
| `{{CURRENCY_CODE}}`  | Store credit currency code                        | `USD`                                                                       | Reward Notification                                                                                                     | Available only when reward type is Store Credit                                                                                     |
| `{{BALANCE_AFTER}}`  | Store credit balance after credit                 | `225.00`                                                                    | Reward Notification                                                                                                     | Available only when reward type is Store Credit                                                                                     |

<Note>
  If a placeholder is not available for a trigger, it is sent as-is (not replaced). In **Send Test Message**, you can still provide manual values for any placeholder from the modal.
</Note>

### Full Example

```json theme={null}
{
  "body.1": "Share your unique link, and your friends get {{FRIEND_REWARD}} OFF, while you earn ₹150 when they buy! 👇",
  "body.2": "{{REFERRAL_LINK}}&source=order",
  "languageCode": "en",
  "button.url.0.1": "{{REFERRAL_CODE}}&source=order_cta"
}
```

***

## Share Button URL

Referbro provides a **Share Button URL** endpoint that you can use as a URL button in your WhatsApp templates. When a customer taps this button, it opens WhatsApp with a pre-filled share message — making it easy for them to refer friends with a single tap.

### URL Syntax

```
https://server.referbro.com/whatsapp/share?referralCode={referralCode}&source={source}
```

| Query Parameter | Required | Description                                                                                             | Example                                |
| :-------------- | :------- | :------------------------------------------------------------------------------------------------------ | :------------------------------------- |
| `referralCode`  | ✅ Yes    | The customer's unique referral code (UUID format)                                                       | `937ef225-18a2-4f10-a9cc-5d43ecdcd4f1` |
| `source`        | ❌ No     | Identifies where the share originated (for analytics tracking). Defaults to `whatsapp_share` if omitted | `widget_cta`, `order_cta`, `nudge_cta` |

**Example URL:**

```
https://server.referbro.com/whatsapp/share?referralCode=937ef225-18a2-4f10-a9cc-5d43ecdcd4f1&source=widget_cta
```

### How It Works

When a customer taps a button configured with this URL:

1. Referbro looks up the referral code to find the associated **campaign**.
2. The campaign's **Share Message** (configured on the [Campaign page](/docs/features/campaigns#widget-configuration)) is retrieved.
3. Placeholders `{{REFERRAL_LINK}}` and `{{FRIEND_REWARD}}` in the Share Message are replaced with the customer's actual referral link and the friend's discount text.
4. The customer is **redirected** to `https://api.whatsapp.com/send?text=...` with the fully resolved message — opening WhatsApp with the share message pre-filled and ready to send.

<Important>
  The Share Message text is configured in **Campaign Configuration → Widget Configuration → Share Message**. If no Share Message is set, the share URL will return an error. See the [Campaign Management](/docs/features/campaigns#widget-configuration) page for details on configuring this field.
</Important>

### Using It in Template Buttons

To add a share button to your WhatsApp template, configure the `buttons` section in your Referbro template mapping. The button URL on your WhatsApp provider should use the Referbro share endpoint as the base URL, with the referral code appended as a dynamic parameter.

**Step 1:** When creating the template on your provider's platform (e.g., Meta, Pragma), add a **URL button** with a base URL like:

```
https://server.referbro.com/whatsapp/share?referralCode={{1}}
```

Where `{{1}}` is the dynamic parameter placeholder that Referbro will fill in.

**Step 2:** In Referbro's template parameter mapping, map the button parameter to include the referral code and source:

```json theme={null}
{
  "body.1": "Share your unique link, and your friends get {{FRIEND_REWARD}} OFF! 👇",
  "languageCode": "en",
  "button.url.0.1": "{{REFERRAL_CODE}}&source=widget_cta"
}
```

The `button.url.0.1` value is appended to the base URL you set on the provider, resulting in a final URL like:

```
https://server.referbro.com/whatsapp/share?referralCode=JOHN-AB12&source=widget_cta
```

<Note>
  **For Pragma users:** Use `button.url.0.value` instead of `button.url.0.1`. See the [Pragma section](/docs/features/whatsapp/providers#pragma) for the correct format.
</Note>

### Button Key Format Reference

| Key Pattern                                  | Provider                            | Example                                                      |
| :------------------------------------------- | :---------------------------------- | :----------------------------------------------------------- |
| `button.url.<btnIndex>.<paramIndex>`         | Meta, Bitespeed, and most providers | `"button.url.0.1": "{{REFERRAL_CODE}}&source=order_cta"`     |
| `button.url.<index>.value`                   | Pragma                              | `"button.url.0.value": "{{REFERRAL_CODE}}&source=order_cta"` |
| `button.quick_reply.<btnIndex>.<paramIndex>` | Quick reply buttons (all providers) | `"button.quick_reply.0.1": "Share Now"`                      |

### Full Example with Share Button

```json theme={null}
{
  "body.1": "Love your purchase? Share with friends — they get {{FRIEND_REWARD}} OFF, and you earn ₹150! 👇",
  "body.2": "{{REFERRAL_LINK}}&source=order",
  "languageCode": "en",
  "button.url.0.1": "{{REFERRAL_CODE}}&source=order_cta"
}
```

In this example:

* `body.2` contains the referral link as a clickable text link in the message body
* `button.url.0.1` powers a **"Share Now"** URL button that redirects to the Referbro share endpoint → opens WhatsApp with the campaign's Share Message pre-filled

<Tip>
  Use different `source` values for body links vs. button taps (e.g., `source=order` vs. `source=order_cta`) to distinguish them in [Analytics](/docs/features/analytics).
</Tip>

***

## Testing Templates

Before going live, test your template configuration:

1. Go to **Apps → Referbro → WhatsApp Settings**.
2. Scroll to the template you configured.
3. Click **Send Test Message** and enter your phone number.
4. Verify you receive the message with correct content and working links.

<Warning>
  Test messages use the placeholder code `TEST123`. Make sure your template doesn't have strict validation that would reject test codes.
</Warning>