> For the complete documentation index, see [llms.txt](https://docs.bloodgpt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloodgpt.com/integration-guides/whatsapp-setup.md).

# WhatsApp Setup

How to set up WhatsApp as a notification channel for your patient portal.

Deliver lab result notifications and magic link sign-ins to your patients via WhatsApp. This guide walks you through creating the required message templates in the Meta for Developers portal and connecting them to your BloodGPT patient portal.

{% hint style="info" %}
**Prerequisite:** You must have a working patient portal before enabling WhatsApp. See [Portal Setup Guide](/integration-guides/portal-setup.md) if you haven't set one up yet.
{% endhint %}

## Prerequisites

| Requirement               | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| **Active Patient Portal** | Portal configured with your branding and domain                   |
| **Custom Portal Domain**  | Your white-label portal URL, e.g. `https://portal.yourlab.com`    |
| **Meta Business Account** | A verified [Meta Business account](https://business.facebook.com) |
| **WhatsApp Business API** | Access to WhatsApp Business Platform via Meta for Developers      |
| **Verified Phone Number** | A phone number registered and verified for WhatsApp Business      |
| **Patient Phone Numbers** | Patients registered with phone numbers in E.164 format            |

{% hint style="warning" %}
**About the portal URL:** Throughout this guide, `yourlab.com` represents your own domain and `portal` is the subdomain where your patient portal is hosted. Replace both with your actual values — for example, `https://results.acmediagnostics.com`.
{% endhint %}

## Step 1: Create a Meta App

1. Go to [developers.facebook.com](https://developers.facebook.com) and log in
2. Click **My Apps** → **Create App**
3. Select **Business** as the app type
4. Enter your app name and contact email, select your Meta Business Account
5. On the app dashboard, find **WhatsApp** and click **Set Up**
6. Follow the prompts to add a phone number and verify it

{% hint style="info" %}
If you already have a Meta app with WhatsApp configured, skip to Step 2.
{% endhint %}

## Step 2: Create Message Templates

You need to create two message templates in the Meta for Developers portal. Go to your [WhatsApp Manager](https://business.facebook.com/wa/manage/message-templates/) and click **Create Template** for each one.

### Template 1: `lab_report_ready`

This template notifies patients when their lab results are ready.

#### Configuration

| Setting           | Value                                |
| ----------------- | ------------------------------------ |
| **Template Name** | `lab_report_ready`                   |
| **Category**      | Utility                              |
| **Language**      | English (or your preferred language) |

#### Body

```
Hello! Your lab test result from  {{date}} are ready.

Click the button to see it.
```

`{{date}}` is a variable that will be replaced with the test date at send time (e.g. "January 15, 2025").

#### Button

| Setting         | Value                              |
| --------------- | ---------------------------------- |
| **Type**        | Call to Action                     |
| **Action**      | Visit Website                      |
| **Button Text** | View Results                       |
| **URL Type**    | Dynamic                            |
| **URL**         | `https://portal.yourlab.com/{{1}}` |

#### Preview

> **Your Lab Name**
>
> Hello! Your lab test result from January 15, 2025 are ready.
>
> Click the button to see it.
>
> `[View Results]`

***

### Template 2: `auth_magic_link`

This template sends a magic link when a patient requests to sign in to the portal.

#### Configuration

| Setting           | Value                                |
| ----------------- | ------------------------------------ |
| **Template Name** | `auth_magic_link`                    |
| **Category**      | Utility                              |
| **Language**      | English (or your preferred language) |

#### Body

```
You requested authorization to your patient portal.
```

#### Button

| Setting         | Value                              |
| --------------- | ---------------------------------- |
| **Type**        | Call to Action                     |
| **Action**      | Visit Website                      |
| **Button Text** | Sign In                            |
| **URL Type**    | Dynamic                            |
| **URL**         | `https://portal.yourlab.com/{{1}}` |

#### Preview

> **Your Lab Name**
>
> You requested authorization to your patient portal.
>
> `[Sign In]`

***

### How Dynamic URL Buttons Work

In WhatsApp message templates, a **dynamic URL** has a fixed base and a variable suffix that changes per message. You define the base URL in the template, and BloodGPT appends the unique path when sending.

| Part                                  | Example                                       |
| ------------------------------------- | --------------------------------------------- |
| **Base URL** (set in template)        | `https://portal.yourlab.com/`                 |
| **Dynamic suffix** (set at send time) | `results/a1b2c3d4` or `auth/token-xyz`        |
| **Final URL patient sees**            | `https://portal.yourlab.com/results/a1b2c3d4` |

This is how each patient gets a unique, secure link while the template stays approved — the base URL is fixed and reviewed by Meta, but the path varies per message.

### Template Approval

After creating each template, submit it for Meta review. Approval typically takes a few minutes to 24 hours.

{% hint style="info" %}
**Tips for faster approval:**

* Use clear, non-promotional language
* Choose the correct category (Utility, not Marketing)
* Include a sample value for each variable
* Ensure your Meta Business account is verified
  {% endhint %}

| Status       | Meaning                                              |
| ------------ | ---------------------------------------------------- |
| **Approved** | Template is ready to use                             |
| **Rejected** | Review rejection reason in WhatsApp Manager and edit |
| **Pending**  | Under review — usually completes within 24 hours     |

## Step 3: Configure WhatsApp in BloodGPT

Once your templates are approved, provide the following credentials to BloodGPT so we can send messages on your behalf.

| Credential                       | Where to Find It                                               |
| -------------------------------- | -------------------------------------------------------------- |
| **WhatsApp Business Account ID** | WhatsApp Manager → Account settings                            |
| **Phone Number ID**              | WhatsApp Manager → Phone numbers                               |
| **Permanent Access Token**       | Meta for Developers → Your App → API Setup                     |
| **Template names**               | `lab_report_ready` and `auth_magic_link`                       |
| **Portal base URL**              | Your white-label portal URL, e.g. `https://portal.yourlab.com` |

Send these to <contact@bloodgpt.com> or configure them in your dashboard under **Settings → WhatsApp**.

{% hint style="warning" %}
**Security:** Never share your access token in unsecured channels. Use encrypted email or your BloodGPT dashboard to submit credentials.
{% endhint %}

## Step 4: Test the Flow

Before going live, verify the complete WhatsApp flow using your own phone number.

### 1. Register a Test Patient

Register yourself as a test patient with your WhatsApp phone number:

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/patients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "patient_id": "TEST-WA-001",
    "phone": "+1234567890"
  }'
```

### 2. Submit a Test Result

```bash
curl -X POST https://sandbox.bloodgpt.com/api/v1/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "TEST-WA-001",
    "external_id": "TEST-RESULT-WA-001",
    "patient_info": {"birth_date": "1985-01-01", "gender": "male"},
    "payload": {
      "parameters": [
        {"name": "Glucose", "value": 95, "unit": "mg/dL", "range": "70-100"}
      ]
    }
  }'
```

### 3. Verify

* [ ] WhatsApp message arrives on your phone
* [ ] Message text matches `lab_report_ready` template
* [ ] "View Results" button opens your portal with results
* [ ] Request a magic link and verify `auth_magic_link` message arrives
* [ ] "Sign In" button opens the portal and authenticates you

## Troubleshooting

### Not Receiving Messages

1. Verify your phone number is in E.164 format (e.g. `+1234567890`)
2. Check that both templates have **Approved** status in WhatsApp Manager
3. Ensure the patient is registered with a `phone` field
4. Check WhatsApp Manager → Insights for delivery errors

### Template Rejected

Common rejection reasons:

| Reason                | Fix                                             |
| --------------------- | ----------------------------------------------- |
| Promotional content   | Use Utility category, remove marketing language |
| Missing sample values | Add example values for all `{{variables}}`      |
| Unclear purpose       | Make the message purpose explicit               |
| URL mismatch          | Ensure base URL matches your verified domain    |

Resubmit after editing — Meta allows unlimited resubmissions.

### Button URL Not Working

1. Verify the base URL in your template matches your portal domain exactly
2. Check that HTTPS is used (HTTP is not supported)
3. Ensure your portal domain DNS is configured and accessible

## Security

| Feature                    | Description                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No results in messages** | The message body carries no laboratory values, no report content and no attachment — only your organization name, the patient's name, the test date and a link |
| **Time-limited links**     | Magic links expire 15 minutes after they are issued                                                                                                            |
| **HTTPS only**             | All portal URLs use encrypted connections                                                                                                                      |
| **Secure token delivery**  | Each link contains a unique, single-use token; the token is stored only as a hash on our side                                                                  |

{% hint style="warning" %}
**The message is still a disclosure.** Withholding the results does not make the notification neutral: a named laboratory writing to a named person about a test reveals the care relationship, and the message travels over Meta's global WhatsApp infrastructure. We have not identified BAA coverage for the WhatsApp Cloud API, so where HIPAA applies this channel is not a covered path — use email and the portal instead, and keep clinical detail out of template parameters and link components. Talk to us before enabling WhatsApp for a HIPAA-covered workload.
{% endhint %}

{% hint style="success" %}
**Need help?** Contact <contact@bloodgpt.com> for assistance with WhatsApp setup.
{% endhint %}