phonic 0.26.1 → 0.27.0

package/README.md

@@ -190,16 +190,25 @@ const toolsResult = await phonic.tools.list();
 
 ### Get tool
 
+Gets a tool by its ID or name.
+
 ```ts
 const toolResult = await phonic.tools.get("next_invoice");
+const toolByIdResult = await phonic.tools.get("tool_12cf6e88-c254-4d3e-a149-ddf1bdd2254c");
 ```
 
 ### Create tool
 
+Tools can be either webhook-based (HTTP endpoints) or WebSocket-based.
+
+#### Create webhook tool
+
 ```ts
-const createToolResult = await phonic.tools.create({
+const createWebhookToolResult = await phonic.tools.create({
   name: "next_invoice",
   description: "Returns the next invoice of the given user",
+  type: "custom_webhook",
+  executionMode: "sync",
   endpointMethod: "POST",
   endpointUrl: "https://myapp.com/webhooks/next-invoice",
   endpointHeaders: {
@@ -230,12 +239,75 @@ const createToolResult = await phonic.tools.create({
 });
 ```
 
+#### Create WebSocket tool
+
+WebSocket tools allow you to handle tool execution through the WebSocket connection. When the agent calls a WebSocket tool, you'll receive a `tool_call` message and must respond with a `tool_call_output` message that contains the tool result.
+
+```ts
+const createWebSocketToolResult = await phonic.tools.create({
+  name: "get_product_recommendations",
+  description: "Gets personalized product recommendations",
+  type: "custom_websocket",
+  executionMode: "async",
+  toolCallOutputTimeoutMs: 5000, // Optional, defaults to 15000
+  parameters: [
+    {
+      type: "string",
+      name: "category",
+      description: "Product category (e.g., 'handbags', 'shoes', 'electronics')",
+      isRequired: true
+    }
+  ]
+});
+```
+
+To use this tool in a conversation, add it to your agent or config:
+
+```ts
+// When creating an agent
+const agent = await phonic.agents.create({
+  name: "shopping-assistant",
+  tools: ["get_product_recommendations"],
+  // ... other config
+});
+
+// Or, override agent settings when starting a WebSocket conversation
+const phonicWebSocket = phonic.sts.websocket({
+  name: "shopping-assistant",
+  tools: ["get_product_recommendations"],
+  // ... other config
+});
+
+// Handle the tool call when it's invoked
+phonicWebSocket.onMessage(async (message) => {
+  if (message.type === "tool_call" && message.name === "get_product_recommendations") {
+    const category = message.parameters.category;
+    
+    // Execute your business logic
+    const recommendations = fetchRecommendations(category);
+    
+    // Send the result back
+    phonicWebSocket.[sendToolCallOutput](#send-tool-output-to-phonic)({
+      toolCallId: message.tool_call_id,
+      output: {
+        products: recommendations,
+        total: recommendations.length
+      }
+    });
+  }
+});
+```
+
 ### Update tool
 
+Updates a tool by ID or name. All fields are optional - only provided fields will be updated.
+
 ```ts
-const updateToolResult = await phonic.tools.update("next_invoice", {
+const updateWebhookToolResult = await phonic.tools.update("next_invoice", {
   name: "next_invoice_updated",
   description: "Updated description.",
+  type: "custom_webhook",
+  executionMode: "sync",
   endpointMethod: "POST",
   endpointUrl: "https://myapp.com/webhooks/next-invoice-updated",
   endpointHeaders: {
@@ -266,8 +338,19 @@ const updateToolResult = await phonic.tools.update("next_invoice", {
 });
 ```
 
+For WebSocket tools, you would use `toolCallOutputTimeoutMs` instead of the endpoint fields:
+
+```ts
+const updateWebSocketToolResult = await phonic.tools.update("get_product_recommendations", {
+  description: "Updated product recommendation tool",
+  toolCallOutputTimeoutMs: 7000
+});
+```
+
 ### Delete tool
 
+Deletes a tool by ID or name.
+
 ```ts
 const deleteToolResult = await phonic.tools.delete("next_invoice");
 ```
@@ -412,6 +495,26 @@ phonicWebSocket.onMessage((message) => {
       );
       break;
     }
+
+    case "tool_call": {
+      // Handle WebSocket tool calls
+      console.log(`Tool ${message.tool_name} called with parameters:`, message.parameters);
+      
+      // Example: Process a product recommendations tool call
+      if (message.tool_name === "get_product_recommendations") {
+        const category = message.parameters.category;
+        const recommendations = fetchRecommendations(category);
+        
+        phonicWebSocket.[sendToolCallOutput](#send-tool-output-to-phonic)({
+          toolCallId: message.tool_call_id,
+          output: {
+            products: recommendations,
+            total: recommendations.length
+          }
+        });
+      }
+      break;
+    }
   }
 });
 ```
@@ -432,6 +535,34 @@ phonicWebSocket.setExternalId({
 })
 ```
 
+### Send tool output to Phonic
+
+When you receive a `tool_call` message for a WebSocket tool, you must respond with the tool's output using `sendToolCallOutput()`. This method sends the execution result back to Phonic so the conversation can continue.
+
+```ts
+phonicWebSocket.sendToolCallOutput({
+  toolCallId: "tool_call_123...", // The tool_call_id from the tool_call message
+  output: "Success! Found 2 items" // Can be any JSON-serializable value (string, number, object, array, etc.)
+});
+
+// Or with an object:
+phonicWebSocket.sendToolCallOutput({
+  toolCallId: message.tool_call_id,
+  output: {
+    result: "success",
+    data: {
+      items: ["item1", "item2"],
+      total: 2
+    }
+  }
+});
+```
+
+**Important notes:**
+- You must use the exact `tool_call_id` received in the `tool_call` message
+- The `output` can be any JSON-serializable value (string, number, boolean, object, array, etc.)
+- If you don't send a response within `toolCallOutputTimeoutMs`, the tool call will be marked as failed.
+
 To end the conversation, close the WebSocket:
 
 ```ts
@@ -564,7 +695,24 @@ Sent when the assistant decides to end the conversation.
 ```ts
 {
   type: "tool_call";
-  id: string;
+  tool_call_id: string;
+  tool_name: string;
+  parameters: Record<string, unknown>;
+}
+```
+
+Sent when a WebSocket tool is called during the conversation. When you receive this message, you should:
+1. Process the tool call using the provided `tool_name` and `parameters`
+2. Send back the result using [`phonicWebSocket.sendToolCallOutput`](#send-tool-output-to-phonic)
+
+This is only sent for tools created with `type: "custom_websocket"`. Webhook tools are executed server-side and only send `tool_call_output_processed` messages.
+
+#### `tool_call_output_processed`
+
+```ts
+{
+  type: "tool_call_output_processed";
+  tool_call_id: string;
   tool: {
     id: string;
     name: string;

package/dist/index.d.mts

@@ -93,8 +93,8 @@ type PhonicSTSWebSocketResponseMessage = {
     type: "dtmf";
     digits: string;
 } | {
-    type: "tool_call";
-    id: string;
+    type: "tool_call_output_processed";
+    tool_call_id: string;
     tool: {
         id: string;
         name: string;
@@ -109,10 +109,17 @@ type PhonicSTSWebSocketResponseMessage = {
         } | null;
         [key: string]: unknown;
     } | null;
-    response_body: Record<string, unknown> | null;
+    parameters: Record<string, unknown> | null;
+    output: unknown | null;
+    response_body: unknown | null;
     response_status_code: number | null;
     timed_out: boolean | null;
     error_message: string | null;
+} | {
+    type: "tool_call";
+    tool_call_id: string;
+    tool_name: string;
+    parameters: Record<string, unknown>;
 } | {
     type: "error";
     error: {
@@ -371,12 +378,17 @@ declare class PhonicSTSWebSocket {
     private buffer;
     private isOpen;
     constructor(ws: WebSocket, config: PhonicSTSConfig);
+    private processUserMessage;
     onMessage(callback: OnMessageCallback): void;
     onClose(callback: OnCloseCallback): void;
     onError(callback: OnErrorCallback): void;
     audioChunk({ audio }: {
         audio: string;
     }): void;
+    sendToolCallOutput({ toolCallId, output, }: {
+        toolCallId: string;
+        output: unknown;
+    }): void;
     updateSystemPrompt({ systemPrompt }: {
         systemPrompt: string;
     }): void;
@@ -405,31 +417,50 @@ interface ArrayParameter extends ParameterBase {
     itemType: "string" | "integer" | "number" | "boolean";
 }
 type ToolParameters = Array<PrimitiveParameter | ArrayParameter>;
-type Tool = {
+type ExecutionMode = "sync" | "async";
+interface ToolBase {
     id: string;
     name: string;
     description: string;
+    execution_mode: ExecutionMode;
+    parameters: ToolParameters;
+}
+interface WebhookTool extends ToolBase {
+    type: "custom_webhook";
     endpoint_method: "POST";
     endpoint_url: string;
     endpoint_headers: Record<string, string>;
     endpoint_timeout_ms: number;
-    parameters: ToolParameters;
-};
+}
+interface WebSocketTool extends ToolBase {
+    type: "custom_websocket";
+    tool_call_output_timeout_ms: number;
+}
+type Tool = WebhookTool | WebSocketTool;
 type ListToolsSuccessResponse = DataOrError<{
     tools: Array<Tool>;
 }>;
 type GetToolSuccessResponse = DataOrError<{
     tool: Tool;
 }>;
-type CreateToolParams = {
+interface CreateToolParamsBase {
     name: string;
     description: string;
+    executionMode: ExecutionMode;
+    parameters?: ToolParameters;
+}
+interface CreateWebhookToolParams extends CreateToolParamsBase {
+    type: "custom_webhook";
     endpointMethod: "POST";
     endpointUrl: string;
     endpointHeaders?: Record<string, string>;
     endpointTimeoutMs?: number;
-    parameters?: ToolParameters;
-};
+}
+interface CreateWebSocketToolParams extends CreateToolParamsBase {
+    type: "custom_websocket";
+    toolCallOutputTimeoutMs?: number;
+}
+type CreateToolParams = CreateWebhookToolParams | CreateWebSocketToolParams;
 type CreateToolSuccessResponse = {
     id: string;
     name: string;
@@ -437,11 +468,14 @@ type CreateToolSuccessResponse = {
 type UpdateToolParams = {
     name?: string;
     description?: string;
+    type?: "custom_webhook" | "custom_websocket";
+    executionMode?: ExecutionMode;
     endpointMethod?: "POST";
     endpointUrl?: string;
     endpointHeaders?: Record<string, string>;
     endpointTimeoutMs?: number;
-    parameters?: Array<PrimitiveParameter | ArrayParameter>;
+    toolCallOutputTimeoutMs?: number;
+    parameters?: ToolParameters;
 };
 type UpdateToolSuccessResponse = {
     success: true;
@@ -550,4 +584,4 @@ declare class Phonic {
     }>;
 }
 
-export { Phonic, type PhonicConfigurationEndpointRequestPayload, type PhonicConfigurationEndpointResponsePayload, type PhonicSTSConfig, PhonicSTSWebSocket };
+export { Phonic, type PhonicConfigurationEndpointRequestPayload, type PhonicConfigurationEndpointResponsePayload, type PhonicSTSConfig, PhonicSTSWebSocket, type PhonicSTSWebSocketResponseMessage };

package/dist/index.d.ts

@@ -93,8 +93,8 @@ type PhonicSTSWebSocketResponseMessage = {
     type: "dtmf";
     digits: string;
 } | {
-    type: "tool_call";
-    id: string;
+    type: "tool_call_output_processed";
+    tool_call_id: string;
     tool: {
         id: string;
         name: string;
@@ -109,10 +109,17 @@ type PhonicSTSWebSocketResponseMessage = {
         } | null;
         [key: string]: unknown;
     } | null;
-    response_body: Record<string, unknown> | null;
+    parameters: Record<string, unknown> | null;
+    output: unknown | null;
+    response_body: unknown | null;
     response_status_code: number | null;
     timed_out: boolean | null;
     error_message: string | null;
+} | {
+    type: "tool_call";
+    tool_call_id: string;
+    tool_name: string;
+    parameters: Record<string, unknown>;
 } | {
     type: "error";
     error: {
@@ -371,12 +378,17 @@ declare class PhonicSTSWebSocket {
     private buffer;
     private isOpen;
     constructor(ws: WebSocket, config: PhonicSTSConfig);
+    private processUserMessage;
     onMessage(callback: OnMessageCallback): void;
     onClose(callback: OnCloseCallback): void;
     onError(callback: OnErrorCallback): void;
     audioChunk({ audio }: {
         audio: string;
     }): void;
+    sendToolCallOutput({ toolCallId, output, }: {
+        toolCallId: string;
+        output: unknown;
+    }): void;
     updateSystemPrompt({ systemPrompt }: {
         systemPrompt: string;
     }): void;
@@ -405,31 +417,50 @@ interface ArrayParameter extends ParameterBase {
     itemType: "string" | "integer" | "number" | "boolean";
 }
 type ToolParameters = Array<PrimitiveParameter | ArrayParameter>;
-type Tool = {
+type ExecutionMode = "sync" | "async";
+interface ToolBase {
     id: string;
     name: string;
     description: string;
+    execution_mode: ExecutionMode;
+    parameters: ToolParameters;
+}
+interface WebhookTool extends ToolBase {
+    type: "custom_webhook";
     endpoint_method: "POST";
     endpoint_url: string;
     endpoint_headers: Record<string, string>;
     endpoint_timeout_ms: number;
-    parameters: ToolParameters;
-};
+}
+interface WebSocketTool extends ToolBase {
+    type: "custom_websocket";
+    tool_call_output_timeout_ms: number;
+}
+type Tool = WebhookTool | WebSocketTool;
 type ListToolsSuccessResponse = DataOrError<{
     tools: Array<Tool>;
 }>;
 type GetToolSuccessResponse = DataOrError<{
     tool: Tool;
 }>;
-type CreateToolParams = {
+interface CreateToolParamsBase {
     name: string;
     description: string;
+    executionMode: ExecutionMode;
+    parameters?: ToolParameters;
+}
+interface CreateWebhookToolParams extends CreateToolParamsBase {
+    type: "custom_webhook";
     endpointMethod: "POST";
     endpointUrl: string;
     endpointHeaders?: Record<string, string>;
     endpointTimeoutMs?: number;
-    parameters?: ToolParameters;
-};
+}
+interface CreateWebSocketToolParams extends CreateToolParamsBase {
+    type: "custom_websocket";
+    toolCallOutputTimeoutMs?: number;
+}
+type CreateToolParams = CreateWebhookToolParams | CreateWebSocketToolParams;
 type CreateToolSuccessResponse = {
     id: string;
     name: string;
@@ -437,11 +468,14 @@ type CreateToolSuccessResponse = {
 type UpdateToolParams = {
     name?: string;
     description?: string;
+    type?: "custom_webhook" | "custom_websocket";
+    executionMode?: ExecutionMode;
     endpointMethod?: "POST";
     endpointUrl?: string;
     endpointHeaders?: Record<string, string>;
     endpointTimeoutMs?: number;
-    parameters?: Array<PrimitiveParameter | ArrayParameter>;
+    toolCallOutputTimeoutMs?: number;
+    parameters?: ToolParameters;
 };
 type UpdateToolSuccessResponse = {
     success: true;
@@ -550,4 +584,4 @@ declare class Phonic {
     }>;
 }
 
-export { Phonic, type PhonicConfigurationEndpointRequestPayload, type PhonicConfigurationEndpointResponsePayload, type PhonicSTSConfig, PhonicSTSWebSocket };
+export { Phonic, type PhonicConfigurationEndpointRequestPayload, type PhonicConfigurationEndpointResponsePayload, type PhonicSTSConfig, PhonicSTSWebSocket, type PhonicSTSWebSocketResponseMessage };

package/dist/index.js

@@ -35,7 +35,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.26.1";
+var version = "0.27.0";
 
 // src/agents/index.ts
 var Agents = class {
@@ -298,6 +298,9 @@ var PhonicSTSWebSocket = class {
     this.onClose = this.onClose.bind(this);
     this.onError = this.onError.bind(this);
     this.audioChunk = this.audioChunk.bind(this);
+    this.sendToolCallOutput = this.sendToolCallOutput.bind(this);
+    this.updateSystemPrompt = this.updateSystemPrompt.bind(this);
+    this.setExternalId = this.setExternalId.bind(this);
     this.close = this.close.bind(this);
   }
   onMessageCallback = null;
@@ -305,6 +308,14 @@ var PhonicSTSWebSocket = class {
   onErrorCallback = null;
   buffer = [];
   isOpen = false;
+  processUserMessage(message) {
+    const messageStr = JSON.stringify(message);
+    if (this.isOpen) {
+      this.ws.send(messageStr);
+    } else {
+      this.buffer.push(messageStr);
+    }
+  }
   onMessage(callback) {
     this.onMessageCallback = callback;
   }
@@ -315,37 +326,32 @@ var PhonicSTSWebSocket = class {
     this.onErrorCallback = callback;
   }
   audioChunk({ audio }) {
-    const audiochunkMessage = JSON.stringify({
+    this.processUserMessage({
       type: "audio_chunk",
       audio
     });
-    if (this.isOpen) {
-      this.ws.send(audiochunkMessage);
-    } else {
-      this.buffer.push(audiochunkMessage);
-    }
+  }
+  sendToolCallOutput({
+    toolCallId,
+    output
+  }) {
+    this.processUserMessage({
+      type: "tool_call_output",
+      tool_call_id: toolCallId,
+      output
+    });
   }
   updateSystemPrompt({ systemPrompt }) {
-    const updateSystemPromptMessage = JSON.stringify({
+    this.processUserMessage({
       type: "update_system_prompt",
       system_prompt: systemPrompt
     });
-    if (this.isOpen) {
-      this.ws.send(updateSystemPromptMessage);
-    } else {
-      this.buffer.push(updateSystemPromptMessage);
-    }
   }
   setExternalId({ externalId }) {
-    const setExternalIdMessage = JSON.stringify({
+    this.processUserMessage({
       type: "set_external_id",
       external_id: externalId
     });
-    if (this.isOpen) {
-      this.ws.send(setExternalIdMessage);
-    } else {
-      this.buffer.push(setExternalIdMessage);
-    }
   }
   close(code) {
     this.ws.close(code ?? 1e3);
@@ -404,17 +410,25 @@ var Tools = class {
     return response;
   }
   async create(params) {
+    const body = {
+      name: params.name,
+      description: params.description,
+      type: params.type,
+      execution_mode: params.executionMode,
+      parameters: this.getParametersForBody(params.parameters)
+    };
+    if (params.type === "custom_webhook") {
+      body.endpoint_method = params.endpointMethod;
+      body.endpoint_url = params.endpointUrl;
+      body.endpoint_headers = params.endpointHeaders;
+      body.endpoint_timeout_ms = params.endpointTimeoutMs;
+    }
+    if (params.type === "custom_websocket") {
+      body.tool_call_output_timeout_ms = params.toolCallOutputTimeoutMs;
+    }
     const response = await this.phonic.post(
       "/tools",
-      {
-        name: params.name,
-        description: params.description,
-        endpoint_method: params.endpointMethod,
-        endpoint_url: params.endpointUrl,
-        endpoint_headers: params.endpointHeaders,
-        endpoint_timeout_ms: params.endpointTimeoutMs,
-        parameters: this.getParametersForBody(params.parameters)
-      }
+      body
     );
     return response;
   }
@@ -424,11 +438,14 @@ var Tools = class {
       {
         name: params.name,
         description: params.description,
+        type: params.type,
+        execution_mode: params.executionMode,
         endpoint_method: params.endpointMethod,
         endpoint_url: params.endpointUrl,
         endpoint_headers: params.endpointHeaders,
         endpoint_timeout_ms: params.endpointTimeoutMs,
-        parameters: this.getParametersForBody(params.parameters)
+        parameters: this.getParametersForBody(params.parameters),
+        tool_call_output_timeout_ms: params.toolCallOutputTimeoutMs
       }
     );
     return response;

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.26.1";
+var version = "0.27.0";
 
 // src/agents/index.ts
 var Agents = class {
@@ -262,6 +262,9 @@ var PhonicSTSWebSocket = class {
     this.onClose = this.onClose.bind(this);
     this.onError = this.onError.bind(this);
     this.audioChunk = this.audioChunk.bind(this);
+    this.sendToolCallOutput = this.sendToolCallOutput.bind(this);
+    this.updateSystemPrompt = this.updateSystemPrompt.bind(this);
+    this.setExternalId = this.setExternalId.bind(this);
     this.close = this.close.bind(this);
   }
   onMessageCallback = null;
@@ -269,6 +272,14 @@ var PhonicSTSWebSocket = class {
   onErrorCallback = null;
   buffer = [];
   isOpen = false;
+  processUserMessage(message) {
+    const messageStr = JSON.stringify(message);
+    if (this.isOpen) {
+      this.ws.send(messageStr);
+    } else {
+      this.buffer.push(messageStr);
+    }
+  }
   onMessage(callback) {
     this.onMessageCallback = callback;
   }
@@ -279,37 +290,32 @@ var PhonicSTSWebSocket = class {
     this.onErrorCallback = callback;
   }
   audioChunk({ audio }) {
-    const audiochunkMessage = JSON.stringify({
+    this.processUserMessage({
       type: "audio_chunk",
       audio
     });
-    if (this.isOpen) {
-      this.ws.send(audiochunkMessage);
-    } else {
-      this.buffer.push(audiochunkMessage);
-    }
+  }
+  sendToolCallOutput({
+    toolCallId,
+    output
+  }) {
+    this.processUserMessage({
+      type: "tool_call_output",
+      tool_call_id: toolCallId,
+      output
+    });
   }
   updateSystemPrompt({ systemPrompt }) {
-    const updateSystemPromptMessage = JSON.stringify({
+    this.processUserMessage({
       type: "update_system_prompt",
       system_prompt: systemPrompt
     });
-    if (this.isOpen) {
-      this.ws.send(updateSystemPromptMessage);
-    } else {
-      this.buffer.push(updateSystemPromptMessage);
-    }
   }
   setExternalId({ externalId }) {
-    const setExternalIdMessage = JSON.stringify({
+    this.processUserMessage({
       type: "set_external_id",
       external_id: externalId
     });
-    if (this.isOpen) {
-      this.ws.send(setExternalIdMessage);
-    } else {
-      this.buffer.push(setExternalIdMessage);
-    }
   }
   close(code) {
     this.ws.close(code ?? 1e3);
@@ -368,17 +374,25 @@ var Tools = class {
     return response;
   }
   async create(params) {
+    const body = {
+      name: params.name,
+      description: params.description,
+      type: params.type,
+      execution_mode: params.executionMode,
+      parameters: this.getParametersForBody(params.parameters)
+    };
+    if (params.type === "custom_webhook") {
+      body.endpoint_method = params.endpointMethod;
+      body.endpoint_url = params.endpointUrl;
+      body.endpoint_headers = params.endpointHeaders;
+      body.endpoint_timeout_ms = params.endpointTimeoutMs;
+    }
+    if (params.type === "custom_websocket") {
+      body.tool_call_output_timeout_ms = params.toolCallOutputTimeoutMs;
+    }
     const response = await this.phonic.post(
       "/tools",
-      {
-        name: params.name,
-        description: params.description,
-        endpoint_method: params.endpointMethod,
-        endpoint_url: params.endpointUrl,
-        endpoint_headers: params.endpointHeaders,
-        endpoint_timeout_ms: params.endpointTimeoutMs,
-        parameters: this.getParametersForBody(params.parameters)
-      }
+      body
     );
     return response;
   }
@@ -388,11 +402,14 @@ var Tools = class {
       {
         name: params.name,
         description: params.description,
+        type: params.type,
+        execution_mode: params.executionMode,
         endpoint_method: params.endpointMethod,
         endpoint_url: params.endpointUrl,
         endpoint_headers: params.endpointHeaders,
         endpoint_timeout_ms: params.endpointTimeoutMs,
-        parameters: this.getParametersForBody(params.parameters)
+        parameters: this.getParametersForBody(params.parameters),
+        tool_call_output_timeout_ms: params.toolCallOutputTimeoutMs
       }
     );
     return response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phonic",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Phonic Node.js SDK",
   "scripts": {
     "build": "tsup",