Widget Token Endpoint | Zentrix Agent Studio Docs

The widget token endpoint generates a short-lived access token that authorizes a browser-based voice call with your AI agent. Use this endpoint from your backend server to obtain a token, then pass it to the Voice Web SDK on the client side to initiate the call.

Endpoint

POST /api/widget/token

Request Headers

Header	Value	Required
`Authorization`	`Bearer nas_your_api_key`	Yes
`Content-Type`	`application/json`	Yes

Request Body

json

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "instanceId": "660f9500-f30c-52e5-b827-557766551111",
  "language": "en",
  "callerName": "Rahul Sharma"
}

Field	Type	Required	Description
`agentId`	string (UUID)	Yes	The ID of the agent template from the catalog
`instanceId`	string (UUID)	No	Specific customer agent instance ID. If provided, instance-specific variables (company name, persona, custom instructions) are injected into the agent prompt
`language`	string	No	Language for the call. Options: `en` (English), `hi` (Hindi), `mr` (Marathi), `auto` (automatic detection). Default: `en`
`callerName`	string	No	Name of the caller, used by the agent in conversation (e.g., "Hello, Rahul!")

Response

json

{
  "accessToken": "rt_live_abc123def456...",
  "callId": "call_789xyz...",
  "agentName": "Customer Support Agent"
}

Field	Type	Description
`accessToken`	string	Short-lived token for the Voice Web SDK (valid for ~60 seconds)
`callId`	string	Unique identifier for this call session, used for tracking in call logs
`agentName`	string	Display name of the agent for UI purposes

Error Responses

Status	Error	Cause
`401`	Invalid API key	Missing or invalid `Authorization` header
`404`	Agent not found	The `agentId` does not exist or is inactive
`403`	Subscription inactive	Trial expired or subscription cancelled
`500`	Voice platform error	Failed to create web call session

Full Integration Example

Server side (Node.js / Next.js API route):

javascript

// Your backend endpoint that your frontend calls
export async function POST(request) {
  const { agentId, callerName } = await request.json();

  const tokenResponse = await fetch(
    'https://agentstudio.brtneura.com/api/widget/token',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.NEURA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ agentId, callerName }),
    }
  );

  const data = await tokenResponse.json();
  return Response.json(data);
}

Client side (browser):

javascript

import { ZentrixVoiceClient } from 'zentrix-voice-sdk';

const voiceClient = new ZentrixVoiceClient();

async function startCall() {
  // Get token from your backend
  const res = await fetch('/api/start-call', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agentId: 'your-agent-uuid',
      callerName: 'Website Visitor',
    }),
  });
  const { accessToken } = await res.json();

  // Start the WebRTC call
  await voiceClient.startCall({ accessToken });

  voiceClient.on('call_started', () => {
    console.log('Call connected');
  });

  voiceClient.on('call_ended', () => {
    console.log('Call ended');
  });
}

Tip

Tip: The access token expires quickly (approximately 60 seconds). Generate it on demand when the user clicks the call button -- do not pre-fetch tokens.

Instance-Specific Variables

When you pass an instanceId, the agent prompt is dynamically enriched with:

Company name from the customer's instance configuration
Persona name (e.g., "Priya" or "Arjun") set during the setup wizard
Custom greeting tailored to the business
Custom instructions specific to that customer's workflow
Knowledge base content uploaded by the customer

This means the same agent template can serve hundreds of different businesses, each with its own personalized experience. See Agent Setup Wizard for how these variables are configured.

A Product by BRTNeura Technology LLP

← Previous

Authentication

Webhooks

Last updated: 2026-03-05

Endpoint

POST /api/widget/token

Request Headers

Header	Value	Required
`Authorization`	`Bearer nas_your_api_key`	Yes
`Content-Type`	`application/json`	Yes

Request Body

json

{
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "instanceId": "660f9500-f30c-52e5-b827-557766551111",
  "language": "en",
  "callerName": "Rahul Sharma"
}

Field	Type	Required	Description
`agentId`	string (UUID)	Yes	The ID of the agent template from the catalog
`instanceId`	string (UUID)	No	Specific customer agent instance ID. If provided, instance-specific variables (company name, persona, custom instructions) are injected into the agent prompt
`language`	string	No	Language for the call. Options: `en` (English), `hi` (Hindi), `mr` (Marathi), `auto` (automatic detection). Default: `en`
`callerName`	string	No	Name of the caller, used by the agent in conversation (e.g., "Hello, Rahul!")

Response

json

{
  "accessToken": "rt_live_abc123def456...",
  "callId": "call_789xyz...",
  "agentName": "Customer Support Agent"
}

Field	Type	Description
`accessToken`	string	Short-lived token for the Voice Web SDK (valid for ~60 seconds)
`callId`	string	Unique identifier for this call session, used for tracking in call logs
`agentName`	string	Display name of the agent for UI purposes

Error Responses

Status	Error	Cause
`401`	Invalid API key	Missing or invalid `Authorization` header
`404`	Agent not found	The `agentId` does not exist or is inactive
`403`	Subscription inactive	Trial expired or subscription cancelled
`500`	Voice platform error	Failed to create web call session

Full Integration Example

Server side (Node.js / Next.js API route):

javascript

// Your backend endpoint that your frontend calls
export async function POST(request) {
  const { agentId, callerName } = await request.json();

  const tokenResponse = await fetch(
    'https://agentstudio.brtneura.com/api/widget/token',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.NEURA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ agentId, callerName }),
    }
  );

  const data = await tokenResponse.json();
  return Response.json(data);
}

Client side (browser):

javascript

import { ZentrixVoiceClient } from 'zentrix-voice-sdk';

const voiceClient = new ZentrixVoiceClient();

async function startCall() {
  // Get token from your backend
  const res = await fetch('/api/start-call', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agentId: 'your-agent-uuid',
      callerName: 'Website Visitor',
    }),
  });
  const { accessToken } = await res.json();

  // Start the WebRTC call
  await voiceClient.startCall({ accessToken });

  voiceClient.on('call_started', () => {
    console.log('Call connected');
  });

  voiceClient.on('call_ended', () => {
    console.log('Call ended');
  });
}

Tip

Tip: The access token expires quickly (approximately 60 seconds). Generate it on demand when the user clicks the call button -- do not pre-fetch tokens.

Instance-Specific Variables

When you pass an instanceId, the agent prompt is dynamically enriched with:

Company name from the customer's instance configuration
Persona name (e.g., "Priya" or "Arjun") set during the setup wizard
Custom greeting tailored to the business
Custom instructions specific to that customer's workflow
Knowledge base content uploaded by the customer

This means the same agent template can serve hundreds of different businesses, each with its own personalized experience. See Agent Setup Wizard for how these variables are configured.

A Product by BRTNeura Technology LLP

← Previous

Authentication

Webhooks

Last updated: 2026-03-05