> For the complete documentation index, see [llms.txt](https://docs.dorg.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dorg.pro/install-dorg/optional-configurations/messaging-via-whatsapp.md). # Messaging via Whatsapp This chapter explains how to enable **WhatsApp** access to **Dorg** through the **Meta WhatsApp Cloud API**. This WhatsApp messaging channel is supported starting from **Dorg v3.4**. WhatsApp configuration is managed from the Dorg Console and is intended for the customer administrator, IT team, or deployment operator responsible for Meta Business configuration. The goal of this procedure is to collect the required values from Meta and enter them in the **WhatsApp** configuration section of the Dorg Console. *** ### What WhatsApp Enables When WhatsApp is configured, users can interact with Dorg through a WhatsApp Business phone number. The WhatsApp Cloud API receives inbound WhatsApp messages, forwards them to the Dorg webhook, and allows Dorg to reply through the same WhatsApp conversation. This is separate from Teams, Email, SIP phone calls, and the browser interface. WhatsApp users are identified through the phone number used in the conversation and must be mapped to authorized users according to the deployment configuration. *** ### Prerequisites Before configuring WhatsApp in the Dorg Console, make sure the following are available: * A personal Facebook account with access to Meta for Developers. * A Meta Business Portfolio / Business Manager account. * A WhatsApp Business Account, also called WABA. * A phone number dedicated to WhatsApp Business. * Access to the Dorg Console with administration permissions. * The public webhook URL shown in the Dorg Console. * Business details required by Meta, such as legal name, VAT/tax ID, official documents, and website. The phone number must not already be registered with the WhatsApp consumer app or WhatsApp Business app. If it is already registered, delete the existing WhatsApp account for that number before adding it to Meta. *** ### Open the WhatsApp Configuration Page in Dorg 1. Open the Dorg Console URL provided by your IT team. 2. Sign in with an account that has Console administration access. 3. In the left-hand sidebar, open **WhatsApp Configuration**. 4. Keep this page open while completing the Meta setup. The WhatsApp configuration page contains the values that must be copied into Meta, such as the webhook callback URL and verify token, and the fields where Meta credentials must later be entered. *** ### Values Required by the Dorg Console During the Meta setup, collect the following values: * **Phone Number ID** * **WhatsApp Business Account ID** * **Permanent access token** * **Meta App ID** * **Meta App Secret** * **Graph API version**, for example `v25.0` The Console may also display or require: * **Webhook callback URL** * **Webhook verify token** * **Webhook status** * **Configuration status** Do not store access tokens or App Secrets in shared documents, tickets, emails, or screenshots. *** ### Register as a Meta Developer 1. Go to [developers.facebook.com](https://developers.facebook.com). 2. Click **Get Started**. 3. Log in with your Facebook account. 4. Complete developer registration: * verify your phone number; * enter a contact email; * accept the Meta terms. 5. After registration, open the **My Apps** dashboard. *** ### Create or Select the Business Portfolio The Business Portfolio owns the WhatsApp Business Account, Meta app, system users, and payment method. 1. Go to [business.facebook.com](https://business.facebook.com). 2. Create a new Business Portfolio or select the existing one used by your organization. 3. Complete the business details: * legal company name; * address; * website; * tax information. Business verification is required to remove initial messaging limits and approve the WhatsApp display name. Business verification is available from: ``` Business Settings -> Security Center -> Start Verification ``` Verification usually takes several business days. *** ### Create the Meta App 1. Go to **Meta for Developers -> My Apps -> Create App**. 2. Select **Other**, then choose **Business** as the app type. 3. Enter the app name and contact email. 4. Select the Business Portfolio used for Dorg. 5. Create the app. 6. In the app dashboard, add the **WhatsApp** product. 7. Accept the WhatsApp Cloud API terms. 8. Link or create the WhatsApp Business Account. From **Settings -> Basic**, copy and save: * **App ID** * **App Secret** The App Secret will later be entered in the Dorg Console. *** ### Test the WhatsApp Cloud API Setup Meta provides a temporary test phone number for initial validation. 1. In the Meta app sidebar, open **WhatsApp -> API Setup**. 2. Click **Generate access token**. 3. Copy the temporary token only for testing. 4. Copy: * **Phone Number ID** * **WhatsApp Business Account ID** 5. Add a personal WhatsApp number as a test recipient. 6. Send the pre-approved `hello_world` template. This confirms that the Meta app and WhatsApp product are working. Temporary tokens expire quickly and must not be used in the Dorg Console for production. *** ### Add the Production Phone Number 1. Open **WhatsApp -> API Setup** or WhatsApp Manager. 2. Click **Add phone number**. 3. Enter the business profile information: * display name; * business category; * description; * phone number. 4. Verify the number by SMS or voice call. The display name must match the legal business name or be clearly associated with the company website. If the number remains in `Pending` state, check that: * business verification is complete; * a payment method is configured; * the display name complies with Meta policies. *** ### Add a Payment Method 1. Go to **Business Settings -> Accounts -> WhatsApp Accounts**. 2. Select the WhatsApp Business Account used by Dorg. 3. Open **Settings -> Payment Settings**. 4. Add a payment method. A production WhatsApp number requires a payment method before it can send production traffic at normal volume. *** ### Configure the Webhook in Meta The webhook connects Meta WhatsApp events to Dorg. 1. In the Dorg Console, open **WhatsApp Configuration**. 2. Copy the **Webhook callback URL**. 3. Copy the **Verify token**. 4. In Meta for Developers, open the app. 5. Go to **WhatsApp -> Configuration**. 6. In the **Webhook** section, click **Edit**. 7. Paste the Dorg webhook callback URL. 8. Paste the verify token from the Dorg Console. 9. Click **Verify and save**. Meta sends a verification request to Dorg. If the token matches, the webhook is saved successfully. *** ### Subscribe to the `messages` Webhook Field After the webhook URL is verified, enable the webhook field required for WhatsApp messages. 1. In the Meta app, open the WhatsApp webhook fields section. 2. Find the `messages` field. 3. Enable the subscription. The `messages` field is required for: * inbound messages; * delivery status updates; * read status updates. Other fields are usually not required for standard Dorg WhatsApp usage. *** ### Subscribe the Meta App to the WABA If the Meta webhook test works but real WhatsApp messages do not reach Dorg, the app may not be subscribed to the WhatsApp Business Account. Check the subscribed apps with: ```http GET https://graph.facebook.com/v25.0/{WABA_ID}/subscribed_apps Authorization: Bearer {TOKEN} ``` If the Dorg Meta app is not listed, subscribe it with: ```http POST https://graph.facebook.com/v25.0/{WABA_ID}/subscribed_apps Authorization: Bearer {TOKEN} ``` The token used for this operation must include: * `whatsapp_business_management` * `whatsapp_business_messaging` A successful response is: ```json { "success": true } ``` Run the `GET` request again to confirm that the app is now subscribed. *** ### Create a Permanent Access Token The Dorg Console requires a permanent access token generated from a Meta System User. Temporary tokens from API Setup or Graph API Explorer must not be used for production. #### Create the System User 1. Go to **Meta Business Manager -> Business Settings**. 2. Open **Users -> System Users**. 3. Click **Add**. 4. Enter a name, for example `dorg-whatsapp`. 5. Set the role to **Admin**. 6. Create the system user. #### Assign the Meta App 1. Go to **Business Settings -> Accounts -> Apps**. 2. Select the Meta app used for Dorg. 3. Add the system user. 4. Grant full access, including **Manage app**. 5. Click **Assign**. #### Assign the WhatsApp Business Account 1. Go to **Business Settings -> Accounts -> WhatsApp Accounts**. 2. Select the WABA used for Dorg. 3. Add the same system user. 4. Grant full access, or at least access to messages and phone numbers. 5. Click **Assign**. #### Generate the Token 1. Return to **Users -> System Users**. 2. Select the system user. 3. Open **Access Token Generation**. 4. Select the Meta app. 5. Enable: * `whatsapp_business_management` * `whatsapp_business_messaging` 6. Generate the token. 7. Copy it immediately. Meta shows the token only once. *** ### Configure WhatsApp in the Dorg Console Return to the Dorg Console and open **WhatsApp Configuration**. Enter the values collected from Meta. **Enabled**\ Enable WhatsApp for this Dorg deployment. **Graph API Version**\ Enter the Graph API version used by the Meta app, for example `v25.0`. **Phone Number ID**\ Enter the Phone Number ID from **WhatsApp -> API Setup**. **WhatsApp Business Account ID**\ Enter the WABA ID from Meta. **Permanent Access Token**\ Enter the System User token generated in Meta Business Manager. **Meta App ID**\ Enter the App ID from **Settings -> Basic** in Meta for Developers. **Meta App Secret**\ Enter the App Secret from **Settings -> Basic** in Meta for Developers. After saving, the Console should report the WhatsApp configuration as configured. Secret values may not be displayed again after saving. *** ### Validate the Configuration After saving the configuration in the Dorg Console: 1. Confirm that the WhatsApp configuration status is **Configured**. 2. Confirm that the Meta webhook is verified. 3. Confirm that the `messages` webhook field is subscribed. 4. Confirm that the Meta app is subscribed to the WABA. 5. Send a real WhatsApp message to the configured business number. 6. Verify that Dorg receives the message and replies. 7. Test with a user phone number that is authorized for the deployment. *** ### Messaging Rules WhatsApp enforces a 24-hour service window. Within 24 hours from the user's latest message, Dorg can send free-form replies. Outside the 24-hour window, Dorg must use approved WhatsApp message templates. Message templates are managed from WhatsApp Manager: ``` WhatsApp Manager -> Message Templates ``` Templates must be approved by Meta before they can be used in production. *** ### Security Best Practices * Do not share the permanent access token. * Do not paste the token into tickets, emails, screenshots, or documentation. * Store secrets only in the Dorg Console or the approved secret management system. * Never expose the token to frontend or client-side applications. * If a token is compromised, regenerate it from the System User profile. * Rotate credentials according to your organization security policy. *** ### Move to Production Before using WhatsApp in production, confirm that: * the Meta app is in **Live** mode; * the Privacy Policy URL is configured in Meta; * the production phone number is verified; * the display name is approved; * the payment method is configured; * business verification is completed or in progress; * required message templates are approved; * the Dorg Console contains the production Phone Number ID; * the Dorg Console contains the permanent System User token; * the webhook is verified and subscribed to `messages`; * a real inbound and outbound WhatsApp test has been completed. *** ### Troubleshooting **The Meta webhook verification fails.**\ Check that the callback URL and verify token were copied exactly from the Dorg Console. The callback URL must be publicly reachable over HTTPS. **The Meta webhook test works, but real messages do not arrive in Dorg.**\ Check that the app is subscribed to the WABA through `/{WABA_ID}/subscribed_apps` and that the `messages` field is enabled. **Messages cannot be sent from Dorg.**\ Check the Phone Number ID, permanent access token, WABA permissions, payment method, and WhatsApp messaging limits. **The token works at first but later stops working.**\ A temporary token may have been used. Generate a permanent token from a Meta System User and save it in the Dorg Console. **The phone number remains pending.**\ Check business verification, payment method, and display name approval. **Users do not receive replies outside the 24-hour window.**\ Create and approve WhatsApp message templates. Free-form replies are allowed only inside the 24-hour service window. *** ### Checklist * [ ] Meta Developer account created. * [ ] Business Portfolio selected or created. * [ ] Business verification started or completed. * [ ] Meta Business app created. * [ ] WhatsApp product added to the app. * [ ] WhatsApp Business Account created or linked. * [ ] Production phone number registered and verified. * [ ] Payment method configured. * [ ] Display name submitted and approved. * [ ] App ID copied from Meta. * [ ] App Secret copied from Meta. * [ ] Phone Number ID copied from Meta. * [ ] WhatsApp Business Account ID copied from Meta. * [ ] System User created. * [ ] Meta app assigned to the System User. * [ ] WABA assigned to the System User. * [ ] Permanent token generated with `whatsapp_business_management`. * [ ] Permanent token generated with `whatsapp_business_messaging`. * [ ] Webhook callback URL copied from the Dorg Console into Meta. * [ ] Verify token copied from the Dorg Console into Meta. * [ ] Webhook verified successfully. * [ ] `messages` webhook field subscribed. * [ ] Meta app subscribed to the WABA. * [ ] WhatsApp values saved in the Dorg Console. * [ ] Dorg Console reports WhatsApp as configured. * [ ] Real inbound message test completed. * [ ] Real outbound reply test completed. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.dorg.pro/install-dorg/optional-configurations/messaging-via-whatsapp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.