Installation

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

Path	Cache	Use for
`…/embedded-signup/v1/sdk.js`	5 min, revalidated	Floating — auto-picks the latest `1.x` release
`…/embedded-signup/v1.0.5/sdk.js`	1 year, immutable	Pinned — recommended for production

import {
  GatewayEmbeddedSignup,
  GatewayTheme,
} from '@connexease/gateway-embedded-signup';

Render the connect button and launch the WhatsApp Business onboarding flow in a few lines of code. This is the whole frontend integration: call init() once, then call launch() from your button’s click handler. The only server-side piece you need is the /api/session proxy.

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

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

<script>
  window.addEventListener('DOMContentLoaded', () => {
    // Keep false in production. Enable only while developing.
    const SDK_DEBUG = false;

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

      // Optional. Omit this property to use the default Connexease API URL.
      // Provide only the base URL; the SDK appends the required endpoint paths.
      apiBaseUrl: 'https://your-gateway-api.example.com',

      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: true,
        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>

Browser Security Headers

Meta Embedded Signup uses an OAuth popup and a cross-origin relay iframe.
If your application configures CSP or COOP headers, apply the following
requirements before launching the SDK.

Cross-Origin-Opener-Policy

Do not serve the page with:

Cross-Origin-Opener-Policy: same-origin

Use:

Cross-Origin-Opener-Policy: same-origin-allow-popups

Content Security Policy

Add the following origins to your existing CSP directives:

script-src https://d38joj22zi0xe8.cloudfront.net https://connect.facebook.net;
connect-src https://public-api.gateway.connexease.com https://graph.facebook.com;
frame-src https://www.facebook.com https://web.facebook.com https://m.facebook.com https://staticxx.facebook.com;
img-src data: https://*.fbsbx.com https://platform-lookaside.fbsbx.com;
style-src 'unsafe-inline';

Do not replace your application’s existing CSP directives. Append these origins to the existing values. Replacing them may break payment, CAPTCHA, analytics, or other application frames.

Enable debug: true while testing.

fb_login_timeout: Meta’s FB.login callback did not return within 15 minutes. Check the page’s Cross-Origin-Opener-Policy header.
meta_finish_timeout: The OAuth callback returned, but Meta did not send the terminal Embedded Signup message within 60 seconds. Check frame-src and the Meta message diagnostics.

apiBaseUrl is optional. When it is provided, the SDK uses it as the base URL for its Embedded Signup API requests. When it is omitted, the existing default Connexease API URLs continue to be used.Provide only the base URL, such as https://your-gateway-api.example.com. Do not append /api/v1/wa/embedded-signup because the SDK adds the required paths automatically.

Never expose your secret key in frontend code or pass it to launch() in a production integration. The sk_… key must stay on your server and should only be used by your /api/session backend endpoint.

With debug: true, the SDK logs each internal step event of the flow to the browser console so you can watch it progress while developing. It does not log the final result by itself.The onSuccess, onError, and onCancel callbacks continue to run when debug is false. If your callback code writes its payload to the console, guard that console statement with the same debug flag.Keep debug logging disabled in production.

Looking for framework-specific setups? See Framework Examples for Vanilla JS, React / Next.js, and Vue.js.

The only server-side piece you need is the /api/session proxy — see Backend Integration.

Getting Started

Guides

Browser Security Headers

Cross-Origin-Opener-Policy

Content Security Policy

​Browser Security Headers

​Cross-Origin-Opener-Policy

​Content Security Policy

​Popup Troubleshooting

Browser Security Headers

Cross-Origin-Opener-Policy

Content Security Policy

Popup Troubleshooting