Using WhatsApp with SoAI

The server can answer messages sent to a WhatsApp Business phone number. Each sender becomes a messaging conversation in Chat and uses the model, workspace, sender access, and tools saved with the account.

Prepare WhatsApp and SoAI

  1. In the Meta developer console, add the WhatsApp product to an application, connect a WhatsApp Business Account, and add the business phone number that SoAI will use.
  2. In Meta Business Settings, create or select a System User, assign it the application and WhatsApp Business Account assets, then generate a permanent access token with whatsapp_business_management and whatsapp_business_messaging permissions.
  3. Copy the Phone number ID and Business account ID from the application's WhatsApp setup. Copy the Application ID and App secret from the same application's basic settings. Note the active Graph API version in the vNN.N format, and create a private verify token between 16 and 256 characters for the callback check.
  4. Confirm that the SoAI server has a public HTTPS address. In the SoAI WebUI, an administrator with Configuration changes (CONFIG_PATCH) selects the Settings button at the right of the header, chooses Settings, selects Advanced in the page header, opens Server, sets Public Origin, and selects Save. The setting is SERVER.PUBLIC_ORIGIN.

The application, token, business account, and phone number must belong together. The public origin must be an HTTPS address whose WhatsApp callback route is reachable from the internet. If a reverse proxy handles TLS, finish that routing first. Enter the base address without a WhatsApp webhook path; SoAI builds and registers the callback. The rest of the SoAI interface can remain private when you follow the selective callback routing in Network and TLS. Keep the access token, App secret, and verify token private.

WhatsApp requires the callback route to be public, not the complete SoAI WebUI or API. Exposing SoAI directly to the public internet is not recommended. Review Security hardening before enabling this integration.

The Messaging tab requires the SoAI permissions named Model read access (MODEL_READ), Public inference API access (OPENAI_API), and MCP usage (MCP_USE). These permissions do not require an external OpenAI account or API key. SoAI also needs an available model and the MCP tool catalog before Add account can open. Ask an administrator to review your access if the tab is missing.

Add WhatsApp in SoAI

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, then select Messaging.
  2. Select Add account.
  3. Enter an Account label, choose WhatsApp as the Provider, and select the language for SoAI's built-in provider messages under Remote response language.
  4. Enter the Access token, Phone number ID, Business account ID, Application ID, API version, App secret, and Verify token from the same Meta setup.
  5. Choose who may send messages. For restricted access, leave Accept messages from anyone off and enter one WhatsApp sender ID per line under Authorized provider senders. Use the exact messages[].from sender ID for that user from a WhatsApp webhook event, not the business Phone number ID. If you leave the list empty, SoAI accepts no senders.
  6. Under Chat execution, select a model and agent mode. Choose the workspace folder and display names, then select Edit parameters for account-specific model parameters.
  7. Choose any MCP tools the account may use. Turn on Require tool approval if SoAI should send an approval request to the WhatsApp conversation before running a tool that requires it.
  8. Select Save.

Remote response language controls built-in command, status, error, and interaction messages. To require a language for model answers, select Edit parameters and add that requirement to the System prompt.

SoAI checks the Meta application, token permissions, business account, and phone number before it stores the account. It then subscribes the application to messages and installs the WhatsApp callback. If Save reports that the application already uses a different callback, turn on Replace an existing provider callback only when SoAI may replace it, then select Save again. A callback failure after storage leaves the account in Degraded state.

A WhatsApp message can contain an image, document, audio file, video, or sticker, with or without supported message text or a caption. The server downloads the file, processes it with the same attachment pipeline used by Chat, and gives it to the model with the message. The file is also visible with that message in the matching Chat conversation. WhatsApp and server file limits still apply. See Attachments and file context for how models use different file types.

WhatsApp supports the text-only commands /help, /status, /cancel, and /new. See Connect messaging apps to SoAI for what they do and how to answer agent questions or tool approval requests.

Keep Allow plaintext secret replies off unless you accept the risk of a secret appearing in WhatsApp history or notifications. See Secrets vault for how tools request and store credentials.

Use the conversation in SoAI Chat

You can open the WhatsApp conversation in Chat and send a message there. That message and its immediate reply stay in Chat; neither is copied to WhatsApp. Both remain in the conversation transcript, so the model can use them as context when it answers a later WhatsApp message.

Files attached to a message sent from Chat also stay there. They can affect later model replies, but the server does not forward them to WhatsApp.

Chat locks the model, agent mode, workspace, display names, parameters, and MCP tools saved with the messaging account. To change them, or to update the WhatsApp credentials or sender policy, select the Settings button at the right of the header, choose Settings, select Messaging, and use Edit for the account.

This account can have its own context length and therefore its own effective compaction limit. Under Chat execution, select Edit parameters, then set Context length (tokens) under Model settings. Clear it to use the selected model's default. A lower value gives this account a smaller context budget, so SoAI compacts older context sooner. If a smaller model gives worse answers as a conversation grows, lowering this value can keep its active prompt shorter without changing your other messaging accounts.

Automatic context compaction lets the conversation continue without a fixed message-count limit. SoAI keeps recent turns and may replace older details with a summary before sending the next prompt to the model. See Chat for more about context compaction.

Check the connection

Wait for the account row under Settings > Messaging to show Active and Provider connection healthy, then send a message to the business number from an allowed WhatsApp number. A Meta development setup may limit messages to its configured test recipients. The setup works when SoAI replies in WhatsApp and the conversation appears in the SoAI Chat sidebar.

Each WhatsApp sender has a separate conversation and model context. Editing or deleting a WhatsApp message does not change the Chat transcript; send a new correction instead.

Fix common setup problems

If Meta rejects the access token, replace an expiring test token with a permanent System User token and check both required permissions. Application, business account, or phone mismatch errors mean that at least one ID came from a different Meta setup. Copy the values again from the application and WhatsApp Business Account that own the phone number.

A missing or non-HTTPS Public Origin prevents callback setup. If SoAI reports a callback conflict, confirm that the previous service no longer needs the subscription before allowing SoAI to replace it. A saved account shows Degraded when activation fails; correct the settings under Settings > Messaging > Edit, then save the account again.

Related documentation