@telnyx/ai-agent-lib 0.1.7 → 0.1.9

package/README.md

@@ -86,7 +86,12 @@ function VoiceChat() {
       <h3>Agent State: {agentState}</h3>
       
       <button 
-        onClick={() => client.startConversation()}
+        onClick={() =>
+          client.startConversation({
+            callerName: 'Jane Doe',
+            customHeaders: [{ name: 'X-Account-Number', value: '123456' }]
+          })
+        }
         disabled={connectionState !== 'connected'}
       >
         Start Conversation
@@ -142,6 +147,7 @@ function VoiceChat() {
 | `agentId` | `string` | ✅ | - | Your Telnyx AI agent ID |
 | `versionId` | `string` | ❌ | `"main"` | Agent version to use |
 | `environment` | `"production" \| "development"` | ❌ | `"production"` | Telnyx environment |
+| `debug` | `boolean` | ❌ | `false` | Enable debug logging |
 
 ### Hooks
 
@@ -151,11 +157,20 @@ Returns the `TelnyxAIAgent` instance for direct API access.
 **Methods:**
 - `connect()` - Connect to Telnyx platform
 - `disconnect()` - Disconnect and cleanup
-- `startConversation()` - Start a new conversation
+- `startConversation(options?)` - Start a new conversation with optional caller metadata and headers
 - `endConversation()` - End the current conversation
 - `sendConversationMessage(message: string)` - Send a text message during an active conversation
 - `transcript` - Get current transcript array
 
+**`startConversation` Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `destinationNumber` | `string` | [docs](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#destinationnumber) |
+| `callerNumber` | `string` | [docs](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#callernumber) |
+| `callerName` | `string` | [docs](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#callername) |
+| `customHeaders` | `{ name: string; value: string }[]` | [docs](https://developers.telnyx.com/development/webrtc/js-sdk/interfaces/icalloptions#customheaders) |
+
 **Events:**
 - `agent.connected` - Agent successfully connected
 - `agent.disconnected` - Agent disconnected
@@ -224,8 +239,16 @@ agent.on('conversation.update', (notification) => {
   }
 });
 
-// Start a conversation
-await agent.startConversation();
+// Start a conversation with optional caller metadata
+await agent.startConversation({
+  callerNumber: '+15551234567',
+  callerName: 'John Doe',
+  customHeaders: [
+    { name: 'X-User-Plan', value: 'gold' },
+    { name: 'X-Session-Id', value: 'session-abc' }
+  ],
+  audio: { autoGainControl: true, noiseSuppression: true }
+});
 
 // Send messages during an active conversation
 // Note: This will only work when there's an active call
@@ -350,4 +373,3 @@ For support, please contact Telnyx support or check the [Telnyx documentation](h
 ## Contributing
 
 This library is maintained by Telnyx. For bug reports or feature requests, please contact Telnyx support.elnyx AI Agent Library
-

package/dist/client.d.ts

@@ -5,20 +5,88 @@ export type TelnyxAIAgentConstructorParams = {
     agentId: string;
     versionId?: string;
     environment?: "production" | "development";
+    debug?: boolean;
 };
 export declare class TelnyxAIAgent extends EventEmitter<AIAgentEvents> {
     private telnyxRTC;
     private transcription;
     agentId: string;
     versionId: string;
+    debug: boolean;
     private audioStreamMonitor;
     activeCall: Call | null;
     constructor(params: TelnyxAIAgentConstructorParams);
+    /**
+     * Connects to the Telnyx WebRTC service and establishes a session with the AI agent.
+     *
+     * @returns Promise that resolves when the connection is established
+     */
     connect(): Promise<void>;
+    /**
+     * Disconnects from the Telnyx WebRTC service and cleans up all event listeners.
+     * Emits an 'agent.disconnected' event before completing cleanup.
+     */
     disconnect(): Promise<void>;
+    /**
+     * Sends a text message to the AI agent during an active conversation.
+     * Requires an active conversation to be in progress.
+     *
+     * @param message - The text message to send to the AI agent
+     * @param attachments - Optional array of base64 encoded file attachments (defaults to empty array)
+     *
+     * @example
+     * client.sendConversationMessage('Hello, I need help with my account');
+     *
+     * @example
+     * // With attachments
+     * client.sendConversationMessage('Please review this document', ['base64EncodedData...']);
+     */
     sendConversationMessage(message: string, attachments?: string[]): void;
+    /**
+     * Gets the current conversation transcript.
+     *
+     * @returns Array of transcript items containing all messages exchanged during the conversation
+     */
     get transcript(): TranscriptItem[];
-    startConversation(): Promise<void>;
+    /**
+     * Initiates a conversation with the AI agent.
+     *
+     * @param options - Optional configuration for the call.
+     * Note: This method will ALWAYS call the AI agent, the optional parameters are primarily used for log referencing or passing parameters to the agent via the custom headers.
+     * @param options.destinationNumber - The destination phone number (defaults to "xxx"). Note, regardless of the destination number, the call will be made to the AI agent.
+     * @param options.callerNumber - The caller's phone number
+     * @param options.callerName - The caller's display name
+     * @param options.customHeaders - Custom SIP headers to pass to the AI agent. Headers with the `X-` prefix
+     * will be mapped to dynamic variables in the AI assistant (e.g., `X-Account-Number` becomes `{{account_number}}`).
+     * Note: Hyphens in header names are converted to underscores in variable names.
+     *
+     * @example
+     * // Start conversation with custom headers for dynamic variables
+     * client.startConversation({
+     *   callerName: 'John Doe',
+     *   customHeaders: [
+     *     { name: 'X-User-Name', value: 'user-name' },
+     *     { name: 'X-Agent-Session', value: 'session-abc' }
+     *   ]
+     * });
+     * // These headers will be available in your AI assistant as {{user_name}} and {{agent_session}}
+     * @param options.audio - Audio constraints for the call (boolean or MediaTrackConstraints)
+     */
+    startConversation(options?: {
+        destinationNumber?: string;
+        callerNumber?: string;
+        callerName?: string;
+        customHeaders?: {
+            name: string;
+            value: string;
+        }[];
+        audio?: boolean | MediaTrackConstraints;
+    }): Promise<void>;
+    /**
+     * Ends the current active conversation with the AI agent.
+     *
+     * @returns Promise that resolves when the call is hung up, or undefined if there is no active call
+     */
     endConversation(): void | undefined;
     private onClientReady;
     private onClientOrSocketError;

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./react/use-client-connection-state";
 export * from "./react/use-client";
 export * from "./react/use-conversation";
 export * from "./react/use-agent-state";
+export * from "./types";