@telnyx/ai-agent-lib 0.1.6 → 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
@@ -331,7 +352,7 @@ This library is built with TypeScript and provides full type definitions. All ho
 
 ## Examples
 
-Check out the `/src` directory for a complete example application demonstrating all features of the library.
+Check out the [example](https://github.com/team-telnyx/telnyx-ai-agent-lib-example) repository for a complete example application demonstrating all features of the library.
 
 ## Dependencies
 
@@ -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>;
-    sendConversationMessage(message: string): 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

@@ -2558,34 +2558,67 @@ function di() {
 }
 var ui = di();
 const dt = /* @__PURE__ */ li(ui), Ee = new dt();
-function hi(t) {
+function hi(t, e) {
+  let n = 0;
+  return (...i) => {
+    const s = Date.now();
+    s - n >= e && (n = s, t(...i));
+  };
+}
+const pi = 10;
+class fi {
+  animationFrameId = null;
+  stream = null;
+  audioContext = null;
+  source = null;
+  analyser = null;
+  updateAgentState = hi((e) => {
+    Ee.emit("conversation.agent.state", e);
+  }, 100);
+  setMonitoredAudioStream(e) {
+    this.stream && this.stopAudioStreamMonitor(), this.stream = e, this.startAudioStreamMonitor();
+  }
+  stopAudioStreamMonitor() {
+    this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), this.source?.disconnect();
+  }
+  startAudioStreamMonitor() {
+    if (!this.stream) return;
+    this.audioContext = new AudioContext(), this.source = this.audioContext.createMediaStreamSource(this.stream), this.analyser = this.audioContext.createAnalyser(), this.source.connect(this.analyser), this.analyser.fftSize = 512;
+    const e = new Uint8Array(this.analyser.frequencyBinCount), n = () => {
+      const i = e.reduce((s, c) => s + c, 0) / e.length;
+      this.analyser?.getByteFrequencyData(e), i >= pi ? this.updateAgentState("speaking") : this.updateAgentState("listening"), this.animationFrameId = requestAnimationFrame(n);
+    };
+    this.animationFrameId = requestAnimationFrame(n);
+  }
+}
+function gi(t) {
   if (!t || typeof t != "object")
     return !1;
   const e = t;
   return e.method === "ai_conversation" && typeof e.params == "object";
 }
-function pi(t) {
+function vi(t) {
   if (!t || typeof t != "object")
     return !1;
   const e = t;
   return e.params.type !== "response.text.delta" ? !1 : !!e.params.delta;
 }
-function fi(t) {
+function mi(t) {
   if (!t || typeof t != "object")
     return !1;
   const e = t;
   return e.params.type !== "conversation.item.created" ? !1 : !!e.params.item.content;
 }
-function gi(t) {
-  return pi(t) ? {
+function bi(t) {
+  return vi(t) ? {
     id: `${t.params.item_id}-${Date.now()}`,
     role: "assistant",
     content: t.params.delta,
     timestamp: /* @__PURE__ */ new Date()
   } : null;
 }
-function vi(t) {
-  if (!fi(t) || t.params.item.role !== "user" || t.params.item.status !== "completed")
+function yi(t) {
+  if (!mi(t) || t.params.item.role !== "user" || t.params.item.status !== "completed")
     return null;
   let e = "", n = [];
   return Array.isArray(t.params.item.content) ? (e = t.params.item.content.reduce((i, s) => (s.type === "text" && (i += s.text), i), ""), n = t.params.item.content.reduce((i, s) => (s.type === "image_url" && s.image_url.url && i.push({ type: "image", url: s.image_url.url }), i), [])) : e = t.params.item.content, {
@@ -2596,61 +2629,28 @@ function vi(t) {
     attachments: n
   };
 }
-class mi extends dt {
+class _i extends dt {
   telnyxRTC;
   transcript = [];
   constructor(e) {
     super(), this.telnyxRTC = e, this.telnyxRTC.on(O.SocketMessage, this.onSocketMessage);
   }
   onSocketMessage = (e) => {
-    if (hi(e))
+    if (gi(e))
       switch (e.params.type) {
         case "response.text.delta": {
-          const n = gi(e);
+          const n = bi(e);
           n && (this.transcript.push(n), this.emit("transcript.item", n), Ee.emit("conversation.agent.state", "listening"));
           return;
         }
         case "conversation.item.created": {
-          const n = vi(e);
+          const n = yi(e);
           n && (this.transcript.push(n), this.emit("transcript.item", n), Ee.emit("conversation.agent.state", "thinking"));
           return;
         }
       }
   };
 }
-function bi(t, e) {
-  let n = 0;
-  return (...i) => {
-    const s = Date.now();
-    s - n >= e && (n = s, t(...i));
-  };
-}
-const yi = 10;
-class _i {
-  animationFrameId = null;
-  stream = null;
-  audioContext = null;
-  source = null;
-  analyser = null;
-  updateAgentState = bi((e) => {
-    Ee.emit("conversation.agent.state", e);
-  }, 100);
-  setMonitoredAudioStream(e) {
-    this.stream && this.stopAudioStreamMonitor(), this.stream = e, this.startAudioStreamMonitor();
-  }
-  stopAudioStreamMonitor() {
-    this.animationFrameId && (cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null), this.source?.disconnect();
-  }
-  startAudioStreamMonitor() {
-    if (!this.stream) return;
-    this.audioContext = new AudioContext(), this.source = this.audioContext.createMediaStreamSource(this.stream), this.analyser = this.audioContext.createAnalyser(), this.source.connect(this.analyser), this.analyser.fftSize = 512;
-    const e = new Uint8Array(this.analyser.frequencyBinCount), n = () => {
-      const i = e.reduce((s, c) => s + c, 0) / e.length;
-      this.analyser?.getByteFrequencyData(e), i >= yi ? this.updateAgentState("speaking") : this.updateAgentState("listening"), this.animationFrameId = requestAnimationFrame(n);
-    };
-    this.animationFrameId = requestAnimationFrame(n);
-  }
-}
 class Ot extends dt {
   telnyxRTC;
   transcription;
@@ -2667,41 +2667,103 @@ class Ot extends dt {
         target_type: "ai_assistant",
         target_version_id: e.versionId
       }
-    }), this.telnyxRTC.on(O.Ready, this.onClientReady), this.telnyxRTC.on(O.Error, this.onClientOrSocketError), this.telnyxRTC.on(O.SocketError, this.onClientOrSocketError), this.telnyxRTC.on(O.Notification, this.onNotification), this.transcription = new mi(this.telnyxRTC), this.transcription.addListener("transcript.item", this.onTranscriptItem), Ee.addListener(
+    }), this.telnyxRTC.on(O.Ready, this.onClientReady), this.telnyxRTC.on(O.Error, this.onClientOrSocketError), this.telnyxRTC.on(O.SocketError, this.onClientOrSocketError), this.telnyxRTC.on(O.Notification, this.onNotification), this.transcription = new _i(this.telnyxRTC), this.transcription.addListener("transcript.item", this.onTranscriptItem), Ee.addListener(
       "conversation.agent.state",
       this.onAgentStateChange
-    ), this.audioStreamMonitor = new _i();
+    ), 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();
   }
-  sendConversationMessage(e) {
+  /**
+   * 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.");
       return;
     }
-    this.activeCall.sendConversationMessage(e);
+    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.6",
+  "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"
 }