WhatsApp Setup

Connect a customer-owned WhatsApp Business Account and phone number to the intended Kravos.ai agent through Meta Embedded Signup. The phone-number destination belongs to that tenant/agent connection; it is not a deployment-wide routing fallback.

Before You Start

The deployment's Meta channels system setting must be enabled to expose Channels setup; sandbox organizations receive feature availability automatically. The switch does not bypass reviewed Embedded Signup or activation requirements. Hiding setup does not stop existing active WhatsApp processing, hide conversation history, block authorized disable/revoke operations, or disable privacy callbacks.

• Use a Meta account authorized to manage the customer's business assets.
• Confirm the business-owned WABA, phone number, registration state, and customer-managed payment readiness.
• Ask the deployment operator to confirm public HTTPS, signed webhook handling, supported Graph version, worker/runtime health, schema readiness, and the exact reviewed Embedded Signup configuration.
• Review the business-specific use case, recipient market, messaging policy, and applicable legal/pilot requirements before production use.

Deployment operators must review consent wording and logging safety before creating a genuine WHATSAPP_SIGNUP_REVIEW attestation. The record must match the deployed app/configuration/origin and Embedded Signup v4 CLOUD_API flow. Never set review flags merely to unblock the interface.

Connect From The Agent

1. Open the intended agent's Channels page and start WhatsApp onboarding.
2. Complete Meta Embedded Signup using the customer's authorized account. Review the consent settings rather than assuming a previously-linked shortcut includes every required asset.
3. Return to the initiating workspace and agent. The server must exchange and validate the authorization result before asset selection is trusted.
4. Select the intended WABA and phone number, then verify the destination and agent before saving.
5. Complete the displayed registration, subscription, payment, and readiness actions. Saving the connection alone does not establish activation.
6. Use authorized development assets for acceptance. Non-role own-asset acceptance and explicit production authorization are separate later gates.

After an SDK loader update, reload setup and start fresh consent. The loader waits for fbAsyncInit; a script load event alone may expose only Meta's buffering stub. Do not reuse an expired attempt or copy callback codes between tabs or agents.

Manual credential setup is an existing controlled compatibility path, not a way around Embedded Signup, provider verification, or production review requirements. Do not create a legacy ChannelConfig to onboard a new customer.

Webhook And Reply Boundary

The public webhook endpoint is:

https://your-web-app.example.com/api/webhooks/whatsapp

The deployment operator registers the verification token and app-level subscription without exposing secret values. Incoming POST requests must pass raw-body signature verification. The signed phone-number destination resolves the connection, and PostgreSQL admission preserves the operation before queue publication.

Supported text and media use the common connection-scoped processing path. The applicable customer-service window and template policy are enforced before dispatch. Unsupported media or a closed messaging window must be handled explicitly, not reported as a successful send.

A successful send response establishes Accepted, not recipient delivery. WhatsApp status callbacks can establish Delivered, Read, or Failed. Duplicate/reordered callbacks must not create another transcript response. An ambiguous dispatch remains Unknown until reconciled; do not blindly retry it.

Verify The Whole Journey

1. Confirm the connection's WABA, phone number, selected agent, and readiness.
2. Send an authorized test message to that phone number and observe the signed inbound operation in the correct conversation.
3. Confirm one logical turn, its canonical reply, and the corresponding outbound intent/provider evidence.
4. Exercise human takeover, supported media, window/template policy, and disconnect/reconnect behavior within the approved test scope.
5. Record customer payment readiness and perform separate non-role own-asset acceptance before production activation.

A webhook challenge or HTTP acknowledgement alone does not prove the reply was generated, dispatched, delivered, or read. Development testers are not a substitute for a non-role customer.

Troubleshooting

• Consent cannot finish: check the exact reviewed app/configuration/origin, attempt expiry, initiating agent, provider asset access, and server-side exchange result. Never print the authorization code or token.
• Connected but not ready: inspect registration, subscription, payment, and credential state independently; do not infer activation from a saved row.
• Inbound not routed: verify the signed phone-number destination and active historical connection. Do not add a global-token fallback.
• No AI reply: inspect conversation assignment, durable operation/recovery state, runtime health, and window policy.
• Unknown send: reconcile the original intent before any retry. Missing receipt is not proof of rejection.
• Deletion request: follow the public Privacy Policy; disconnecting a channel is not data deletion.