vCX WhatsApp Onboarding & Messaging

~~Here is the integration documentation for the external mobile app, based on the endpoints actually present in the backend.~~

> **Note on base path:** The routes in this backend are mounted at `/api/v2`, not `/api/admin/v2`. The `/api/admin/v2/*` paths you referenced proxy to a separate admin service. The mobile-app flow below uses the customer-facing API at `/api/v2`.

~~---~~

~~# Mobile App Integration Guide — vCX WhatsApp Onboarding & Messaging~~

Base URL

~~```~~

https://<your-backend>/backend.admin.versalence.online/api/v2
```

All protected endpoints require:

~~```http~~

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.

~~```http~~

POST /api/v2/login

Content-Type: application/json

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

Response:

~~```json~~

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

}
```

Notes:

~~**Notes:**~~
-

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

~~---~~

2. Check WhatsApp integration status

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

~~```http~~

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

Authorization: Bearer <JWT_TOKEN>
```

**Not integrated response:**

~~```json~~

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

}
```

**Already integrated response:**

~~```json~~

{
 
  "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. Check Coexistence status (optional)

If the partner wants the customer to use ~~**Coexistence**~~Coexistence mode (so the customer’s existing WhatsApp Business app keeps working alongside vCX), check the feature flag first.

~~```http~~

GET /api/v2/whatsapp-coexistence/status

Authorization: Bearer <JWT>
```

Response:

~~```json~~

{
 
  "success": true,
 
  "data": {
 
    "uuid": "...",
 
    "coexistence_enabled": false,
 
    "onboarding_mode": "standard",
 
    "is_active": false,
 
    "waba_id": null    "phone_id": null
 
  }

}
```

**Role requirement:** Admin only.

~~---~~

4. Enable Coexistence mode

If the customer wants Coexistence onboarding, enable the feature flag ~~**before**~~before running embedded signup.

~~```http~~

 /api/v2/whatsapp-coexistence/enable

Authorization: Bearer <JWT_TOKEN>

Content-Type: application/json

{
"enabled": true
}
~~```~~

Response:

~~```json~~

{
 
  "success": true,
 
  "message": "Coexist enabled for tenant"

}
```

**Role requirement:** Admin only.

~~---~~

5. Launch Meta Embedded Signup from the mobile app

The mobile app must open Meta’s Embedded Signup flow using the **vCX Meta App ID**ID. The recommended implementation is- Open a WebView / in-app browser.
-

Load the Meta Embedded Signup SDK configured with vCX’s ~~`APP_ID`~~APP_ID.
- Request the ~~`whatsapp_business_management`~~whatsapp_business_management permission.
- Ask the user to select or create a WhatsApp Business Account and phone number.
- Meta will redirect back the app with an **authorization `code`**code.

Keep that ~~`code`~~code — you will send it to the vCX backend in the next step.

> The backend uses ~~`APP_ID`~~APP_ID and ~~`APP_SECRET`~~APP_SECRET to exchange the code for a long-lived access, so the mobile app never needs to store Meta credentials.

~~---~~

6. Complete WhatsApp onboarding on the vCX backend

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

~~###~~

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

~~```http~~

POST /api/v2/whatsappSign

Authorization: Bearer <JWT_TOKEN>

Content-Type: application/json

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

Response:

~~```json~~

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

}
```

Save ~~`session_id`~~session_id and discard ~~`data`~~data (legacy field).

~~###~~

Step 6b — Resolve WABA ID

~~```http~~

POST /api/v2/whatsappWaba

Authorization: Bearer <JWT_TOKEN>

Content-Type:/json

{
"session_id": "<SESSION_ID>"
}
~~```~~

Response:

~~```json~~

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

}
```

~~###~~

Step 6c — Resolve phone number and complete signup

~~```http~~

POST /api/v2/whatsappPhone

Authorization: Bearer <JWT_TOKEN>

Content-Type: application/json

{
session_id": "<SESSION_ID>"
}
~~```~~

Response:

~~```json~~

{
 
  "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 ~~<JWT_TOKEN>~~
```

Confirm ~~`is_active`~~is_active is ~~`true`~~true and ~~`webhook_subscription_status`~~webhook_subscription_status is ~~`subscribed`~~subscribed.

~~---~~

8. Send messages via vCX

Once is complete, use the **separately documented messaging API**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

~~Prerequisites~~

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.
4. Coexistence mode must be enabled before the 3-step onboarding if that mode is desired.

~~---~~

Role requirements summary

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

~~---~~

Important notes

**Legacy endpoint `POST /api/v2/embeddedSignup`embeddedSignup exists as a single-call onboarding flow, but it **always uses ~~`standard`~~standard mode** and does not support Coexistence. Use the 3-step flow above for Coexistence.
- **Token storage The 3-step flow uses ~~`session_id`~~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`md).