Enable WhatsApp and messaging

The WhatsApp skill connects a WhatsApp Business number to the bot for written conversations.

Connect a number

1. Enable the WhatsApp skill.
2. Choose Connect my WhatsApp.
3. Sign in through the secure Meta window.
4. Select the business and an existing number, or follow the flow to add a new number.
5. Confirm the number when requested by Meta.
6. Return to BeAI and check that the connection is active.

BeAI configures the technical integration. The customer organisation remains the owner of its WhatsApp Business account and Meta billing.

Administrative access and bot operation

BeAI uses the Meta authorisation granted for your own business to configure the number, send messages and manage calls. You do not need to assign a Beone system user to your account manually.

This authorisation is independent of your portal login session. If Meta sets an expiry date or access is revoked, use Connect my WhatsApp to renew access to the same account and number. Do not delete your WhatsApp account to reconnect BeAI.

Monitor conversations

WhatsApp conversations appear alongside calls in history and live views. The channel distinguishes them, while filters help find a bot or period.

Before customer rollout

Follow Meta's rules for consent, message templates and conversation windows. Validate the complete journey with a test number before using a commercial number.

Incoming calls

When reconnecting, BeAI checks whether the number is already active on WhatsApp Cloud API. If it is, BeAI restores access and incoming events without registering the number again or changing its two-step verification PIN. This also applies after disconnecting in BeAI. New numbers still need to complete Meta registration.

When connecting a number, BeAI asks Meta to enable incoming calls and the call icon. Incoming calls displays the result; Refresh checks it again. Messaging remains available if Meta refuses calling activation, with a separate error. After resolving the Meta restriction, reconnect the same number to retry.

Meta currently requires a messaging limit of at least 2,000 recipients. External SIP routing must be disabled in Meta for calls to reach BeAI. Open the contact information in WhatsApp to refresh a missing call icon after activation.

A Meta configuration with no token expiry avoids periodic 60-day reconnection. Revoked or invalidated authorisations still require reconnection. The public WhatsApp API exposes calling_status (unknown, enabled, disabled, unavailable) and calling_error, without exposing Meta tokens.

Human takeover in WhatsApp Business

When a request needs human help, the bot can request takeover. The team receives an alert on the company's shared WhatsApp Business account, with Accept and Decline. Enable native WhatsApp notifications on the smartphone and computer; BeAI cannot inspect their settings. Reading or dismissing an alert makes no decision.

Acceptance closes that customer's AI session. The human replies directly from the company's WhatsApp Business account, under the same business number, with a separate native conversation for each customer. Personal numbers stay private, and other customers keep using the bot. Customer messages are never relayed to the agent's personal WhatsApp chat.

Enable takeover

A bot administrator opens WhatsApp skill > Human takeover:

1. Enable Human takeover.
2. Use the editor that appears to describe when the bot may request takeover: an explicit request for a person, missing information or a business limit.
3. Save the bot.

BeAI reuses recipients and alerts that are already prepared. If no recipient is configured, an authorized user in the organisation is suggested when possible. You can keep the usual settings: 120 seconds to accept and 60 minutes without activity before returning to AI. Disabling takeover preserves your instructions without applying them.

The number and alerts still need initial preparation with Meta. Validate this once on the actual number and devices; enabling the switch does not create that validation. If takeover is not ready, BeAI explains the blocking reason. Ask your administrator to finish preparation before trying again.

Advanced options

Advanced options appears only when takeover is enabled and stays closed by default. Open it to change authorized BeAI users, timeouts and service messages, or test alerts. Opening, closing or hiding this section preserves all settings. The request instructions use Markdown (request_prompt, maximum 10,000 characters); disabling Allow the bot to request takeover keeps manual requests but removes the AI tool.

Alerts use the shared Business account only. A distinct internal sender alerts the company's account; agents do not register individual WhatsApp numbers. Enabling takeover authorizes team decisions. WhatsApp decisions identify the team and shared account, not the individual person who clicked.

For initial preparation, enable the switch to show advanced options, confirm access to the Business account, notifications and devices, then send a test alert. The test saves authorized users and alert references without enabling AI takeover; save the bot after validation to activate it. Activation requires validated Coexistence eligibility, a real Business App message echo, a decision on a test alert, an available approved template and confirmed devices. A connected API number alone is insufficient. The form displays availability or blocking reasons. Meta onboarding and actual devices must be tested: API numbers cannot always be converted automatically and WhatsApp calling has separate restrictions.

Everyone with native access to a shared Business account can see its conversations. Removing BeAI permissions does not revoke an existing WhatsApp account access.

Waiting and inactivity

The decision timeout defaults to 120 seconds, configurable between 30 and 900 seconds. AI replies pause while waiting. Declining the alert from the shared account declines the request for the team. If nobody accepts or the alert cannot be sent, BeAI reports unavailability and resumes queued AI messages.

Accepted threads default to 60 minutes without activity before returning to AI. Each new customer message, including voice notes, and each human Business App reply renews the expiry. Delivery/read statuses and duplicates do not renew it. Bot administrators can configure 1 to 10,080 minutes; existing accepted takeovers keep their previous duration.

Expiry sends no message and starts no session. The next fresh customer message starts a new AI session subject to normal credit checks. A known human activity tracking incident keeps the takeover protected and appears in availability status.

Supervision and API

The conversation list and details show takeover states, including Takeover requested and Human takeover accepted. Authorized actions are available in that context: accept or decline, and for bot administrators, cancel pending requests or return human threads to the bot. Release creates no session until the next customer message. No separate takeover menu or page is needed. Everyday handling stays in WhatsApp: accept or decline the alert, then reply to the customer from WhatsApp Business. Old AI history stays available. Disabling takeover cancels pending requests and prevents new ones; accepted threads remain protected.

Equivalent /api/v1 operations cover /bots/{id}/skills/whatsapp configuration, /bots/{id}/whatsapp/takeover-recipients authorized users, /bots/{id}/whatsapp/takeovers listing, /conversations/{id}/whatsapp-takeover creation, /whatsapp/takeovers/{uuid} detail and actions, and /bots/{id}/whatsapp/takeover-notification-test. Conversation responses include action_items and action_groups, with the same states and presentation as the GUI. API keys use their owner's current permissions; links do not grant cross-organisation access. OpenAPI documents formats and errors. Meta tokens are never returned in read responses.

After preparation, minimal activation uses PATCH /api/v1/bots/{id}/skills/whatsapp:

{
  "human_takeover": {
    "enabled": true,
    "request_prompt": "Request takeover when the customer asks for a person or the available tools cannot resolve the request."
  }
}

enabled: true alone also works when prepared values are available. Omitted fields reuse existing settings and available authorized defaults; no Meta evidence is created. In shared mode, omitting collective_decisions_enabled when enabling authorizes collective decisions; explicitly sending false blocks activation. null still resets a field to its default. The fallback recipient is the eligible current user in the organisation; when a platform administrator outside that organisation intervenes, the eligible bot owner is used. Activation is rejected if there is no authorized recipient or ready notification flow.

To prepare alerts before activation, POST /api/v1/bots/{id}/whatsapp/takeover-notification-test accepts the three confirmations (devices_confirmed, business_account_access_confirmed, notifications_confirmed) and an optional configuration object containing only recipient_user_ids, notification_sender_id and notification_template. These references are saved before testing, without enabling or disabling takeover. The same permissions and evidence are checked: changing the references of an active takeover does not bypass Meta validation.

Availability displays Not checked before validation, Ready when the required evidence is present, or Degraded if activity tracking encounters a known incident. The API keeps the status codes documented in OpenAPI.

The Meta alert template contains exactly three body variables (bot name, case reference, UTC deadline); its first two quick-reply buttons are Accept and Decline, in that order. The alert preview does not contain the customer summary. The template must be approved in the configured language; a missing or rejected template blocks activation.

Restoring a bot version restores takeover settings disabled and requires fresh verification before activation. Previously accepted human threads stay protected.

Conversation exports include takeover history (reference, status, reason, summary and decision audit), without copying human WhatsApp exchanges or exposing internal numbers and control tokens. A protected takeover prevents deletion of the bot, conversation or affected user with whatsapp_takeover_active (HTTP 409). A bot administrator must cancel a pending request or explicitly release an accepted takeover before deletion; inactivity expiry alone can leave protection against late Business App echoes.

Meta consent, approved templates and reply windows still apply. OS notification delivery times are not guaranteed. Web Push is not part of this flow.