@telnyx/ai-agent-lib 0.1.7 → 0.1.8

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
@@ -151,11 +156,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 +238,15 @@ 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' }
+  ]
+});
 
 // Send messages during an active conversation
 // Note: This will only work when there's an active call
@@ -350,4 +371,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

@@ -14,11 +14,75 @@ export declare class TelnyxAIAgent extends EventEmitter<AIAgentEvents> {
     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}}
+     */
+    startConversation(options?: {
+        destinationNumber?: string;
+        callerNumber?: string;
+        callerName?: string;
+        customHeaders?: {
+            name: string;
+            value: string;
+        }[];
+    }): 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.js

@@ -2672,12 +2672,35 @@ class Ot extends dt {
       this.onAgentStateChange
     ), this.audioStreamMonitor = new fi();
   }
+  /**
+   * Connects to the Telnyx WebRTC service and establishes a session with the AI agent.
+   *
+   * @returns Promise that resolves when the connection is established
+   */
   async connect() {
     return this.telnyxRTC.connect();
   }
+  /**
+   * Disconnects from the Telnyx WebRTC service and cleans up all event listeners.
+   * Emits an 'agent.disconnected' event before completing cleanup.
+   */
   async disconnect() {
     this.audioStreamMonitor.stopAudioStreamMonitor(), this.telnyxRTC.disconnect(), this.telnyxRTC.off(O.Ready, this.onClientReady), this.telnyxRTC.off(O.Error, this.onClientOrSocketError), this.telnyxRTC.off(O.SocketError, this.onClientOrSocketError), this.telnyxRTC.off(O.Notification, this.onNotification), this.emit("agent.disconnected"), this.transcription.removeAllListeners(), Ee.removeAllListeners(), this.removeAllListeners();
   }
+  /**
+   * 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(e, n = []) {
     if (!this.activeCall) {
       console.error("No active call to send message.");
@@ -2685,23 +2708,62 @@ class Ot extends dt {
     }
     this.activeCall.sendConversationMessage(e, n);
   }
+  /**
+   * Gets the current conversation transcript.
+   *
+   * @returns Array of transcript items containing all messages exchanged during the conversation
+   */
   get transcript() {
     return this.transcription.transcript;
   }
-  async startConversation() {
+  /**
+   * 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}}
+   */
+  async startConversation(e) {
     if (!this.telnyxRTC) {
       console.error("Client is not initialized.");
       return;
     }
-    const n = RTCRtpReceiver.getCapabilities("audio")?.codecs?.find(
-      (c) => c.mimeType.toLowerCase().includes("opus")
-    ), i = this.versionId ? [{ name: "X-AI-Assistant-Version-ID", value: this.versionId }] : void 0, s = this.telnyxRTC.newCall({
+    const i = RTCRtpReceiver.getCapabilities("audio")?.codecs?.find(
+      (h) => h.mimeType.toLowerCase().includes("opus")
+    ), { customHeaders: s, ...c } = e || {}, a = s ? [...s] : [];
+    this.versionId && a.push({
+      name: "X-AI-Assistant-Version-ID",
+      value: this.versionId
+    });
+    const d = this.telnyxRTC.newCall({
       destinationNumber: "xxx",
-      preferred_codecs: [n],
-      customHeaders: i
+      ...c,
+      preferred_codecs: [i],
+      customHeaders: a.length > 0 ? a : void 0
     });
-    this.emit("conversation.update", { call: s, type: "callUpdate" });
+    this.emit("conversation.update", { call: d, type: "callUpdate" });
   }
+  /**
+   * 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() {
     return this.activeCall?.hangup();
   }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@telnyx/ai-agent-lib",
   "private": false,
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "license": "MIT",
   "files": [
     "dist"
   ],
@@ -40,5 +41,6 @@
     "typescript": "~5.8.3",
     "typescript-eslint": "^8.35.1",
     "vite": "^7.0.4"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }