Embed the GetVoiceBot app

Authenticate a reseller customer from your backend and open the GetVoiceBot application in an iframe.

Eligible resellers can embed the GetVoiceBot application inside their own product. Your backend identifies
the customer and user, requests a one-time GetVoiceBot authentication token, and returns that short-lived
token to your frontend. Your frontend opens /app/embed on your GetVoiceBot domain.

Never put a long-lived GetVoiceBot API token in frontend code, an iframe URL, or browser storage. Generate
one-time user authentication tokens only from an authenticated backend you control.

Before you begin

You need:

• an eligible GetVoiceBot reseller account;
• a GetVoiceBot domain, such as agents.example.com;
• a trusted mapping between each customer in your system and its GetVoiceBot organization;
• a backend that can authenticate the current user and call the GetVoiceBot API.

If your account does not manage downstream organizations, use the normal GetVoiceBot application rather
than creating an unnecessary reseller hierarchy.

1. Resolve the customer organization

Store the GetVoiceBot organization ID when you create a customer. Also send your own stable
externalAccountId so the organization can be reconciled later.

• Create a customer organization with the documented Organizations API.
• Resolve an existing customer through GET /api/v2/getAccountByExternalId when you have its
  external ID.

Confirm the returned organization belongs to the authenticated reseller before issuing user access.

2. Generate a one-time authentication token

From your backend, call:

GET /api/v2/auth/account/oneTimeAuthToken

Supply the user's email and, when needed, the customer organization's externalAccountId. If the
email is not already a member and the external organization is valid, GetVoiceBot can create the member
without sending an invitation email.

The response includes authToken and the authenticated account ID. Return the one-time token to
your frontend only after verifying the current user belongs to that customer in your system.

3. Build the iframe URL

Use /app/embed on your GetVoiceBot or white-label domain:

const url = new URL("https://agents.example.com/app/embed");
url.searchParams.set("authToken", oneTimeAuthToken);
url.searchParams.set("email", currentUser.email);

The email must match the GetVoiceBot account authenticated by the token. Use URL and searchParams
instead of concatenating unescaped query strings.

Render the result:

<iframe
  src="https://agents.example.com/app/embed?authToken=ONE_TIME_TOKEN&email=user%40example.com"
  title="GetVoiceBot"
  allow="camera; microphone"
  style="width: 100%; height: 100vh; border: 0"
></iframe>

An end-to-end example is available in the
GetVoiceBot app embed demo.

Optional destination and onboarding values

redirectUrl can select a destination inside the same embedded GetVoiceBot application. Supply a
URL-encoded /app/... destination; external origins and another /app/embed loader are rejected.

For new organizations, you may preselect a template and prefill onboarding:

Prefilling a value does not automatically skip its step. Unknown or unavailable values may be
ignored. Treat onboarding query values as draft inputs, then read and verify the resulting
organization and Agent configuration.

Production checklist

• Verify the signed-in user-to-customer mapping on every token request.
• Keep the GetVoiceBot API token server-side.
• Use HTTPS for your product and GetVoiceBot domain.
• Confirm the iframe host's Content Security Policy permits the GetVoiceBot domain.
• Test login, logout, account switching, microphone permission, onboarding, and deep links.
• Do not reuse or cache one-time authentication tokens.

For API-managed domains and the full backend sequence, see
White-label domains and embedded access.