# WhatsApp Integration Setup

This guide walks you through the process of setting up WhatsApp integration using Meta’s WhatsApp Cloud API.

If you need the full Meta account and business setup flow before activation, start with [Meta WhatsApp Account Setup](https://docs.hostelmate.co/finance-management/notifications/meta-whatsapp-account-setup).

#### Prerequisites

Before setting up the WhatsApp integration, ensure you have the following:

* A **Meta Developer Account**
* A **Meta Business Account**
* A **Phone Number** registered with WhatsApp
* A **Meta App** with WhatsApp enabled

#### Step 1: Create a Meta App

1. Go to the [Meta App Dashboard](https://developers.facebook.com/apps/).
2. Click **Create App** and select **Business** as the app type.
3. Enter your **App Name** and **Contact Email**.
4. (Optional) Select a **Business Portfolio** if you have one.
5. Click **Create App** and enter your password for confirmation.
6. On the "Add Products to Your App" page, locate **WhatsApp** and click **Set Up**.
7. Select your **Meta Business Account** or create a new one.
8. Confirm your account via the email link sent by Meta.

#### Step 2: Configure WhatsApp API

1. In the Meta App Dashboard, go to **WhatsApp > Quickstart**.
2. Under **Select Business Portfolio**, choose an existing portfolio or create a new one.
3. Navigate to **WhatsApp > API Setup**.
4. Copy the **Temporary Access Token** (expires after 23 hours; we will generate a permanent token later).
5. Under **Step 1: Select Phone Numbers**, copy the **Phone Number ID**.
6. In the **To** field, add a recipient phone number for testing.
7. Click **Send Message** to test the API. You should receive a message from the configured WhatsApp number.
8. Under **App Settings > Basic**, copy the **App ID** and **App Secret**.

#### Step 3: Get a Permanent Access Token

1. In the Meta App Dashboard, go to **Business Settings**.
2. In the left menu, navigate to **Users > System Users**.
3. Click **Add** and enter a **System Username**.
4. Assign the **System User Role** (Admin or Developer).
5. Click **Create System User**.
6. Under **Assigned Assets**, click **Add Assets**.
7. Select your app, enable **Manage App**, and save changes.
8. Click **Generate Token** and choose your app.
9. Select the following permissions:
   * `whatsapp_business_messaging`
   * `whatsapp_business_management`
10. Click **Generate Token** and copy the **Permanent Access Token**.

#### Step 4: Setup Webhooks

1. In the Meta App Dashboard, navigate to **WhatsApp > Configuration**.
2. Under **Webhook**, click **Edit**.
3. Set **Callback URL** to `https://app-whpbk.hostelmate.co/webhook`.
4. Enter a **Verify Token** (a custom token you create for security).
5. Click **Verify and Save**.
6. Under **Webhook Fields**, click **Manage** and enable **messages**.

#### Step 5: Connect to Your Backend

Use the following credentials to configure WhatsApp in your system:

* **WhatsApp Token** (Permanent Access Token)
* **WhatsApp Phone** (Your registered phone number)
* **WhatsApp SID** (Your System User ID)
* **WhatsApp Number ID** (Phone Number ID from Meta)

#### Step 6: Required Message Templates

To use WhatsApp messaging effectively, there is a set number of templates that must be predefined. All templates must adhere to the following rules:

* Templates need to be in English ("en") for now—other languages aren’t supported just yet!.
* It's best to select templates as "Utility" since they're more cost-effective to use.
* Templates **must not** contain any variables, images.
* The templates should be predefined and approved for WhatsApp messaging.

**List of Required Templates:**

1. **new\_guest** - This message is sent to a guest who is booking your hostel for the first time, welcoming them and providing initial details about their stay.
2. **new\_booking** - This message is triggered whenever a guest makes a new booking, confirming their reservation details.
3. **extend\_booking** - Sent when a guest books an additional stay that directly follows an existing reservation, ensuring continuity in their lodging.
4. **canceled\_booking** - This message is sent when a guest cancels a booking, notifying them that their reservation is no longer active.
5. **arriving\_soon** - Sent one day before the guest's scheduled check-in date, reminding them of their upcoming stay.

#### Step 7: Testing & Deployment

1. Send a test message via the Meta App Dashboard.
2. Verify that your backend correctly processes and responds to WhatsApp messages.
3. Deploy the integration into production.

***

For further details, refer to the [Meta Developer Documentation](https://developers.facebook.com/docs/whatsapp/).