WhatsApp Business

The module brings WhatsApp into the same workspace as your sales and service records. Your team can:

• Read, reply to, assign, and label conversations in a shared inbox.
• Add internal notes and use saved replies without exposing internal discussion to the customer.
• Load Meta-approved message templates and map their variables.
• Create keyword bots, message bots, and structured response flows.
• Send tested, scheduled campaigns and drip sequences to consented audiences.
• Create leads from incoming conversations and route follow-up to the right person.
• Synchronize supported products with a WhatsApp catalog and review order activity.
• Review delivery analytics, activity logs, webhook logs, and opt-outs.

Start with one business number, one staff group, and one repeatable use case. Expand only after messages, replies, assignments, and opt-outs have been tested end to end.

Assign only the access each person needs.

| Role | Recommended access |
|---|---|
| WhatsApp administrator | Connection settings, phone numbers, templates, webhooks, retention, and all diagnostic logs. |
| Inbox agent | Assigned conversations, replies, notes, labels, and saved replies. No access to credentials. |
| Campaign manager | Audiences, approved templates, test sends, scheduling, campaigns, and opt-out review. |
| Automation manager | Bots, triggers, flows, business hours, and CRM routing rules. |
| Analyst or supervisor | Inbox oversight, delivery analytics, activity logs, and operational reports. |

Before going live, confirm that agents can see only the conversations and actions appropriate to their role. Keep the Meta App Secret and access token restricted to trusted administrators.

1. Prepare the Meta account

• Confirm that the business is available in Meta Business Manager.
• Prepare a Meta app, a WhatsApp Business Account, and a phone number eligible for the WhatsApp Business Platform.
• Make sure the person connecting the account has the required Meta permissions.
• Document how customers give consent and how your team will handle requests to stop messages.

#### Find the WhatsApp API setup in Meta's current interface

Meta may show the WhatsApp setup as a use case instead of a separate product menu:

1. Open Meta for Developers - My Apps and select the app used for Xfatora.
2. Open Use cases, then select Connect with customers through WhatsApp and choose Customize.
3. Select the business portfolio that owns the intended WhatsApp Business Account. If the portfolio card is still loading, wait for it to finish before continuing.
4. Under Basic setup, open Step 1: Try it. This is the current equivalent of WhatsApp - API Setup.
5. Select or create a test recipient and choose Generate access token. The generated token is temporary and is suitable only for setup validation.
6. Use Step 2: Set up for production to add the real business number and prepare a production credential.

If Required actions is empty, return to Use cases. An empty page means there is no pending action; it does not contain the WhatsApp access token.

#### Do not confuse the Meta identifiers

| Value | Where to find it | Where it belongs in Xfatora |
|---|---|---|
| Meta App ID | App settings - Basic | Step 1, Meta App ID. It identifies the developer app only. |
| Meta App Secret | App settings - Basic | Step 1, Meta App Secret. Treat it as a password. |
| WhatsApp Business Account ID (WABA ID) | Basic setup - Step 1: Try it, beside the WhatsApp Business Account label | Step 2, WhatsApp Business Account ID. This is the ID used to load templates and phone numbers. |
| Phone Number ID | The same Meta setup page, beside Phone Number ID | The sending-number identity. Xfatora loads it after the correct WABA connection. |
| Access token | Basic setup - Step 1: Try it - Generate access token | Step 2, WhatsApp access token. Use a temporary token only for testing. |

Never enter the Meta App ID in the WABA ID field. The values can look similar because both are long numbers, but they represent different Meta objects.

The Meta test number, often displayed with a `555` number, is not the customer's production number. Complete the production setup before expecting messages from the real business number.

#### Replace Meta's `555` test number with the real business number

1. In the WhatsApp use case, open Basic setup - Step 2: Set up for production.
2. Select the business portfolio that owns the company, then select or create the intended WABA. Do not continue with Meta's automatically created test account if the company already has the correct WABA.
3. Choose Add phone number. Enter the public business display name, category, timezone, and the other requested business details exactly as customers should see them.
4. Select the country and enter the real business number. If Meta shows a separate country selector, choose Saudi Arabia `+966` and enter the number without its domestic leading zero. If it shows one field, use the complete international format, such as `+966540685712`.
5. Choose SMS or voice verification, receive the one-time password, enter it in Meta, and wait until the phone-number status is connected or registered.
6. Complete any business verification or payment-method requirement shown by Meta. These requirements are controlled by Meta and can differ by account.
7. Open WhatsApp Manager or return to the API setup and copy the Phone Number ID for the real number. Confirm the WABA ID on the same page.
8. Create a production access token from Business settings - Users - System users. Assign the Xfatora Meta app and the correct WhatsApp account to that system user, then generate a token with `whatsapp_business_management` and `whatsapp_business_messaging`. Choose the longest expiry Meta allows and record its renewal date.
9. In Xfatora, replace the test WABA/token with the production WABA and system-user token, select Complete setup, refresh the phone numbers, and choose the Saudi number as the default sender.
10. Send one approved template to an internal number in full international format and confirm delivery, reply, and webhook status before opening the number to staff.

If the number is already used in the WhatsApp or WhatsApp Business mobile app, follow the coexistence or migration path Meta presents. Do not remove or migrate a live number until the business understands the effect on its current app and message history.

2. Connect WhatsApp to Xfatora

Open WhatsApp → Settings. Use the Facebook/Meta embedded connection when available; it is the simplest route because it guides you through selecting the business account and phone number.

If manual setup is required, enter the WABA ID and access token shown in your Meta configuration. For embedded signup, the administrator may also need the Meta App ID, App Secret, and Configuration ID. Never send these values in chat or email, and never place them in a public document.

Connect the webhook in Step 1, then complete the WhatsApp account setup in Step 2. A successful webhook connection confirms the app callback configuration, but it does not prove that the WABA ID is correct. Xfatora validates the WABA separately when it loads templates.

Before selecting Complete setup, compare the WABA ID in Xfatora with the value explicitly labelled WhatsApp Business Account ID in Meta. Do not copy the App ID from the app header into this field.

Save the connection, select the default sending phone number, and reload the page if prompted.

###

1. Test the connection

1. Enter your own test number in full international format, beginning with `+` and the country code.

• Remove the domestic leading zero, spaces, and punctuation. For example, Saudi number `0540685712` becomes `+966540685712`.
• When sending from Meta's test number, the recipient must first be added and verified as a test recipient in Meta.

1. Send a test message from Xfatora.
2. Reply from the phone.
3. Confirm that both directions appear in the shared inbox.
4. Assign the conversation, add an internal note, apply a label, and close or resolve it according to your process.

Do not continue to campaigns until this test works reliably.

4. Load templates and configure the team

• Refresh the template list and confirm that approved Meta templates appear.
• Verify the language and purpose of each template before using it.
• Map every variable to a real field and preview a sample with realistic data.
• Configure staff permissions, ownership rules, business hours, labels, and saved replies.
• Confirm the scheduled-task service (cron) is running before scheduling campaigns or drip messages.

Manage the shared team inbox

Open WhatsApp → Conversations to review new and active chats. Assign each conversation to an owner, use labels to show its purpose or status, and keep operational comments in internal notes. Saved replies are useful for consistent answers, but agents should review the final message before sending it.

When handing a conversation to sales or support, include a clear next action and due date in the relevant Xfatora record. The inbox should show ownership; it should not become a second, disconnected task list.

Send approved templates correctly

Free-form replies are normally allowed during the 24-hour customer service window after the customer’s latest message. Starting or restarting a business conversation outside that window generally requires a Meta-approved template.

Before sending a template:

1. Confirm that its status is approved in Meta and refreshed in Xfatora.
2. Choose the correct language version.
3. Map variables in the exact approved order.
4. Preview names, dates, currencies, links, and optional values.
5. Send to an internal test contact first.

Build bots and response flows

Use a keyword bot for a focused repeat request, such as business hours or order status. Use a structured flow when you need to collect several answers or route the customer.

Begin with one trigger. Test expected wording, misspellings, messages outside business hours, and the handoff to a human. Avoid overlapping triggers that could send more than one answer. Always give customers a clear route to a staff member.

Run a responsible campaign

1. Select a documented, consented audience; never use purchased or unverified lists.
2. Choose an approved template and validate every variable.
3. Send an internal test and inspect the message on a real phone.
4. For CSV audiences, use UTF-8, keep the required headings, and use international phone format.
5. Start with a small group, then schedule the full campaign or drip sequence.
6. Monitor delivery, replies, failures, and opt-outs during the send.
7. Stop or adjust the campaign if the response or failure pattern is unexpected.

Convert conversations into CRM work

Enable automatic lead creation only after defining the lead source, default status, assignment rule, and duplicate-handling process. Test with a new number and a known customer number. Confirm that incoming messages do not create duplicate leads and that the assigned person receives the expected record.

You can also design flows that collect information for sales, tickets, or projects. Keep the customer-facing questions short and send the final response to the correct Xfatora record.

Synchronize the catalog

Before synchronizing products, check names, descriptions, prices, images, availability, and identifiers. Start with a small product group and compare the WhatsApp catalog with Xfatora. Resolve rejected or incomplete products before synchronizing the full catalog.

Use the WhatsApp dashboard and logs to review:

• Sent, delivered, read, failed, and replied messages.
• Conversation volume, active ownership, and unresolved work.
• Campaign performance, template use, and delivery failures.
• Opt-outs and contacts who must no longer receive promotional messages.
• Activity history for configuration and staff actions.
• Webhook processing results when inbound messages or statuses are missing.

Review opt-outs and failures after every campaign. Review assignment and unresolved conversations at least daily. Limit access to message content and logs according to your privacy and retention policy.

| Issue | What to check |
|---|---|
| The page does not load | Refresh once, confirm the module is active for the tenant, verify staff permission, then give support the page address and time of the error. |
| The account will not connect | Confirm Meta permissions, the selected business and WABA, the eligibility of the phone number, and that credentials have not expired. |
| `Tried accessing nonexisting field (message_templates)` | The value entered as the WABA ID is usually the Meta App ID or another object ID. Copy the value labelled WhatsApp Business Account ID from Meta, replace the WABA field in Xfatora, and select Complete setup again. |
| The webhook connects but completing setup fails | Webhook setup and WABA validation are separate. Keep the successful webhook, then correct the WABA ID and access token in Step 2. |
| The token is valid but expires soon | A token generated under Step 1: Try it is temporary. Use it to validate setup, then complete Meta's production setup and issue an appropriate long-lived system-user credential. |
| Only a `555` phone number appears | This is Meta's test number. Add and verify the real business number under Step 2: Set up for production. |
| A token or App Secret appeared in a screenshot | Treat it as exposed. Revoke or rotate it in Meta, create a replacement, and paste it directly into Xfatora without sending or photographing it. |
| An approved template is missing | Refresh templates, confirm the correct WABA and language, and verify that Meta shows the template as approved. |
| A template was rejected | Read the reason in Meta, correct the wording/category/variables there, resubmit, and refresh the list after approval. |
| A test message was not delivered | Use international format, select the correct default number, check the 24-hour window or template requirement, then inspect message and webhook logs. |
| A bot does not reply | Confirm it is active, the trigger matches, its business-hour rules allow a reply, and no higher-priority bot uses the same trigger. |
| A scheduled campaign did not start | Confirm the campaign is active, timezone and schedule are correct, an approved template is selected, and the server scheduled-task service is running. |
| Duplicate leads are created | Review the phone-number format and duplicate matching rule, then test with a known contact before re-enabling automatic lead creation. |
| The connection suddenly stopped | Check Meta business status, token validity, phone-number status, recent configuration changes, and webhook logs. |
| A staff member cannot see WhatsApp | Confirm the module is assigned to the tenant and the staff member has the required menu and action permissions. |

Go-live checklist

• Connection and two-way messaging tested.
• Default number selected.
• Staff permissions and conversation ownership tested.
• At least one approved template tested inside and outside the 24-hour window.
• One bot tested with a human handoff.
• Consent source and opt-out process documented.
• Scheduled tasks confirmed if campaigns or sequences are used.
• Logs, retention, and escalation responsibilities assigned.

Meta controls template approval, platform availability, policy enforcement, and WhatsApp Business messaging charges. Xfatora provides the operating workspace but cannot bypass those rules.

Request a guided WhatsApp setup · Return to the WhatsApp module page