API Reference

Complete API documentation for the Traise Widget, including all methods, events, and types.

Core API Methods

Initialization

init(config)

Initializes the widget with configuration options.

Parameters:

• config (object): Configuration options

Returns:

• Promise (TraiseWidgetAPI) - Widget instance

Example:

const { init, show, getStatus } = window.TraiseWidget;

const widget = await init({
  apiKey: 'your-api-key',
  mode: 'light',
  position: 'bottom-right'
});

if (getStatus().initialized) {
  show();
}

Widget Control

show()

Shows the widget interface.

Returns: TraiseWidgetAPI

const { show } = window.TraiseWidget;
show();

hide()

Hides the widget interface.

Returns: TraiseWidgetAPI

const { hide } = window.TraiseWidget;
hide();

destroy()

Destroys the widget and cleans up resources.

Returns: void

const { destroy } = window.TraiseWidget;
destroy();

retry()

Retries initialization after a failure.

Returns: Promise<TraiseWidgetAPI>

const { retry } = window.TraiseWidget;
await retry();

recordIncomingCall(contact)

Records an incoming call in the widget's history.

Parameters:

• contact (ClientData): Contact information from the incoming call

Returns: void

Voice Calling

makeCall(target)

Initiates a voice call.

Parameters:

• target: Phone number (string) or client object

Returns: Promise (void)

const { makeCall } = window.TraiseWidget;

// Simple phone number
await makeCall('+1234567890');

// With client object (recommended)
await makeCall({
  name: 'John Doe',
  phoneNumber: '+1234567890'
});

endCall()

Ends the current active call.

Returns: void

const { endCall } = window.TraiseWidget;
endCall();

SMS Messaging

sendMessage(phoneNumber, message)

Sends an SMS message.

Parameters:

• phoneNumber (string): Recipient's phone number
• message (string): Message text

Returns: Promise (void)

const { sendMessage } = window.TraiseWidget;
await sendMessage('+1234567890', 'Hello from Traise!');

Client Management

loadClient(clientData) / setClient(clientData)

Loads client information into the widget.

Parameters:

• clientData (object): Client information

Returns: TraiseWidgetAPI

const { loadClient } = window.TraiseWidget;

loadClient({
  name: 'John Smith',
  phoneNumber: '+1234567890',
  email: '[email protected]'
});

getClient()

Gets the currently loaded client.

Returns: ClientData | null

const { getClient } = window.TraiseWidget;
const client = getClient();

unloadClient()

Removes client information.

Returns: TraiseWidgetAPI

const { unloadClient } = window.TraiseWidget;
unloadClient();

Configuration

getConfig()

Gets current configuration.

Returns: WidgetConfig

const { getConfig } = window.TraiseWidget;
const config = getConfig();

updateConfig(updates)

Updates configuration dynamically.

Parameters:

• updates (Partial WidgetConfig): Configuration updates

Returns: TraiseWidgetAPI

const { updateConfig } = window.TraiseWidget;
updateConfig({
  mode: 'dark',
  position: 'top-left'
});

getStatus()

Gets widget status information.

Returns: WidgetStatus

const { getStatus } = window.TraiseWidget;
const status = getStatus();
// {
//   initialized: true,
//   visible: true,
//   websocket: true,
//   voice: true,
//   activeCall: false,
//   unreadMessages: 0
// }

Complete Example

async function setupWidget() {
  const { init, show, on, loadClient, makeCall, sendMessage, getStatus, destroy } = window.TraiseWidget;

  // Initialize
  const widget = await init({
    apiKey: 'your-api-key',
    mode: 'light',
    position: 'bottom-right',
    debug: false
  });

  // Check initialization
  if (!getStatus().initialized) {
    console.error('Failed to initialize widget');
    return;
  }

  // Set up event listeners
  on('error', (error) => {
    console.error(`[${error.category}] ${error.message}`);
  });

  on('callStarted', (call) => {
    console.log('Call started:', call.phoneNumber);
  });

  on('messageReceived', (message) => {
    console.log('New message:', message.text);
  });

  // Show widget
  show();

  // Load client
  loadClient({
    name: 'John Doe',
    phoneNumber: '+1234567890'
  });

  // Make a call
  await makeCall('+1234567890');

  // Send a message
  await sendMessage('+1234567890', 'Hello!');

  // Clean up on page unload
  window.addEventListener('beforeunload', () => {
    destroy();
  });
}

setupWidget();

Error Handling

// Check initialization status
const widget = await init({ apiKey: 'your-api-key' });
if (!getStatus().initialized) {
  console.error('Widget initialization failed');
}

// Handle runtime errors
on('error', (error) => {
  switch (error.category) {
    case 'auth':
      // Handle authentication errors
      alert('Authentication failed. Please check your API key.');
      break;
    case 'voice':
      // Handle voice errors
      alert('Call failed. Please check your microphone.');
      break;
    case 'network':
      // Handle network errors
      alert('Connection lost. Please check your internet.');
      break;
  }
});

Best Practices

1. Always check initialization status using getStatus().initialized
2. Set up error handlers early
3. Clean up with destroy() when done
4. Use client objects for better UX
5. Never expose API keys in client code

Error Codes

Errors emitted via the error event include a code field for programmatic handling:

Code	Category	Description
AUTH_001	auth	Invalid API key
AUTH_002	auth	API key expired or revoked
AUTH_003	auth	Account not found
VOICE_001	voice	Microphone permission denied
VOICE_002	voice	Call failed to connect
VOICE_003	voice	Voice token refresh failed
VOICE_004	voice	No voice device available
SMS_001	sms	Message send failed
SMS_002	sms	Invalid phone number
SMS_003	sms	SMS room creation failed
WS_001	network	WebSocket connection failed
WS_002	network	Max reconnection attempts reached
WS_003	network	Connection rejected by server
API_001	api	Request timeout
API_002	api	Server error
API_003	api	Rate limited

See Also

• Types - TypeScript type definitions
• Events - Event reference and handling
• Configuration - Configuration options
• Widget Setup - Creating widgets in Traise