Framework Examples

Copy-pasteable setups for the most common frameworks. Each one installs the SDK and launches the flow; the /api/session endpoint is covered in Backend Integration.

These examples use a shared SDK_DEBUG flag for the SDK’s internal development logs and the console statements inside the callbacks.The onSuccess, onError, and onCancel callbacks continue to run when debug logging is disabled. Only the example’s console output is skipped. Keep the debug flag set to false in production.

The optional apiBaseUrl setting lets you dynamically select the Gateway API environment. Provide only the base URL, such as https://your-gateway-api.example.com.When it is omitted, the SDK continues using the existing default Connexease production API.

Before testing Meta Embedded Signup, configure the required CSP and COOP response headers. In particular, do not use Cross-Origin-Opener-Policy: same-origin; use same-origin-allow-popups.See Browser Security Headers.

React / Next.js
Vue.js
Vanilla JS

'use client';

import { useEffect, useRef, useState } from 'react';
import {
  GatewayEmbeddedSignup,
  GatewayTheme,
} from '@connexease/gateway-embedded-signup';
import type {
  GatewayEmbeddedSignupInstance,
} from '@connexease/gateway-embedded-signup';

const SDK_DEBUG =
  process.env.NEXT_PUBLIC_GATEWAY_DEBUG === 'true';

export function ConnectButton() {
  const widgetRef =
    useRef<GatewayEmbeddedSignupInstance | null>(null);

  const [loading, setLoading] = useState(false);

  useEffect(() => {
    const apiBaseUrl =
      process.env.NEXT_PUBLIC_GATEWAY_API_BASE_URL;

    widgetRef.current = GatewayEmbeddedSignup.init({
      publishableKey:
        process.env.NEXT_PUBLIC_GATEWAY_PUBLISHABLE_KEY!,

      // Optional. Omit it to use the default Connexease API.
      ...(apiBaseUrl ? { apiBaseUrl } : {}),

      theme: GatewayTheme.Blue,
      logoUrl: 'https://yourapp.com/logo.png',
      debug: SDK_DEBUG,
    });

    return () => {
      widgetRef.current?.destroy();
      widgetRef.current = null;
    };
  }, []);

  const handleClick = async () => {
    if (!widgetRef.current || loading) return;

    setLoading(true);

    try {
      await widgetRef.current.launch({
        fetchSessionToken: async () => {
          const res = await fetch('/api/session', {
            method: 'POST',
          });

          if (!res.ok) {
            throw new Error('Failed to fetch session');
          }

          return res.json();
        },

        isCoexistence: false,

        onSuccess: (result) => {
          if (SDK_DEBUG) {
            console.log(
              'WhatsApp Business connected:',
              result,
            );
          }

          // Save the connected account or update your UI here.
        },

        onError: (error) => {
          if (SDK_DEBUG) {
            console.error(
              'Embedded Signup failed:',
              error,
            );
          }

          // Handle the error in your application here.
        },

        onCancel: (info) => {
          if (SDK_DEBUG) {
            console.warn(
              'Embedded Signup canceled:',
              info,
            );
          }

          // Handle the cancellation in your application here.
        },
      });
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClick} disabled={loading}>
      {loading
        ? 'Connecting…'
        : 'Connect WhatsApp Business'}
    </button>
  );
}

<template>
  <button @click="handleClick" :disabled="loading">
    {{ loading
      ? 'Connecting…'
      : 'Connect WhatsApp Business' }}
  </button>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import {
  GatewayEmbeddedSignup,
  GatewayTheme,
} from '@connexease/gateway-embedded-signup';
import type {
  GatewayEmbeddedSignupInstance,
} from '@connexease/gateway-embedded-signup';

const SDK_DEBUG =
  import.meta.env.VITE_GATEWAY_DEBUG === 'true';

const loading = ref(false);
let widget: GatewayEmbeddedSignupInstance | null = null;

onMounted(() => {
  const apiBaseUrl =
    import.meta.env.VITE_GATEWAY_API_BASE_URL;

  widget = GatewayEmbeddedSignup.init({
    publishableKey:
      import.meta.env.VITE_GATEWAY_PUBLISHABLE_KEY,

    // Optional. Omit it to use the default Connexease API.
    ...(apiBaseUrl ? { apiBaseUrl } : {}),

    theme: GatewayTheme.Blue,
    logoUrl: 'https://yourapp.com/logo.png',
    debug: SDK_DEBUG,
  });
});

onUnmounted(() => {
  widget?.destroy();
  widget = null;
});

async function handleClick() {
  if (!widget || loading.value) return;

  loading.value = true;

  try {
    await widget.launch({
      fetchSessionToken: async () => {
        const res = await fetch('/api/session', {
          method: 'POST',
        });

        if (!res.ok) {
          throw new Error('Failed to fetch session');
        }

        return res.json();
      },

      isCoexistence: false,

      onSuccess: (result) => {
        if (SDK_DEBUG) {
          console.log(
            'WhatsApp Business connected:',
            result,
          );
        }

        // Save the connected account or update your UI here.
      },

      onError: (error) => {
        if (SDK_DEBUG) {
          console.error(
            'Embedded Signup failed:',
            error,
          );
        }

        // Handle the error in your application here.
      },

      onCancel: (info) => {
        if (SDK_DEBUG) {
          console.warn(
            'Embedded Signup canceled:',
            info,
          );
        }

        // Handle the cancellation in your application here.
      },
    });
  } finally {
    loading.value = false;
  }
}
</script>

<button id="connect-btn">
  Connect WhatsApp Business
</button>

<script>
  // Optional runtime configuration.
  // Remove this value to use the default Connexease API.
  window.GATEWAY_API_BASE_URL =
    'https://your-gateway-api.example.com';

  // Keep false in production.
  window.GATEWAY_DEBUG = false;
</script>

<script
  src="https://d38joj22zi0xe8.cloudfront.net/embedded-signup/v1.0.3/sdk.js"
  defer
></script>

<script>
  window.addEventListener('DOMContentLoaded', () => {
    const apiBaseUrl =
      window.GATEWAY_API_BASE_URL;

    const SDK_DEBUG =
      window.GATEWAY_DEBUG === true;

    const widget =
      window.GatewayEmbeddedSignup.init({
        publishableKey:
          'pb_xxxxxxxxxxxxxxxxxxxxxx',

        // Optional. Omit it to use the default Connexease API.
        ...(apiBaseUrl ? { apiBaseUrl } : {}),

        theme: 'blue',
        logoUrl: 'https://yourapp.com/logo.png',
        debug: SDK_DEBUG,
      });

    document
      .getElementById('connect-btn')
      .addEventListener('click', () => {
        widget.launch({
          fetchSessionToken: async () => {
            const res = await fetch('/api/session', {
              method: 'POST',
            });

            if (!res.ok) {
              throw new Error(
                'Failed to fetch session',
              );
            }

            return res.json();
          },

          isCoexistence: false,

          onSuccess: (result) => {
            if (SDK_DEBUG) {
              console.log(
                'WhatsApp Business connected:',
                result,
              );
            }

            // Save the connected account or update your UI here.
          },

          onError: (error) => {
            if (SDK_DEBUG) {
              console.error(
                'Embedded Signup failed:',
                error,
              );
            }

            // Handle the error in your application here.
          },

          onCancel: (info) => {
            if (SDK_DEBUG) {
              console.warn(
                'Embedded Signup canceled:',
                info,
              );
            }

            // Handle the cancellation in your application here.
          },
        });
      });
  });
</script>

Next.js Backend Route

The following Route Handler can be used as the /api/session endpoint for the React / Next.js example:

const CONNEXEASE_SECRET_KEY =
  process.env.GATEWAY_SECRET_KEY;

const CONNEXEASE_API_BASE = (
  process.env.GATEWAY_CORE_API_URL ??
  'https://public-api.gateway.connexease.com'
).replace(/\/+$/, '');

const SESSIONS_API =
  `${CONNEXEASE_API_BASE}/api/v1/wa/embedded-signup/sessions`;

export async function POST() {
  if (!CONNEXEASE_SECRET_KEY) {
    return Response.json(
      {
        error: 'GATEWAY_SECRET_KEY is not configured',
      },
      { status: 500 },
    );
  }

  try {
    const res = await fetch(SESSIONS_API, {
      method: 'POST',
      headers: {
        'Authorization':
          `Bearer ${CONNEXEASE_SECRET_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
    });

    const data = (await res.json()) as {
      data?: Record<string, unknown>;
      [key: string]: unknown;
    };

    if (!res.ok) {
      return Response.json(data, {
        status: res.status,
      });
    }

    // Connexease wraps the payload as:
    // { data: {...}, isSuccess: true }
    //
    // fetchSessionToken must receive the inner object.
    return Response.json(data.data ?? data);
  } catch {
    return Response.json(
      { error: 'Failed to fetch session' },
      { status: 500 },
    );
  }
}

.env:

# React / Next.js frontend
NEXT_PUBLIC_GATEWAY_PUBLISHABLE_KEY=pb_xxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_GATEWAY_API_BASE_URL=https://your-gateway-api.example.com
NEXT_PUBLIC_GATEWAY_DEBUG=false

# Vue.js frontend
VITE_GATEWAY_PUBLISHABLE_KEY=pb_xxxxxxxxxxxxxxxxxxxxxx
VITE_GATEWAY_API_BASE_URL=https://your-gateway-api.example.com
VITE_GATEWAY_DEBUG=false

# Server-side session proxy
GATEWAY_SECRET_KEY=sk_xxxxxxxxxxxxxxxxxxxxxx
GATEWAY_CORE_API_URL=https://your-gateway-api.example.com

Use only the frontend variables for your framework. A React / Next.js application uses the NEXT_PUBLIC_ variables, while a Vue / Vite application uses the VITE_ variables.NEXT_PUBLIC_GATEWAY_API_BASE_URL, VITE_GATEWAY_API_BASE_URL, and GATEWAY_CORE_API_URL are optional. If they are omitted, the existing Connexease production API continues to be used.

NEXT_PUBLIC_GATEWAY_DEBUG and VITE_GATEWAY_DEBUG control the SDK’s internal development logs and the guarded callback console statements shown in these examples.The callbacks themselves continue to run when these values are false. Keep debug logging disabled in production.

The frontend API base URL and the server-side GATEWAY_CORE_API_URL should point to the same Gateway environment.Provide only the base URL. Do not append /api/v1/wa/embedded-signup or an individual endpoint path.

Only NEXT_PUBLIC_ and VITE_ variables are exposed to the browser. Never give the secret key one of these prefixes.GATEWAY_SECRET_KEY has no public prefix, so it stays server-side in the Route Handler. Never pass it to launch() in a production integration.

Public frontend environment values are usually included in the application during build or dev-server startup. If you add or change one, restart the dev server or rebuild the application.

Getting Started

Guides

Next.js Backend Route

​Next.js Backend Route

Next.js Backend Route