Skip to main content

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

    The agency owner logs in via /api/admin/v2/adminLogin to get their own JWT. They call /api/admin/v2/clientAgentLogin&client_id=<company_id> with that JWT. The backend validates that the requested account is actually a sub-account under the agency. 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. Check Coexistence status (optional)

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

    GET /api/v2/whatsapp-coexistence/status
Authorization: Bearer <JWT>

    Response:

    {
  "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 running embedded signup.

     /api/v2/whatsapp-coexistence/enable
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "enabled": true
}

    Response:

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

    Role requirement: Admin only.

    5. Launch Meta Embedded Signup from the mobile app

    The mobile app initiates embedded signup **directly with Meta**, using vCX’s Meta App ID.

    The typical sequence is:

    ### 1. Mobile app has vCX Meta App ID configured

    This is a static config in the mobile app:

    ```javascript
    const 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 openbe shared with the external developer as integration constants.

    ### 2. Mobile app launches Meta Embedded Signup

    Using Meta’s Embedded Signup flowSDK usingor a WebView, the vCXapp loads:

    ```
    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
    ```

    ### 3. User completes setup inside Meta

    App ID.

    The recommendeduser:
    - implementation is- Open a WebView / in-app browser.

      Load the Meta Embedded Signup SDK configured with vCX’s APP_ID. Request the whatsapp_business_management permission. Ask the user to selectSelects or createcreates a WhatsApp Business Account
      - andSelects the phone number.number
      - Grants permission to vCX’s app

      ### 4. Meta will redirectredirects back the app with an authorization code.

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

      The backend uses APP_ID and APP_SECRET to exchange the code for a long-livedcode

      access,

      Meta soredirects to the mobile app neverredirect needsURI with:

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

      ### 5. Mobile app sends the code to storevCX

      ```http
      POST /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 credentials.App ID
      - What scopes to request
      - What redirect URI to use

      So those must be provided to the external developer out-of-band, or you can add a new endpoint like:

      ```http
      GET /api/v2/whatsappSignupConfig
      Authorization: Bearer <vCX_JWT>
      ```

      which returns:

      ```json
      {
        "success": true,
        "data": {
          "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 Meta App ID directly with the external developer?

      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).

      Back to top