---
name: acp-business-line
title: "Turn a phone number into an AI business line with the Telnyx Agent Control Plane"
description: "Declare a clinic appointment-intake agent in configuration — agent.json plus instructions.md, no application code — and answer calls and texts on one number with the Agent Control Plane."
language: acp
framework: agent-control-plane
telnyx_products: [Agent Control Plane, AI Inference, Voice AI]
channel: [voice, sms]
---
# Turn a phone number into an AI business line with the Telnyx Agent Control Plane
> **Beta.** The Agent Control Plane is in beta; behavior and CLI flags can change between releases. See the [beta limitations](https://developers.telnyx.com/docs/agents/beta-limitations).
A clinic's website lists one phone number. In this example that number becomes an AI agent: it answers calls with a greeting, takes an appointment request (name, reason, preferred time), confirms it back, and hands off to the front desk — and it answers texts on the same number. There is no application code anywhere: the whole agent is one `agent.json` and one `instructions.md`, deployed with the `telnyx-acp` CLI.
## Why Telnyx
Telnyx is an **AI Communications Infrastructure** platform — voice, messaging, and AI inference run on the same private network, so a config-declared agent can answer live calls and texts with hosted STT, TTS, and models, without stitching together third-party providers.
## Telnyx API Endpoints Used
This example ships configuration, not code — the Agent Control Plane wires these endpoints for you when you run `telnyx-acp deploy`:
- **Telnyx Inference**: `POST /v2/ai/chat/completions` with the declared model (`zai-org/GLM-5.3-Flash`) — [API reference](https://developers.telnyx.com/api/inference/chat-completions)
- **Agent Memory**: conversation profiles per caller — [API reference](https://developers.telnyx.com/api-reference/agent-memory)
- **Call Control**: one application created and wired by `deploy` — [API reference](https://developers.telnyx.com/api-reference/call-control)
- **Messaging Profile**: one profile created and wired by `deploy` — [API reference](https://developers.telnyx.com/api-reference/messaging)
## Architecture
```
Inbound call or text
│
▼
┌─────────────────────┐
│ Telnyx number │ deploy wires Call Control app + messaging profile
└──────────┬──────────┘
▼
┌─────────────────────┐ agent.json ┌────────────────────┐
│ Edge Compute function│ ◄────────────────────│ acp-business-line/ │
│ (one instance per │ instructions.md └────────────────────┘
│ conversation) │
└──────────┬──────────┘
▼
┌─────────────────────┐
│ GLM-5.3-Flash │ reply streamed sentence-by-sentence to TTS
│ Telnyx STT / TTS │ texts reply over the messaging profile
└──────────┬──────────┘
▼
┌─────────────────────┐
│ Agent Memory │ profile per conversation — the caller's
└─────────────────────┘ history comes back on their next call or text
```
One conversation is one instance: a text conversation is keyed by the sender's phone number (one instance per phone, kept across every text it sends); a call runs on its own per-call instance. Agent Memory is what joins the same person's calls and texts together.
## Environment Variables
| Variable | Type | Example | Required | Description | Where to get it |
|----------|------|---------|----------|-------------|-----------------|
| `TELNYX_API_KEY` | `string` | `KEY0123456789ABCDEF` | **yes** | Telnyx API v2 key — used by `telnyx-acp dev` for model calls, and by scripts/CI instead of `telnyx-acp login` | [Portal](https://portal.telnyx.com/api-keys) · [CLI: `telnyx auth`](https://developers.telnyx.com/development/cli) |
> **Agent / CLI access** — provision resources programmatically with the [Telnyx CLI](https://developers.telnyx.com/development/cli):
>
> ```bash
> telnyx auth login
> telnyx available-phone-numbers list --country US --features sms,voice
> telnyx number-orders create --phone-number +15551234567
> telnyx messaging-profiles create --name "clinic-line"
> ```
>
> Full API discovery: [llms-full.txt](https://developers.telnyx.com/llms-full.txt) · [CLI docs](https://developers.telnyx.com/development/cli)
## Setup
```bash
git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/acp-business-line
cp .env.example .env # ← fill in your credentials
# Prerequisites: Node.js >= 22.13 and telnyx-edge >= 0.5.7 on your PATH
npm install -g @telnyx/acp
telnyx-acp validate # checks agent.json; every problem names the field and the fix
telnyx-acp dev # runs the agent on http://127.0.0.1:8787
```
In a second terminal, talk to it locally:
```bash
telnyx-acp chat --local
```
Deploy it and give it a number:
```bash
telnyx-acp numbers # lists numbers in your account
telnyx-acp add phone +15550001234 # voice- and messaging-enabled number
telnyx-acp deploy --dry-run # the plan; writes nothing
telnyx-acp deploy # builds (first build ≈ 10 min), wires the number
telnyx-acp status # function, revision, numbers, webhook health
```
Programmatic / CLI setup
```bash
# Install CLI — https://developers.telnyx.com/development/cli
go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest
telnyx auth login
# Provision resources
telnyx available-phone-numbers list --country US --features sms
telnyx number-orders create --phone-number +15551234567
```
For full API discovery, point your agent at [`llms-full.txt`](https://developers.telnyx.com/llms-full.txt).
The first `deploy` registers the agent and builds it (about ten minutes; `deploy` waits up to 25). Every `deploy` after that is a new revision — `telnyx-acp versions acp-business-line` lists them. To remove everything the agent created: `telnyx-acp delete acp-business-line`.
## API Reference
The agent answers at one address over three transports (WebSocket, SSE, RPC). Under `dev` that is `http://127.0.0.1:8787/agents/acp-business-line/`; deployed it is the mount URL `https://.telnyxcompute.com/agents/acp-business-line/`.
| Surface | Command | What it does |
|---------|---------|--------------|
| One turn | `telnyx-acp invoke acp-business-line --conversation --local "hi"` | One text turn against `dev` (`--local`) or the deployed agent |
| Conversation | `telnyx-acp chat --local` / `telnyx-acp chat` | Interactive conversation, local or deployed |
| One SMS | `telnyx-acp text "what times do you have?"` | Sends an SMS from one of your account's numbers to the agent's number and prints the reply — both numbers are Telnyx's, so no 10DLC registration is needed |
| Status | `telnyx-acp status` | Function, revision, each number, webhook health |
| Logs | `telnyx-acp logs --since 10m` | One JSON line per runtime event (`voiceCall`, `voiceTurn`, `modelStream`, `voiceFiller`, …) |
| Traces | `telnyx-acp traces [run]` | Run waterfall: model calls with tokens, tool calls, delivery, timings |
`voice.greeting` is spoken verbatim the moment a call is answered. Each turn of the reply is streamed to TTS sentence-by-sentence, so the caller hears the first words in about a second.
## Demo Script (2–3 minute recording)
1. *"This is the number on our website. Watch it become an agent."*
2. Show `instructions.md` and `agent.json` — two files, no code.
3. Run one local interaction: `telnyx-acp chat --local`, book an intake.
4. Deploy is already done — show the plan: `telnyx-acp deploy --dry-run`.
5. Place one call to the number; let the greeting and intake run. Send one text (`telnyx-acp text`).
6. Show the logs: `telnyx-acp logs --since 5m` (call the out `voiceTurn` lines).
7. Open the trace of the text interaction: `telnyx-acp traces ` — walk the model and memory steps.
8. Close: *"One agent, calls and texts, with no application code."*
Record call audio on a second device if needed, and check the beta limitations before making product claims.
## Troubleshooting
| Issue | Cause | Fix |
|-------|-------|-----|
| `You are not signed in.` (exit 4) from `telnyx-acp models` | No CLI session and no `TELNYX_API_KEY` | Run `telnyx-acp login`, or set `TELNYX_API_KEY` in `.env` |
| `telnyx-edge is not installed or not on PATH` (exit 3) | Missing or old `telnyx-edge` | Install version ≥ 0.5.7 from its releases, or point `TELNYX_EDGE_BIN` at a copy |
| A call connects but stays silent | Recognition, model, or synthesis failed mid-turn | `telnyx-acp logs --since 5m`: a `voiceCall` line with `streaming.failed` names the platform's reason; a non-`completed` `voiceTurn` outcome names the stage |
| A text from a phone got no reply | The agent's number is not 10DLC-registered (error `40010`), or the sender is outside the US | Register the number under a 10DLC campaign in Mission Control, or test with `telnyx-acp text`, which needs no 10DLC |
| `telnyx-acp add phone` fails at `deploy` | Number missing from the account or not yet active | Check `telnyx-acp numbers`; buy in [Mission Control → Numbers → Search & Buy](https://portal.telnyx.com/#/app/numbers/search-numbers) |
| Deployed `invoke` says it is waiting for approval | An `ask` approval was configured (not in this example) | Beta: `ask` works under `dev` only — `telnyx-acp unset approvals.` and redeploy |
## Related Examples
- [Build a complete voice AI agent with Telnyx (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/build-voice-ai-agent-python/README.md)
- [Route phone calls to an AI agent (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/route-phone-calls-to-ai-agent-python/README.md)
- [AI SMS triage bot (Agent SDK, Node.js)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/agent-sms-triage-bot/README.md)
- [Voice IVR with an agent backend (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/voice-ivr-with-agent-backend/README.md)
## Agent Discovery
This example is part of the [Telnyx Code Examples](https://github.com/team-telnyx/telnyx-code-examples) catalog.
- **Agent signup**: [telnyx.com/agent-signup.md](https://telnyx.com/agent-signup.md) — automated account provisioning via agent mail; get an API key with no human intervention
- **Agent CLI**: [github.com/team-telnyx/ai/tree/main/cli](https://github.com/team-telnyx/ai/tree/main/cli) — composite commands for agents ([commands reference](https://github.com/team-telnyx/ai/tree/main/cli/src/commands))
- **Agent skills**: [github.com/team-telnyx/ai/tree/main/skills](https://github.com/team-telnyx/ai/tree/main/skills)
- **Telnyx AI repo**: [github.com/team-telnyx/ai](https://github.com/team-telnyx/ai)
- **LLM-optimized docs**: [`llms-full.txt`](https://developers.telnyx.com/llms-full.txt)
- **Example index**: [`llms.txt`](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/llms.txt)
- **Telnyx CLI (human)**: [developers.telnyx.com/development/cli](https://developers.telnyx.com/development/cli) — `go install github.com/team-telnyx/telnyx-cli/cmd/telnyx@latest`
## Resources
- [Agent Control Plane overview](https://developers.telnyx.com/docs/agents)
- [Agent Control Plane — getting started](https://developers.telnyx.com/docs/agents/get-started)
- [`agent.json` reference](https://developers.telnyx.com/docs/agents/reference/agent-json)
- [Voice configuration](https://developers.telnyx.com/docs/agents/voice)
- [Agent Control Plane beta limitations](https://developers.telnyx.com/docs/agents/beta-limitations)
- [`telnyx-acp` CLI reference](https://developers.telnyx.com/docs/agents/cli)
- [Voice AI product page](https://telnyx.com/products/voice-ai-agents)
- [Telnyx pricing](https://telnyx.com/pricing)