360dialog Coexistence Onboarding

360dialog Coexistence Onboarding

Coexistence onboarding connects an existing WhatsApp Business App number to ChatPilot through 360dialog while preserving WhatsApp Business App access.

Sources:

• 360dialog client guide: https://docs.360dialog.com/docs/hub/embedded-signup/coexistence-onboarding
• 360dialog partner guide: https://docs.360dialog.com/partner/onboarding/whatsapp-coexistence
• Coexistence webhook guide: https://docs.360dialog.com/partner/onboarding/whatsapp-coexistence/coexistence-webhooks

API Endpoints

Backend FastAPI endpoints:

| Method | Path | Purpose |

| --- | --- | --- |

| GET | /onboarding/coexistence/eligibility | Checks whether the tenant can start coexistence onboarding. Requires X-Internal-Key and X-Tenant-Id. |

| POST | /onboarding/coexistence/start | Creates an onboarding_sessions row and returns a 360dialog onboarding URL with a secure state token. |

| GET | /onboarding/360/callback | Consumes 360dialog redirect query params, validates state, links channels, and redirects to /onboarding/success. |

| GET | /onboarding/session/{id} | Returns session status and progress stage for polling. |

| POST | /webhooks/360dialog | Receives partner webhook events such as channel creation, channel status changes, and quality changes. |

The legacy singular /webhook/* prefix remains mounted for existing webhook integrations.

Database Schema

Primary tables:

• onboarding_sessions: tenant-scoped session state, secure state_token, external client id, channel payloads, and error details.
• whatsapp_accounts: tenant WhatsApp channel record keyed by 360dialog channel id.
• whatsapp_api_keys: encrypted D360 messaging API key per channel.
• onboarding_webhook_events: idempotent buffer for partner webhooks that arrive before redirect processing.

State flow:

flowchart LR
  A["pending"] --> B["in_progress"]
  B --> C["channel_created"]
  C --> D["activating"]
  D --> E["channel_status = running"]
  E --> F["completed"]
  B --> G["failed"]
  D --> G

Operational Notes

Set these environment variables:

• DIALOG360_ONBOARDING_URL
• DIALOG360_PARTNER_API_KEY or DIALOG360_PARTNER_TOKEN
• DIALOG360_WEBHOOK_SECRET when 360dialog signature validation is enabled
• ONBOARDING_ENCRYPTION_KEY or CREDENTIAL_ENCRYPTION_KEY
• PUBLIC_BASE_URL
• FRONTEND_BASE_URL

API keys are encrypted before persistence. Existing send paths decrypt v1: encrypted tenant keys before calling the 360dialog Messaging API.