Tools enable your Phonic Agent to take actions beyond basic conversation, such as retrieving information or calling your functions. You can define your own custom tools, or use Phonic’s built-in tools for keypad input, hanging up, and transferring to another agent.

Tool Definition

Each tool is defined by its name, description, parameters, and timeout.

Each tool parameter has a name and description, and can be of type string, integer, number, boolean or array. This tool definition lets your agent understand what the tool does, when it should be called, and what arguments to call it with.

The timeout defines how long the agent should wait for a response before deeming the tool call as failed.

How these parameters are used depends on whether your tool is a Webhook or WebSocket tool.

Tool Types

Webhook Tools

When Webhook tools are called, an HTTP request is made to the endpoint associated with the tool. You may also provide headers for the Phonic Agent to call the endpoint with, such as an Authorization header. Webhook tools work whether you are running a conversation via Webhook or via WebSocket.

Currently GET and POST Webhook tools are supported. All parameters of a GET Webhook tool are placed in the query string, while with POST Webhook tools, parameters can be placed in the query string or request body.

Call Context Information

When Webhook tools are used with an Agent to make phone calls on Phonic’s infrastructure, call context information (call_info) will be automatically included in the HTTP request. This includes:

• conversation_id: The unique identifier for the current conversation
• from_phone_number: The caller’s phone number (when available)
• to_phone_number: The destination phone number (when available)

GET Webhook Request Format

For GET Webhook tools, call context and parameters are included as query string parameters:

Example GET Request:

GET /your-endpoint?city=Seattle&temperature_unit=celsius&conversation_id=conv_abc123&from_phone_number=%2B15551234567&to_phone_number=%2B15557654321

What your endpoint receives:

• Tool parameters: As query string parameters (e.g., city, temperature_unit)
• Call context: As individual query string parameters (conversation_id, from_phone_number, to_phone_number)

POST Webhook Request Format

For POST Webhook tools, the request body includes a call_info object along with your tool parameters:

Example POST Request Body:

1
{
2
    "call_info": {
3
        "conversation_id": "conv_abc123",
4
        "from_phone_number": "+15551234567",
5
        "to_phone_number": "+15557654321"
6
    },
7
    "city": "Seattle",
8
    "temperature_unit": "celsius"
9
}

What your endpoint receives:

• Tool parameters: At the root level of the JSON body (e.g., city, temperature_unit)
• Call context: In a nested call_info object

TypeScript Interface Examples

To handle webhook requests in your server, you can define interfaces like:

For GET Webhooks:

1
// Query parameters your endpoint will receive
2
interface GetWeatherWebhookParams {
3
  // Your tool parameters
4
  city: string;
5
  temperature_unit?: string;
6
7
  // Call context (automatically added by Phonic)
8
  conversation_id: string;
9
  from_phone_number?: string;
10
  to_phone_number?: string;
11
}

For POST Webhooks:

1
// Request body your endpoint will receive
2
interface PostWeatherWebhookBody {
3
  // Call context (automatically added by Phonic)
4
  call_info: {
5
    conversation_id: string;
6
    from_phone_number?: string;
7
    to_phone_number?: string;
8
  };
9
10
  // Your tool parameters
11
  city: string;
12
  temperature_unit?: string;
13
}

Note: The call_info parameter name is reserved and cannot be used as a custom tool parameter.

Here’s how to create a Webhook tool in the SDK:

1
import { config } from "dotenv";
2
import { PhonicClient } from "phonic";
3
4
config({ path: ".env.local" });
5
6
const apiKey = process.env.PHONIC_API_KEY;
7
const client = new PhonicClient({ apiKey });
8
9
async function createTool() {
10
  await client.tools.create({
11
    name: "add_destination",
12
    description:
13
      "Add a destination to the list when the user indicates they will visit it.",
14
    type: "custom_webhook",
15
    execution_mode: "sync",
16
    endpoint_method: "POST",
17
    endpoint_url: `https://${NGROK_URL.replace("https://", "")}/webhooks/add-destination`,
18
    endpoint_timeout_ms: 7000,
19
    parameters: [
20
      {
21
        name: "destination_name",
22
        description: "The name of the destination",
23
        is_required: true,
24
        type: "string",
25
      },
26
    ],
27
  });
28
}
29
30
createTool()

WebSocket Tools

WebSocket tools allow you to run tools on your server when running a conversation via WebSocket.

When the Phonic Agent makes a tool call, it sends a message with the following schema over the WebSocket:

1
{
2
  "type": "tool_call",
3
  "tool_call_id": "string",
4
  "tool_name": "string", 
5
  "parameters": {
6
    // Parameters passed to tool execution
7
    // Map from parameter names to values
8
  }
9
}

The tool call should be responded to with a message of the following type:

1
{
2
  type: "tool_call_output";
3
  tool_call_id: string; // The ID from the tool_call message
4
  output: unknown; // The result of executing the tool, can be any JSON-serializable object
5
}

Here’s how to create a WebSocket tool in the SDK:

1
import { PhonicClient } from "phonic";
2
3
const apiKey = process.env.PHONIC_API_KEY;
4
const client = new PhonicClient({ apiKey });
5
6
async function createTool() {
7
  await client.tools.create({
8
    name: "get_temperature",
9
    description:
10
      "Get the current temperature and weather conditions for a specific city.",
11
    type: "custom_websocket",
12
    execution_mode: "sync",
13
    parameters: [
14
      {
15
        type: "string",
16
        name: "city",
17
        description: "The name of the city to get the temperature for",
18
        is_required: true,
19
      },
20
    ],
21
  });
22
}
23
24
createTool()

Built-in Tools

Phonic provides built-in tools that work seamlessly while handling calls with Phonic’s infrastructure.

Keypad Input (DTMF)

Keypad Input allows the Phonic Agent to press keypad buttons including digits (0-9) and special keys (#, *, A, B, C, D).

Phonic uses out-of-band DTMF (RFC 4733) signaling with our telephony integration.

When creating a Phonic Agent or making an outbound call via the SDK, include keypad_input in the list of tools.

When using the Keypad Input tool while running a conversation via WebSockets, you will need to handle the dtmf message on your infrastructure.

Natural Conversation Ending

The Natural Conversation Ending tool allows the Phonic Agent to hang up.

When creating a Phonic Agent or making an outbound call via the SDK, include natural_conversation_ending in the list of tools.

When using the Keypad Input tool while running a conversation via WebSockets, you will need to handle the assistant_ended_conversation message on your infrastructure.

Call Transfer

The Call Transfer tool allows the Phonic Agent to transfer calls to another phone number, such as a to a human, or even another Phonic Agent.

Here’s how to create a Call Transfer tool in the SDK:

1
import { PhonicClient } from "phonic";
2
3
const apiKey = process.env.PHONIC_API_KEY;
4
const client = new PhonicClient({ apiKey });
5
6
async function createTool() {
7
  await client.tools.create({
8
    name: "transfer_to_support",
9
    description: "Transfers the call to the support team",
10
    type: "built_in_transfer_to_phone_number",
11
    execution_mode: "sync",
12
    phone_number: "+15551234567", // E.164 format
13
  });
14
}
15
16
createTool()

When creating a Phonic Agent or making an outbound call via the SDK, include the name of your call transfer tool in the list of tools.

Async vs Sync Tools

Tools can operate in two modes:

• Sync: The agent waits for the tool to complete before continuing the conversation. Once the tool call output is received, the agent will use the information returned to generate a response for the user. However, if the user speaks while the tool is executing, the tool call will be interrupted. This is useful for tools that return information quickly.
• Async: The agent continues the conversation without waiting for the tool to complete. Async tools are not subject to interruption. This is useful for background tasks that don’t need to block the conversation, such as adding information to a database, or retrieving information that may be useful later in the conversation. Async tool outputs are added to the agent context upon receipt, but does not immediately trigger a response.

Currently, only custom_websocket tools support async mode. Webhook tools and built-in tools only support sync mode.

Using Tools with Your Agents

Once you’ve created tools, you can use them with your agents by including the tool names in the tools array when creating or updating an agent.

1
await client.agents.create({
2
  name: "support-agent",
3
  tools: [
4
    "keypad_input",
5
    "natural_conversation_ending",
6
    "transfer_to_support",
7
    "book_appointment",
8
  ],
9
  // ... other agent configuration
10
});

If you have included WebSocket tools in your agent, visit our WebSocket Tools guide to see how to handle these tools!