vCX WhatsApp Onboarding & Messaging

Base URL - Administration

https://backend.admin.versalence.online/api/v2

All protected endpoints require:

Authorization: Bearer <JWT_TOKEN>

---

1. Authenticate the customer admin

The customer’s admin user logs in with their vCX credentials. The returned JWT is used for all subsequent calls.

POST /api/v2/login
Content-Type: application/json

{
  "email": "admin@customer.com",
  "password": "CustomerAdminPassword"
}

Response:

{
  "success": true,
  "message "Sign-in successful",
  "token": "<JWT_TOKEN>"
}

Notes:

• The user must have email_verified = 'yes'.
• The account must be active.
• The JWT expiry is controlled by the server (JWT_EXPIRES_IN).

---

2. Get Agency Customers

GET /api/admin/v2/getCustomers
Authorization: Bearer <agency-jwt>

Response:

{
  "success": true,
  "message": "Customers retrieved successfully.",
  "data": [
    {
      "uuid": "...",
      "company_name": "...",
      "company_email": "...",
      "company_id": "AGTSW000012026",
      "account_status": "active",
      "parent_agency_uuid": "...",
      "company_member_since": "...",
      "user_name": "...",
      "user_email": "...",
      "user_phone": "...",
      "user_role": "admin",
      "user_status": "active"
    }
  ]
}

2. Login to Sub Account using company_id

GET /api/admin/v2/clientAgentLogin&client_id=<SUB_ACCOUNT_COMPANY_ID>
Authorization: Bearer <agency-owner-jwt>

How it works

1. The agency owner logs in via /api/admin/v2/adminLogin to get their own JWT.
2. They call /api/admin/v2/clientAgentLogin&client_id=<company_id> with that JWT.
3. The backend validates that the requested account is actually a sub-account under the agency.
4. It returns a JWT for the sub-account’s first admin user.

Example

GET /api/admin/v2/clientAgentLogin&client_id=AGTSW000012026
Authorization: Bearer <agency-owner-jwt>

Response:

{
  "success": true,
  "message": "User successfully logged in.",
  "token": "<sub-account-jwt>"
}

Base URL- Backend

https://backend.versalence.online

All protected endpoints require:

Authorization: Bearer <JWT_TOKEN>

---

Check WhatsApp integration status

Use this to decide whether the customer still needs to onboardApp.

GET https://backend.versalence.online/api/v2/getWaba
Authorization: Bearer <JWT_TOKEN>

Not integrated response:

{
  "success": true,
  "message": "no whatsapp data found"
}

Already integrated response:

{
  "success": true,
  "message": "whatsapp data found",
  "data": [
    {
      "app_id": "...",
      "waba_id": "...",
      "access_token": "[hidden]",
 "phone_id": "...",
      "phone_number": "919876543210",
      "display_phone_number": "+91 98765 43210",
      "onboarding_mode": "standard",
      "is_active": true,
      "webhook_status": "subscribed"
    }
  ]
}

---

3. Launch Meta Embedded Signup 

Mobile App Integration Guide — vCX WhatsApp Onboarding & Messaging

TheThis guide is for external mobile appapps initiatesthat embeddedneed signupto **directlyonboard witha Meta**,vCX sub-account onto WhatsApp and send messages through the vCX platform without using vCX’sthe MetavCX Appweb ID.

The typical sequence is:dashboard.

Base URL

https://backend.versalence.online/api/v2

###All 1.protected endpoints require:

Authorization: Bearer <vCX_JWT_TOKEN>

High-level flow

Mobile app           hasvCX vCXbackend              Meta
    App|                     ID|                    configured|
    |-- POST /login ----->|                    |
    |<-- JWT token                                |
    |                     |                    |
    |-- GET /whatsappSignupInit?mode=coexistence ->|
    |<-- { oauth_url }    |                    |
    |                     |                    |
    |-- opens oauth_url in browser -------------->|
    |                     |-- browser loads Meta OAuth --|
    |                     |                    |
    |                     |<-- Meta redirects to /whatsappSignupCallback?code=...&state=...|
    |                     |-- backend exchanges code, sets up WABA, configures webhook |
    |                     |                    |
    |<-- browser redirects to success/failure page |
    |                     |                    |
    |-- GET /whatsappSignupStatus ----------->|
    |<-- { is_connected, waba_id, phone_id }  |
    |                     |                    |
    |-- GET /whatsappApiConfig ------------->|
    |<-- { send_messages_url, message_status_url } |

Endpoints

1. Authenticate the customer admin

POST /api/v2/login
Content-Type: application/json

{
  "email": "admin@customer.com",
  "password": "CustomerAdminPassword"
}

Response:

{
  "success": true,
  "message": "Sign-in successful",
  "token": "<vCX_JWT_TOKEN>"
}

ThisNotes:

is

The user must have a staticverified configemail inand an active account. The user must have role admin to initiate WhatsApp signup. Store the mobileJWT app:and

```javascript
constsend VCX_META_APP_ID = '931735171941134';
const VCX_GRAPH_API_VERSION = 'v20.0';
const REQUIRED_SCOPES = 'whatsapp_business_management';
```

The backend currently does **not** expose an endpoint to provide these values — they must be shared with the external developerit as integrationAuthorization: constants.

Bearer

###<token> on every subsequent request.

---

2. MobileInitiate app launches MetaWhatsApp Embedded Signup

GET /api/v2/whatsappSignupInit?mode=coexistence
Authorization: Bearer <vCX_JWT_TOKEN>

Query parameters:

Using

Meta’sEmbeddedSignupParameter SDKRequired orValues aDefault WebView,Description mode No standard, coexistence standard WhatsApp onboarding mode. Use coexistence if the customer wants to keep their existing WhatsApp Business app loads:running alongside vCX.

Response:

```

{
  "success": true,
  "data": {
    "oauth_url": "https://www.facebook.com/v20.0/dialog/oauth?
  client_id=<VCX_META_APP_ID>
  ...&redirect_uri=<MOBILE_APP_REDIRECT_URI>
  ...&scope=whatsapp_business_management
  &response_type=code
```&state=...",
    "state": "<STATE_TOKEN>",
    "redirect_uri": "https://backend.versalence.online/api/v2/whatsappSignupCallback",
    "scope": "whatsapp_business_management",
    "mode": "coexistence"
  }
}

###Mobile 3.app Useraction: completesOpen setupoauth_url insidein Meta

an

Thein-app user:
- Selectsbrowser or createsWebView. aDo WhatsAppnot Businessextract Account
-or Selectsstore the phoneMeta number
-App Grants permission to vCX’s appID.

###

---

4.

3. Meta redirects back withto a codevCX

After the user completes Meta’s flow, Meta redirects the browser to:

GET https://backend.versalence.online/api/v2/whatsappSignupCallback?code=<META_AUTH_CODE>&state=<STATE_TOKEN>

This endpoint is called by Meta, not by the mobile app. The vCX backend:

Exchanges the code for a Meta access token. Resolves the WABA ID and phone number. Registers the phone number. Configures the vCX webhook. Persists the account. For coexistence mode, requests history and app-state sync.

On success, the browser is redirected to:

https://backend.versalence.online/whatsapp-signup-success

On failure:

https://backend.versalence.online/whatsapp-signup-failure?error=<ERROR_MESSAGE>

These redirect URLs are configurable via environment variables (see below).

---

4. Check WhatsApp signup status

The mobile app should poll this endpoint after the browser is redirected back.

GET /api/v2/whatsappSignupStatus
Authorization: Bearer <vCX_JWT_TOKEN>

Not connected response:

{
  "success": true,
  "message": "No WhatsApp account connected",
  "data": {
    "is_connected": false,
    "onboarding_mode": "standard"
  }
}

Connected response:

{
  "success": true,
  "message": "WhatsApp account connected",
  "data": {
    "is_connected": true,
    "onboarding_mode": "coexistence",
    "is_active": true,
    "waba_id": "...",
    "phone_id": "...",
    "phone_number": "919876543210",
    "display_phone_number": "+91 98765 43210",
    "webhook_subscription_status": "subscribed",
    "expires_in": "...",
    "last_message_at": null,
    "last_smb_message_echo_at": null,
    "last_history_at": null,
    "last_smb_app_state_sync_at": null
  }
}

This endpoint can be queried at any time in the future to check whether WhatsApp is still connected.

---

5. Get messaging API configuration

GET /api/v2/whatsappApiConfig
Authorization: Bearer <vCX_JWT_TOKEN>

Response:

{
  "success": true,
  "data": {
    "send_messages_url": "https://api.versal.one",
    "create_templates_url": "https://api.versal.one",
    "message_status_url": "https://apiproxy.versal.one"
  }
}

Use these endpoints (documented separately) to send messages, create templates, and check message delivery status.

---

6. Existing account lookup (backward-compatible)

GET /api/v2/getWaba
Authorization: Bearer <vCX_JWT_TOKEN>

This existing endpoint continues to work and returns the connected WhatsApp account data. The mobile app may use either /getWaba or /whatsappSignupStatus.

---

Onboarding modes

Standard mode

GET /api/v2/whatsappSignupInit?mode=standard

Uses the Meta Cloud API onboarding. The customer’s WhatsApp Business app will be replaced by vCX for business messaging.

Coexistence mode

GET /api/v2/whatsappSignupInit?mode=coexistence

The customer’s existing WhatsApp Business app continues to work. vCX receives messages through webhooks while the customer keeps using their native WhatsApp Business app. The backend requests smb_app_state_sync and history sync from Meta during onboarding.

---

Environment variables

Add these to the vCX backend .env:

# Backend-driven OAuth signup flow for external mobile apps.
# WHATSAPP_OAUTH_REDIRECT_URI must be registered in the Meta app settings.
WHATSAPP_OAUTH_REDIRECT_URI=https://backend.versalence.online/api/v2/whatsappSignupCallback
WHATSAPP_OAUTH_SUCCESS_REDIRECT=https://backend.versalence.online/whatsapp-signup-success
WHATSAPP_OAUTH_FAILURE_REDIRECT=https://backend.versalence.online/whatsapp-signup-failure

# External WhatsApp messaging API endpoints exposed to mobile apps.
WHATSAPP_SEND_MESSAGES_URL=https://api.versal.one
WHATSAPP_CREATE_TEMPLATES_URL=https://api.versal.one
WHATSAPP_MESSAGE_STATUS_URL=https://apiproxy.versal.one

The following existing variables are also used:

APP_ID=
APP_SECRET=
META_API_VERSION=

---

Prerequisites

The customer account must already exist in vCX (created as a sub-account under the partner’s master account). The customer must have an admin user with verified email and active account status. The WHATSAPP_OAUTH_REDIRECT_URI must be registered in the Meta app settings. Migration 009_add_whatsapp_coexistence_support.sql must be applied to production. It creates the onboarding_sessions and whatsapp_accounts tables required by the new flow.

---

Coexistence with the existing web dashboard flow

The existing web dashboard flow is unchanged and continues to work:

POST /v2/whatsappSign POST /v2/whatsappWaba POST /v2/whatsappPhone POST /v2/embeddedSignup GET /v2/getWaba GET /v2/whatsapp-coexistence/status

The new mobile-app flow is additive:

GET /v2/whatsappSignupInit GET /v2/whatsappSignupCallback GET /v2/whatsappSignupStatus GET /v2/whatsappApiConfig

The removed /v2/whatsapp-coexistence/enable and /v2/whatsapp-coexistence/disable endpoints are no longer needed because the mode is passed directly at signup time.

---

Error handling

Step Typical failure How the mobile app redirectshould URIhandle with:

```
<MOBILE_APP_REDIRECT_URI>?code=<META_AUTH_CODE>
```

###

5.MobileLogin appInvalid sendscredentials theShow codeerror and ask user to vCXretry.

```http
POST

Initiate signup Missing APP_ID /api/v2/whatsappSign
Authorization: Bearer <vCX_JWT>
Content-Type: application/json

{
  "code": "<META_AUTH_CODE>",
  "mode": "coexistence"
}
```

Then continue with `/v2/whatsappWaba` and `/v2/whatsappPhone` using the `session_id`.

---

## Missing piece

There is currently **no vCX backend endpoint** that tells the mobile app:
- What is vCX’s Meta App ID
- What scopes to request
- What redirect URI

Backend misconfiguration. Contact vCX support. Meta OAuth User cancels Browser redirects to usefailure

Sopage. thosePoll /whatsappSignupStatus to confirm not connected.

Callback Invalid/expired state Browser redirects to failure page with error=Invalid or expired onboarding session. Callback Missing WABA or phone number Browser redirects to failure page. User must beretry providedsignup. to theexternalStatus developerpolling out-of-band,is_connected: false Continue polling or yourestart cansignup. add a new endpoint

---

like:

Summary

```http
GETof API endpoints

Endpoint Method Auth Purpose /api/v2/whatsappSignupConfig
Authorization:login BearerPOST <vCX_JWT>
```Public

which

Authenticate returns:and

```json
{
get JWT.

"success": true,
/api/v2/whatsappSignupInit "data":GET {
Admin JWT "app_id": "<APP_ID>",
    "graph_api_version": "v20.0",
    "scope": "whatsapp_business_management"
  }
}
```

Do you want me to add that config endpoint, or will you share the

Get Meta AppOAuth IDURL. directly withthe/api/v2/whatsappSignupCallback externalGET developer?None (Meta calls this) Complete signup after Meta OAuth. /api/v2/whatsappSignupStatus GET Any JWT Check if WhatsApp is connected. /api/v2/whatsappApiConfig GET Any JWT Get messaging API URLs. /api/v2/getWaba GET Any JWT Existing account lookup.

---

6. Complete WhatsApp onboarding on the vCX backend

Use the 3-step onboarding flow (recommended). It supports both standard and coexistence modes and keeps the access token server-side.

Step 6a — Exchange the Meta code for an access token

POST /api/v2/whatsappSign
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "code": "<META_AUTH_CODE>",
  "": "coexistence"
}

Response:

{
  "success": true,
  "message": "Access token updated successfully",
  "session_id": "<SESSION_ID>",
  "mode": "coexistence",
  "data":<ACCESS_TOKEN>"
}

Save session_id and discard data (legacy field).

Step 6b — Resolve WABA ID

POST /api/v2/whatsappWaba
Authorization: Bearer <JWT_TOKEN>
Content-Type:/json

{
  "session_id": "<SESSION_ID>"
}

Response:

{
  "success": true,
  "message": "WABA ID updated successfully",
  "data": {
    "waba_id": "<WABA_ID  },
  "session_id": "<SESSION_ID>"
}

Step 6c — Resolve phone number and complete signup

POST /api/v2/whatsappPhone
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
 session_id": "<SESSION_ID>"
}

Response:

{
  "success": true,
  "message": "Whatsapp embedded signup complete with co-existence mode",
  "mode": "coexistence",
  "phone_number": "876543210",
  "phone_id": "<PHONE_ID>",
  "webhook_config": "Webhook configured successfully"
}

At this point the backend has:

• Registered the phone number with Meta.
• Configured the vCX webhook.
• Persisted WABA, phone ID, and access token.
• For Coexistence mode, requested history and app-state sync from Meta.

Role requirement: Admin only for all three steps.

---

7. Verify onboarding completed

Call the status endpoint again:

http GET /api/v2/getWaba Authorization: Bearer ```

Confirm is_active is true and webhook_subscription_status is subscribed.

---

8. Send messages via vCX

Once is complete, use the separately documented messaging API to send WhatsApp messages through the vCX platform.

The backend stores the access token and phone ID, so the send-message API only needs the vCX customer JWT (and the recipient/message payload---

Prerequisites

1. The customer account must already exist in vCX (created as a sub-account under the partner’s master account via the admin/partner flow).
2. The customer must have an admin user with verified email and active account status. 3 The mobile app must be able to launch Meta Embedded Signup using vCX’s Meta App ID.
3. Coexistence mode must be enabled before the 3-step onboarding if that mode is desired.

---

Role requirements summary

| Endpoint | Required role|----------|---------------| | POST /v2/login | Any user | | GET /v2/getWaba | Any authenticated user | | GET /v2/whatsapp-coexistence/status | Admin | | POST /v/whatsapp-coexistence/enable | Admin | | POST /v2/whatsappSign | Admin | | POST /v2/whatsappWaba | Admin | | POST /v2/whatsappPhone | Admin |

---

Important notes

• Legacy endpoint POST /api/v2/embeddedSignup exists as a single-call onboarding flow, but it always uses standard mode** and does not support Coexistence. Use the 3-step flow above for Coexistence.
• **Token storage The 3-step flow uses session_id to keep the Meta access token server-side. The mobile app only needs to store the vCX JWT.
• No login to vCX web UI required: The mobile app can perform the entire flow via these API calls.

Let me know if you want me to save this as a file in the repo (e.g., docs/mobile-app-whatsapp-integration.md).