Enable WhatsApp and messaging
Link a WhatsApp Business number and understand how written conversations operate.
The WhatsApp skill links a WhatsApp Business number to the bot to handle written conversations and incoming calls.
Connect a number
- Enable the WhatsApp skill.
- Click Connect my WhatsApp.
- Log in within the secure Meta window.
- In Meta, choose your WhatsApp Business account on phone or follow the workflow to select an account and add a number. Select the desired business and number.
- Confirm the number when Meta prompts you.
- Return to BeAI and check that the connection is active.
BeAI configures the technical elements of the integration. The client organisation remains the owner of its WhatsApp Business account and its Meta billing.
The same button allows you to connect a Cloud API number or a WhatsApp Business account on a phone: the choice is made in the Meta window, with no technical configuration in BeAI. Selecting the phone account requests coexistence between the mobile app and BeAI from Meta. Keep WhatsApp Business up to date and follow the confirmation prompt on the phone. Do not delete your account or the app to try to make the number eligible. Meta remains responsible for eligibility: if the window displays This number cannot be shared with this app, send support the screenshot, time and session ID displayed in that window. This error occurs before connecting in BeAI.
A newly activated WhatsApp Business account may be rejected: Meta states that additional activity in the app may be required to determine its eligibility. Use the account normally with your contacts, then retry the coexistence journey. Meta does not guarantee any timeframe or message count. An existing link to Meta Business Suite is not sufficient to identify the cause: support must verify the precise reason before any disconnection. Registration errors documented by Meta.
If Meta displays This phone number cannot be registered and cannot migrate (3441034), also keep the session reference following the code. This message alone does not indicate a lack of activity or a conflict with Business Suite. Forward these details to BeAI support for diagnosis; do not delete the mobile account or its link based solely on this rejection.
If Meta offers Continue with your previous settings, BeAI can automatically retrieve the single WhatsApp account already authorised even when Meta does not pass the account back to the page. If several accounts are authorised without an explicit selection, restart the connection, choose Edit settings, and select a single WhatsApp Business account.
The Meta window and the BeAI page must remain open until the automatic return completes. If your browser or an extension blocks this secure return, BeAI will not use the incomplete code and will ask you to restart the connection.
If BeAI displays a code validation error after your Meta confirmation, refresh the bot page and restart Connect my WhatsApp to obtain a new authorisation. Select the account and number already created: do not recreate them. If the error persists, provide support with the bot number and the time of the attempt. No return URL or technical key needs to be entered by the client.
Administrative connection and bot operation
BeAI uses your company's own Meta authorisation to configure the number, send messages and manage calls. No manual assignment of a Beone system user to your account is necessary.
The authorisation remains independent of your portal login session. If Meta sets an expiry date for it or if it is revoked, use Connect my WhatsApp to renew it by selecting the same account and the same number. Do not delete your WhatsApp account to reconnect BeAI.
During reconnection, BeAI checks whether the number is already active on WhatsApp Cloud API. If so, it restores access and inbound events without re-registering the number or changing its two-step verification PIN. This also works after disconnecting in BeAI. A new number must always complete the registration requested by Meta.
Inbound calls
When connecting the number, BeAI asks Meta to enable inbound calls and the call icon in WhatsApp. The Incoming calls field displays the result. Check refreshes this status. Messaging remains usable if Meta refuses call activation; the reason appears separately. After resolving the issue in Meta, reconnect the same number to retry activation.
Meta currently requires a messaging limit of at least 2 000 recipients to activate calls. If the number already uses external SIP routing, this must be disabled in Meta for calls to reach BeAI. If the icon is not yet visible after activation, open contact info in WhatsApp to refresh its display.
The Incoming calls status confirms activation on Meta's side. Also test a call to check that the bot answers with audio. If messages work but calls fail despite this status, send the bot number and the time of the test to support. A voice service error may require a fix by BeAI without reconnecting your Meta account.
The Meta configuration used by BeAI can issue an authorisation without expiry. In this case, no periodic reconnection every 60 days is required. An authorisation revoked or invalidated by Meta must nevertheless be renewed.
Connection and verification operations are also available in API /api/v1/bots/{id}/skills/whatsapp. Responses expose calling_status (unknown, enabled, disabled, unavailable) and calling_error, without exposing the Meta token.
To start the same journey from an integration, GET /api/v1/bots/{id}/skills/whatsapp/onboarding provides signup.launch_extras.business_app: pass this object into extras of FB.login to enable the native Meta choice between API and phone accounts, then use the common operations onboarding/discover and onboarding/complete. signup.launch_extras.cloud_api remains available for existing integrations limited to API numbers. No flag sent by the client bypasses number verification on Meta's side.
Monitoring conversations
Received voice messages are saved as attachments and forwarded to the AI model to understand their content. If the history displays WhatsApp attachment not downloaded, the bot did not receive the audio content. Report the bot number and message timestamp to support. Once corrected, resend the voice message; no Meta reconnection is required.
WhatsApp conversations appear alongside calls in the history and live view. The channel allows you to distinguish between them, and filters help you find a bot or a date range.
Session closure and reminders
System settings and API PATCH /api/v1/system-settings/whatsapp are shared across WhatsApp, Messenger and website chat. After the inactivity timeout, BeAI asks once "Do you have any other questions?", without announcing a closure. Without a reply, the session closes silently after the next timeout, without a Session ended message. By default, both timeouts are set to 5 minutes. A reply continues the same session; further inactivity uses the sum of the timeouts and does not send a second question. If the question is disabled, closure remains silent after the sum of the timeouts. The automated question does not use AI and is not billed. Voice calls remain unchanged.
When the conversation is finished, the bot can send a brief closing sign-off. The additional technical message Session ended is no longer sent in WhatsApp; the closure remains visible in the BeAI history. If you wish to adapt the bot's sign-off, specify it in its instructions.
A closed session no longer receives inactivity reminders. The contact's next message opens a new session with the bot. After closure due to inactivity, no additional technical message is sent either.
The summary, detected language and sentiment are computed asynchronously: they may appear after the session closes. The interface and GET /api/v1/conversations/{id} present the same information with the same permissions; ended_at indicates actual closure, independently of the summary. The analysis state appears in channel_metadata.whatsapp.final_report.status (pending, completed or failed). An analysis error does not reopen the conversation or restart reminders. Previous history is not reanalysed automatically.
Before opening to clients
Comply with Meta rules regarding consent, message templates and conversation windows. Have the complete journey validated using a test number before using a commercial number.
Human takeover
Configuration is performed in the Chat human handover skill, which is shared across WhatsApp, Messenger and Website Chat. Search for your team members in its tag field, specify instructions and the timeout before returning to the bot, then save. New requests arrive in the BeAI Inbox, with browser notifications. The WhatsApp skill no longer contains takeover settings.
Replying from WhatsApp Business
If your number is shared between the WhatsApp Business app and BeAI, a reply sent directly from the company's app interrupts the AI session concerned. BeAI links it to the same human takeover as in its Inbox and preserves incoming messages and human replies forwarded by Meta. Other conversations continue to be handled by the bot.
Each new customer message or human reply extends the Inactivity before return to bot timer, configured in the shared skill, between 1 and 10 080 minutes. Duplicates, historical messages and delivery receipts do not extend this timer. Upon expiry, no automatic message is sent: the customer's next new message opens a new session with the bot. You can also take over the conversation in BeAI, transfer it to a colleague, return it to the bot or close it.
Detecting intervention from a handset requires a number compatible with WhatsApp Business sharing and events forwarded by Meta. It does not revoke native permissions already granted to your WhatsApp Business account. A Cloud API connection alone does not guarantee this sharing.
Shared configuration and inbox
WhatsApp Business alerts with Accept/Decline buttons, their Meta templates and their specific tests have been removed. Configure team members and their browser notifications under Chat human handover, then use the BeAI takeover menu to assign conversations. Historical data from previous takeovers remains accessible; integrations must use the shared operations.
Public configuration is managed with PATCH /api/v1/bots/{id}/skills/chat-human-takeover. The queue and its actions run via /api/v1/chat-inbox, using the same permissions and organisation scope as the interface. The legacy WhatsApp skill parameters human_takeover and whatsapp_compatibility are no longer accepted; use the shared skill instead. No Meta tokens are exposed. The Chat human handover guide covers assignment, notifications, returning to the bot and closing conversations.
Message reactions
Received WhatsApp reactions appear under messages retained in the BeAI history, just like in Messenger. Replacements and deletions are supported. During an active AI session, the contact's reaction is immediately passed to the AI along with the text of the relevant message: the AI can thus interpret it and respond according to context. This processing uses standard AI pricing and resets the inactivity timer, without extending Meta's 24-hour response window. A reaction after closure or human takeover remains in the history; it does not trigger the AI again and incurs no billing. Meta does not forward reactions to messages older than 30 days. The conversation detail API and text exports present the same state as the interface.