Conversations via Webhooks

The simplest way to run a conversation with Phonic is via webhooks — start a conversation with a single function call, and let Phonic orchestrate telephony for you.

This guide walks through your first webhook conversation, then covers two more advanced features. The example code is available here and here.

1. Install the SDK

1
npm install phonic

See TypeScript SDK or Python SDK for more on the client.

2. Initialize the client

1
import { PhonicClient } from "phonic";
2
import { config } from "dotenv";
3
4
config({ path: ".env.local" });
5
6
const client = new PhonicClient({
7
  apiKey: process.env.PHONIC_API_KEY,
8
});

3. Create an agent

Let’s create an agent and assign it a random phone number.

1
await client.agents.create({
2
  name: "my-first-agent",
3
  phone_number: "assign-automatically",
4
});

You should see now my-first-agent on the Agents page.

4. Make an outbound call

Let’s make the agent call you. Specify your phone number, the agent name, and a welcome message:

1
await client.conversations.outboundCall({
2
  to_phone_number: "YOUR_PHONE_NUMBER", // e.g. +19189391262
3
  config: {
4
    agent: "my-first-agent",
5
    welcome_message: "Hello, how can I help you?",
6
  }
7
});

Now, pick up the phone and chat with your agent!

5. Make an inbound call

Grab the agent’s phone number on the Agents page, and give it a call!

Agent configuration endpoint

Typically, when you create an agent with Phonic you specify default values for its behavior, such as its welcome message and system prompt. With the agent configuration endpoint, you have the option at the start of every conversation to update your agent with conversation-specific information.

This is primarily useful for inbound calls; for example, your endpoint can look up the inbound caller in your CRM and populate your welcome message with the caller information.

At the start of every conversation, Phonic sends a POST request to your endpoint, and your endpoint returns configuration overrides for that conversation. See the Agent configuration endpoint reference for the full request and response payload shapes.

Implementing your configuration endpoint is easy:

1
import { Hono } from "hono";
2
3
const app = new Hono();
4
5
app.post("/webhooks/agent-config", async (c) => {
6
  const body = (await c.req.json()) as Phonic.PhonicConfigurationEndpointRequestPayload;
7
  const fromPhoneNumber = body.from_phone_number;
8
  const fromCustomerName = lookUpCustomerName(fromPhoneNumber);  // look up customer in your CRM
9
  const response: Phonic.PhonicConfigurationEndpointResponsePayload = {
10
    welcome_message: `Hey ${fromCustomerName}, how can I help you today?`,
11
  };
12
  return c.json(response);
13
});

Post-call analysis endpoint

Upon the completion of each conversation, you can report conversation information, such as the full transcript, system prompt, and start/end timestamps. Implementing this is also easy:

1
import { Hono } from "hono";
2
3
const app = new Hono();
4
5
app.post("/webhooks/post-call", async (c) => {
6
    const body = await c.req.json();
7
    save_conversation(body);  // save conversation information to your database
8
    return c.json({ message: "OK" });
9
});