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

# WhatsApp Setup

> Connect Fincelo to WhatsApp Business API for CSM alerts with quick-reply buttons.

## Setup Time: 2-5 days (includes Meta template approval)

<Warning>
  WhatsApp Business API requires **pre-approved message templates** for business-initiated messages. Submit templates on Day 1 — approval takes 24-72 hours. Do not wait until everything else is set up.
</Warning>

***

## Step 1 — Meta Business Setup

1. [developers.facebook.com](https://developers.facebook.com) → Create App → **Business**
2. Add **WhatsApp** product
3. Go to WhatsApp → Getting Started
4. Note your **Phone Number ID** and **WhatsApp Business Account ID**

***

## Step 2 — Generate Permanent Access Token

1. Meta Business Manager → System Users → **Add System User**
2. Role: Admin
3. Generate New Token → select your app
4. Permissions: `whatsapp_business_messaging` + `whatsapp_business_management`
5. Copy the **permanent token**

***

## Step 3 — Register Webhook

1. WhatsApp → Configuration → **Webhook**
2. Callback URL: `https://app.fincelo.app/api/webhooks/whatsapp`
3. Verify Token: choose any string → copy it
4. Click **Verify and Save**
5. Subscribe to: ✅ messages ✅ message\_deliveries ✅ message\_reads

***

## Step 4 — Submit Message Templates

Fincelo uses 6 pre-built templates. Submit them for Meta approval:

| Template                       | Used For                                   |
| ------------------------------ | ------------------------------------------ |
| `fincelo_usage_opportunity`    | Platinum/Good customers at usage threshold |
| `fincelo_usage_heads_up`       | Average customers approaching limit        |
| `fincelo_usage_risk`           | Poor/Critical customers at risk            |
| `fincelo_collections_personal` | Overdue invoice (premium customers)        |
| `fincelo_collections_urgent`   | Overdue invoice (at-risk customers)        |
| `fincelo_escalation_notify`    | Escalation to manager/VP/CFO               |

Submit via Fincelo: **Settings → CSM Hub → WhatsApp → Submit Templates**

***

## Step 5 — Configure in Fincelo

1. Fincelo → **Settings → CSM Hub → Channel Config → WhatsApp**
2. Enter **Phone Number ID** + **API Token**
3. Save ✅

***

## Step 6 — Add CSM WhatsApp Numbers

1. **Settings → CSM Hub → CSM Roster → each CSM → WhatsApp Number**
2. Format: `+919876543210` (E.164 international format)
3. Must be a number registered with WhatsApp

***

## 24-Hour Window Policy

Meta policy: you can only send free-form messages within 24 hours of the CSM messaging you. After 24 hours, Fincelo automatically uses approved templates. This is enforced by `lib/whatsapp-session-manager.ts`.