Run the same voice AI agent over text chat

AI Agentsomnichannel AI agent (voice and text)

Point the AI Chat API at the URL your voice agent already serves. Create a conversation, send turns, read the log, summarise and end it, with one agent definition for both channels.

Also called AI Chat API, text channel for a voice AI agent, one agent, voice and chat

chatrest

The claim

An AgentBase serves a SWML document at its route, and a phone number fetches that document when a call arrives. The AI Chat API fetches the same document. You name a conversation and hand the platform the agent’s URL as config_url. Each chat request then runs one turn: the user’s message, the agent’s reply, and any tool calls made along the way. The prompt, the tools and the post prompt are the ones the voice channel uses, because they are the same object.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority.

Six methods travel over the one endpoint in a JSON-RPC 2.0 envelope: create_conversation, chat, end_conversation, delete, chat_log and summarize. The envelope requires jsonrpc, id, method and params.
create_conversation requires the conversation id and config_url, “the publicly reachable URL serving your agent’s SWML”; localhost and private addresses cannot be fetched. Its result carries initial_message when the agent greets first.
chat requires id and message. Its role is user or system, and “a system message steers the agent without appearing as something the user said”. The result is response, plus a user_event when a tool raised one.
end_conversation runs post-processing, which is where the post prompt fires; delete removes the conversation without it.
The token needs the chat scope, and a JSON-RPC error arrives inside an HTTP 200, so the HTTP layer does not raise for it.

Later SDK releases wrap this wire as signalwire.ai_chat.AIChatClient. The pinned 3.0.1 does not, so the recipe sends the envelopes through RestClient’s HTTP layer, the way the redact and SIP-address recipes do.

How it works

class FrontDesk(AgentBase):            # the agent a phone call reaches
    def __init__(self):
        super().__init__(name="front-desk", route="/front-desk")
        self.prompt_add_section("Role", "You answer for Ridgeline Cycles...")
        self.set_post_prompt("Summarise the conversation in one sentence.")

channel = TextChannel()                # six methods over client._http
made = channel.create(cid, config_url(agent))
print(made["initial_message"])
print(channel.say(cid, "When are you open?")["response"])
channel.end(cid)

What the platform receives for the first turn:

{"jsonrpc": "2.0", "id": "1f3a...", "method": "chat",
 "params": {"id": "text-9c41...", "message": "When are you open?"}}

config_url is the agent’s route with the trailing slash the SDK registers, on your public host, carrying the basic-auth pair from .env. The platform gets only the URL, so the credentials travel inside it, the same way the SDK builds its own webhook URLs.

Limitations

The verifier proves the envelopes and the document, not the model’s replies. What the agent says in a turn is live behaviour.

The agent has no tools here, so a turn is one model round trip. A tool webhook is fetched from your host during the turn, like a call; the URL has to be public for that too.

The service limits one request to 30 seconds and answers a slower turn with a 502, per the SDK’s client reference. A turn is measured in seconds.

What to change first

Add a tool to FrontDesk with define_tool and run the verifier. The document still validates and the envelopes do not change, because the tool belongs to the agent and not to the channel. Then send a question the tool answers and read the turn’s user_event.

Where this sits

Before this

Route a call to an AI agent

Remember a returning caller across calls Extract structured data after a call Create a hosted voice AI agent with one REST call

Put an AI agent in a web chat widget

Seen in a build

One of 8 recipes composed by Order status desk: one omnichannel AI agent for web chat and phone.

python/app.py

"""Run the same voice AI agent over text chat.

The agent below is the one a phone number reaches. The AI Chat API reaches it
too: `POST /api/ai/chat` takes a JSON-RPC 2.0 body whose `params.config_url`
is the URL this agent serves its SWML from, and SignalWire fetches the
definition server-to-server. One request is one turn. Six methods travel over
the one endpoint: `create_conversation`, `chat`, `end_conversation`, `delete`,
`chat_log` and `summarize` (the vendored REST spec, `tools/openapi/rest.json`).

`RestClient` in signalwire-sdk 3.0.1 wraps no method for this path, so the
requests go through its HTTP layer directly. Later SDK releases ship
`signalwire.ai_chat.AIChatClient` for the same wire.

Written against signalwire-sdk 3.0.1 (AgentBase, RestClient).

    python app.py serve     # the agent, at /front-desk/ behind basic auth
    python app.py chat      # a text conversation with it, from your terminal
"""
import os
import sys
import uuid
from urllib.parse import urlsplit, urlunsplit, quote

from dotenv import load_dotenv
from signalwire import AgentBase
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

CHAT = "/api/ai/chat"
ROUTE = "/front-desk"
ROLES = ("user", "system")   # the spec's enum for params.role on `chat`


class FrontDesk(AgentBase):
    """The agent a phone call reaches. Nothing here is chat-specific."""

    def __init__(self):
        super().__init__(name="front-desk", route=ROUTE)
        self.prompt_add_section("Role", "You answer for Ridgeline Cycles, a bike shop. "
                                        "Be brief and warm.")
        self.prompt_add_section("Hours", "Open Monday to Friday, nine to five, "
                                         "Eastern time. Closed weekends.")
        self.prompt_add_section("Limits", "You cannot book repairs. Offer the shop "
                                          "number for that.")
        self.set_post_prompt("Summarise the conversation in one sentence.")


def config_url(agent, public_base=None):
    """Where the platform fetches the agent's SWML: this agent's route, with a
    trailing slash, on your public host, carrying the basic-auth pair. The
    platform gets only the URL, so the credentials travel inside it."""
    base = public_base or os.environ["AGENT_PUBLIC_URL"]
    user, password = agent.get_basic_auth_credentials()
    parts = urlsplit(base)
    netloc = f"{quote(user, safe='')}:{quote(password, safe='')}@{parts.netloc}"
    path = parts.path.rstrip("/") + agent.route + "/"
    return urlunsplit((parts.scheme, netloc, path, "", ""))


class ChatError(Exception):
    """A JSON-RPC error. It arrives inside an HTTP 200, so the HTTP layer
    never raises for it; `code` is the service's number (-32001 is an unknown
    conversation, -32002 an unreachable config_url)."""

    def __init__(self, code, message):
        super().__init__(f"{code}: {message}")
        self.code = code


class TextChannel:
    """The six methods, each one POST with a JSON-RPC 2.0 envelope."""

    def __init__(self, http=None):
        self.http = http or client._http

    def rpc(self, method, params):
        body = {"jsonrpc": "2.0", "id": uuid.uuid4().hex, "method": method,
                "params": params}
        envelope = self.http.post(CHAT, body=body)
        if "error" in envelope:
            err = envelope["error"] or {}
            raise ChatError(err.get("code"), err.get("message", ""))
        return envelope.get("result", {})

    def create(self, cid, url, user_message=None, timeout=None):
        """A conversation you name. The result carries the agent's opening
        line in `initial_message` when the agent greets first."""
        params = {"id": cid, "config_url": url}
        if user_message:
            params["user_message"] = user_message
        if timeout:
            params["conversation_timeout"] = timeout
        return self.rpc("create_conversation", params)

    def say(self, cid, message, role="user"):
        """One turn. A `system` message steers the agent without appearing as
        something the user said; anything else is refused before it is sent."""
        if role not in ROLES:
            raise ValueError(f"role must be one of {ROLES}, not {role!r}")
        params = {"id": cid, "message": message}
        if role != "user":
            params["role"] = role
        return self.rpc("chat", params)

    def log(self, cid):
        return self.rpc("chat_log", {"id": cid}).get("chat_log", [])

    def summarize(self, cid, prompt=None):
        """A summary on demand. A failure rides the success envelope as
        `error`, so it is checked here rather than by `rpc`."""
        params = {"id": cid}
        if prompt:
            params["summary_prompt"] = prompt
        result = self.rpc("summarize", params)
        if "summary" not in result:
            raise ChatError(None, result.get("error", "no summary produced"))
        return result["summary"]

    def end(self, cid):
        """Ends the conversation and runs post-processing (the post_prompt)."""
        return self.rpc("end_conversation", {"id": cid})

    def delete(self, cid):
        """Removes the conversation with no post-processing."""
        return self.rpc("delete", {"id": cid})


def converse(channel, url, lines=input, out=print):
    """A terminal conversation: create, turns until 'bye', then end."""
    cid = "text-" + uuid.uuid4().hex
    made = channel.create(cid, url)
    if made.get("initial_message"):
        out("agent:", made["initial_message"])
    while True:
        text = lines("you: ").strip()
        if not text or text.lower() == "bye":
            break
        out("agent:", channel.say(cid, text)["response"])
    out("summary:", channel.summarize(cid))
    channel.end(cid)


agent = FrontDesk()

if __name__ == "__main__":
    if sys.argv[1:] == ["serve"]:
        agent.serve(port=int(os.getenv("PORT", "3000")))
    elif sys.argv[1:] == ["chat"]:
        converse(TextChannel(), config_url(agent))
    else:
        print(__doc__)

/**
 * Run the same voice AI agent over text chat.
 *
 * The agent below is the one a phone number reaches. The AI Chat API reaches
 * it too: `POST /api/ai/chat` takes a JSON-RPC 2.0 body whose
 * `params.config_url` is the URL this agent serves its SWML from, and
 * SignalWire fetches the definition server-to-server. One request is one
 * turn. Six methods travel over the one endpoint: `create_conversation`,
 * `chat`, `end_conversation`, `delete`, `chat_log` and `summarize`.
 *
 * `@signalwire/sdk` 2.0.5 wraps no method for this path, so the requests go
 * through the client's HTTP layer directly.
 *
 * Written against @signalwire/sdk 2.0.5 (AgentBase, RestClient).
 *
 *     npm start serve     # the agent, at /front-desk/ behind basic auth
 *     npm start chat      # a text conversation with it, from your terminal
 */
import "dotenv/config";
import { randomUUID } from "node:crypto";
import { createInterface } from "node:readline/promises";
import { AgentBase, RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();
type Http = { post(path: string, body: unknown): Promise<Envelope> };
const http = (client.chat as unknown as { _http: Http })._http;

export const CHAT = "/api/ai/chat";
export const ROUTE = "/front-desk";
export const ROLES = ["user", "system"] as const;   // the spec's enum for params.role
type Role = (typeof ROLES)[number];

type Envelope = {
  jsonrpc: "2.0"; id: string;
  result?: Record<string, unknown>;
  error?: { code?: number; message?: string } | null;
};

/** The agent a phone call reaches. Nothing here is chat-specific. */
export class FrontDesk extends AgentBase {
  constructor() {
    super({ name: "front-desk", route: ROUTE });
    this.promptAddSection("Role", { body: "You answer for Ridgeline Cycles, a bike shop. "
                                          + "Be brief and warm." });
    this.promptAddSection("Hours", { body: "Open Monday to Friday, nine to five, "
                                           + "Eastern time. Closed weekends." });
    this.promptAddSection("Limits", { body: "You cannot book repairs. Offer the shop "
                                            + "number for that." });
    this.setPostPrompt("Summarise the conversation in one sentence.");
  }
}

/**
 * Where the platform fetches the agent's SWML: this agent's route, with a
 * trailing slash, on your public host, carrying the basic-auth pair. The
 * platform gets only the URL, so the credentials travel inside it.
 */
export function configUrl(agent: AgentBase, publicBase?: string) {
  const base = new URL(publicBase ?? process.env["AGENT_PUBLIC_URL"] ?? "");
  const [user, password] = agent.getBasicAuthCredentials();
  base.username = encodeURIComponent(user);
  base.password = encodeURIComponent(password);
  base.pathname = base.pathname.replace(/\/$/, "") + agent.route + "/";
  base.search = "";
  return base.toString();
}

/**
 * A JSON-RPC error. It arrives inside an HTTP 200, so the HTTP layer never
 * throws for it; `code` is the service's number (-32001 is an unknown
 * conversation, -32002 an unreachable config_url).
 */
export class ChatError extends Error {
  constructor(public code: number | null, message: string) {
    super(`${code}: ${message}`);
  }
}

/** The six methods, each one POST with a JSON-RPC 2.0 envelope. */
export class TextChannel {
  constructor(private readonly transport: Http = http) {}

  async rpc(method: string, params: Record<string, unknown>) {
    const envelope = await this.transport.post(CHAT, {
      jsonrpc: "2.0", id: randomUUID().replace(/-/g, ""), method, params,
    });
    if ("error" in envelope) {
      const err = envelope.error ?? {};
      throw new ChatError(err.code ?? null, err.message ?? "");
    }
    return envelope.result ?? {};
  }

  /** A conversation you name. `initial_message` carries the agent's opening line. */
  create(cid: string, url: string, userMessage?: string, timeout?: number) {
    const params: Record<string, unknown> = { id: cid, config_url: url };
    if (userMessage) params["user_message"] = userMessage;
    if (timeout) params["conversation_timeout"] = timeout;
    return this.rpc("create_conversation", params);
  }

  /** One turn. A `system` message steers the agent without appearing as the user. */
  say(cid: string, message: string, role: Role = "user") {
    if (!ROLES.includes(role)) {
      throw new Error(`role must be one of ${ROLES.join(", ")}, not '${role}'`);
    }
    const params: Record<string, unknown> = { id: cid, message };
    if (role !== "user") params["role"] = role;
    return this.rpc("chat", params);
  }

  async log(cid: string) {
    return ((await this.rpc("chat_log", { id: cid }))["chat_log"] ?? []) as unknown[];
  }

  /** A summary on demand. A failure rides the success envelope as `error`. */
  async summarize(cid: string, prompt?: string) {
    const params: Record<string, unknown> = { id: cid };
    if (prompt) params["summary_prompt"] = prompt;
    const result = await this.rpc("summarize", params);
    if (!("summary" in result)) {
      throw new ChatError(null, String(result["error"] ?? "no summary produced"));
    }
    return result["summary"] as string;
  }

  /** Ends the conversation and runs post-processing (the post_prompt). */
  end(cid: string) { return this.rpc("end_conversation", { id: cid }); }

  /** Removes the conversation with no post-processing. */
  delete(cid: string) { return this.rpc("delete", { id: cid }); }
}

/** A terminal conversation: create, turns until 'bye', then end. */
export async function converse(channel: TextChannel, url: string) {
  const cid = "text-" + randomUUID().replace(/-/g, "");
  const rl = createInterface({ input: process.stdin, output: process.stdout });
  const made = await channel.create(cid, url);
  if (made["initial_message"]) console.log("agent:", made["initial_message"]);
  for (;;) {
    const text = (await rl.question("you: ")).trim();
    if (!text || text.toLowerCase() === "bye") break;
    console.log("agent:", (await channel.say(cid, text))["response"]);
  }
  console.log("summary:", await channel.summarize(cid));
  await channel.end(cid);
  rl.close();
}

export const agent = new FrontDesk();

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd] = process.argv.slice(2);
  if (cmd === "serve") {
    await agent.serve({ port: Number(process.env["PORT"] ?? 3000) });
  } else if (cmd === "chat") {
    await converse(new TextChannel(), configUrl(agent));
  } else {
    console.log("usage: npm start serve | npm start chat");
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, token with the chat scope, basic auth
python app.py serve              # the agent at /front-desk/

Expose the agent with a tunnel, set AGENT_PUBLIC_URL in .env to that host, and in a second terminal:

python app.py chat               # type; 'bye' summarises and ends

The TypeScript surface does the same on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start serve                  # and, in another terminal, npm start chat

Point a number at the same URL and the phone reaches the same agent.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier drives the agent’s real app with TestClient, swaps the SDK’s HTTP layer for a recorder, and asserts the following.

the app serves a document that validates, behind basic auth from the environment, and an unauthenticated request is a 401
the config URL is the agent’s route with a trailing slash on the public host, carrying the basic-auth pair
create, two chats, chat_log, summarize, end_conversation and delete each POST the documented path as a JSON-RPC 2.0 envelope with a unique request id
for every method the params carry the spec’s required fields and nothing the spec does not document, and the role enum is read from the spec
a role outside the enum is refused before any request is sent
an error envelope inside a 200 raises with its code, and a summary failure riding the success envelope raises rather than returning an empty string
the TypeScript surface serves the same document, builds the same URL, sends the same seven envelopes and refuses the same role

Report an issue