Types

TypeScript type definitions for the Traise Widget API.

Configuration

WidgetConfig

Configuration options passed to init().

interface WidgetConfig {
  // Required
  apiKey: string;

  // UI Settings
  mode?: 'light' | 'dark';
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';

  // User Information
  userId?: string;
  firstName?: string;
  lastName?: string;

  // Features
  debug?: boolean;
  demoMode?: boolean;
}

Property	Type	Required	Default	Description
apiKey	string	Yes	-	Your Traise widget API key
mode	string	No	'light'	Color mode: 'light' or 'dark'
position	string	No	'bottom-right'	Widget position on screen
userId	string	No	''	User identifier
firstName	string	No	''	User's first name
lastName	string	No	''	User's last name
debug	boolean	No	false	Enable debug mode and logging
demoMode	boolean	No	false	Run with simulated data (no API calls)

Client Data

ClientData

Client information passed to loadClient() or makeCall().

interface ClientData {
  name?: string;
  phoneNumber?: string;
  mobilePhone?: string;
  email?: string;
  firstName?: string;
  lastName?: string;
}

Property	Type	Description
name	string	Client's display name
phoneNumber	string	Primary phone number
mobilePhone	string	Mobile phone number (alternative to phoneNumber)
email	string	Email address
firstName	string	First name
lastName	string	Last name

Status

WidgetStatus

Status object returned by getStatus().

interface WidgetStatus {
  initialized: boolean;
  visible: boolean;
  websocket: boolean;
  voice: boolean;
  activeCall: boolean;
  unreadMessages: number;
}

Property	Type	Description
initialized	boolean	Whether the widget initialized successfully
visible	boolean	Whether the widget panel is visible
websocket	boolean	Whether WebSocket is connected
voice	boolean	Whether voice device is ready
activeCall	boolean	Whether a call is in progress
unreadMessages	number	Count of unread messages

Errors

WidgetError

Error object emitted with the error event.

interface WidgetError {
  category: 'auth' | 'voice' | 'sms' | 'network' | 'api';
  message: string;
  code?: string;
  details?: any;
  timestamp: string;
}

Property	Type	Description
category	string	Error category for handling
message	string	Human-readable error message
code	string	Optional error code
details	any	Optional additional error details
timestamp	string	ISO timestamp when error occurred

Error Categories

Category	Description
auth	Authentication or authorization error
voice	Voice call error (connection, device, etc.)
sms	SMS/messaging error
network	Network connectivity error
api	API request error

Call Information

CallInfo

Information about a voice call.

interface CallInfo {
  phoneNumber: string;
  direction: 'inbound' | 'outbound';
  status: 'connecting' | 'ringing' | 'connected' | 'ended';
  duration?: number;
  clientName?: string;
}

Property	Type	Description
phoneNumber	string	Phone number of the other party
direction	string	Whether call is inbound or outbound
status	string	Current call status
duration	number	Call duration in seconds (when ended)
clientName	string	Name of the client if known

Call Status Values

Status	Description
connecting	Call is being initiated
ringing	Call is ringing
connected	Call is active
ended	Call has ended

Messages

Message

Information about an SMS message.

interface Message {
  id: string;
  text: string;
  phoneNumber: string;
  direction: 'inbound' | 'outbound';
  status: 'pending' | 'sent' | 'delivered' | 'failed';
  timestamp: string;
  clientName?: string;
}

Property	Type	Description
id	string	Unique message identifier
text	string	Message content
phoneNumber	string	Phone number of the other party
direction	string	Whether message is inbound or outbound
status	string	Delivery status
timestamp	string	ISO timestamp
clientName	string	Name of the client if known

Message Status Values

Status	Description
pending	Message is being sent
sent	Message was sent
delivered	Message was delivered
failed	Message failed to send

Using Types in TypeScript

If you're using TypeScript, you can create a type declaration file:

// types/traise-widget.d.ts
declare module 'traise-widget' {
  interface WidgetConfig {
    apiKey: string;
    mode?: 'light' | 'dark';
    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
    userId?: string;
    firstName?: string;
    lastName?: string;
    debug?: boolean;
    demoMode?: boolean;
  }

  interface ClientData {
    name?: string;
    phoneNumber?: string;
    mobilePhone?: string;
    email?: string;
    firstName?: string;
    lastName?: string;
  }

  interface WidgetStatus {
    initialized: boolean;
    visible: boolean;
    websocket: boolean;
    voice: boolean;
    activeCall: boolean;
    unreadMessages: number;
  }

  interface TraiseWidgetAPI {
    init(config: WidgetConfig): Promise<TraiseWidgetAPI>;
    show(): TraiseWidgetAPI;
    hide(): TraiseWidgetAPI;
    destroy(): void;
    retry(): Promise<TraiseWidgetAPI>;
    makeCall(target: string | ClientData): Promise<void>;
    endCall(): void;
    sendMessage(phoneNumber: string, message: string): Promise<void>;
    loadClient(client: ClientData): TraiseWidgetAPI;
    setClient(client: ClientData): TraiseWidgetAPI;
    getClient(): ClientData | null;
    unloadClient(): TraiseWidgetAPI;
    getConfig(): WidgetConfig;
    updateConfig(updates: Partial<WidgetConfig>): TraiseWidgetAPI;
    getStatus(): WidgetStatus;
    on(event: string, handler: Function): TraiseWidgetAPI;
    off(event: string, handler: Function): TraiseWidgetAPI;
  }

  export function init(config: WidgetConfig): Promise<TraiseWidgetAPI>;
  export function show(): TraiseWidgetAPI;
  export function hide(): TraiseWidgetAPI;
  export function destroy(): void;
  export function retry(): Promise<TraiseWidgetAPI>;
  export function makeCall(target: string | ClientData): Promise<void>;
  export function endCall(): void;
  export function sendMessage(phoneNumber: string, message: string): Promise<void>;
  export function loadClient(client: ClientData): TraiseWidgetAPI;
  export function setClient(client: ClientData): TraiseWidgetAPI;
  export function getClient(): ClientData | null;
  export function unloadClient(): TraiseWidgetAPI;
  export function getConfig(): WidgetConfig;
  export function updateConfig(updates: Partial<WidgetConfig>): TraiseWidgetAPI;
  export function getStatus(): WidgetStatus;
  export function on(event: string, handler: Function): TraiseWidgetAPI;
  export function off(event: string, handler: Function): TraiseWidgetAPI;

  const widget: TraiseWidgetAPI;
  export default widget;
}

Next Steps

• Events - Event reference
• API Reference - Complete API documentation