Documentation Index
Fetch the complete documentation index at: https://katavenai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
We’ll build a simple receptionist agent, attach it to a phone number,
and place a test call.
Prerequisites
- A Kataven account with the dashboard accessible.
- Bearer token + account slug (see Authentication).
- Python 3.10+ or Node 20+.
- Provider account (Twilio / Plivo / Vobiz) and at least one phone
number purchased on that provider.
pip install kataven # or: npm install @kataven/server
export KATAVEN_API_KEY="eyJhbGciOi..."
export KATAVEN_ACCOUNT_ID="acme"
1. Create the agent
from kataven import KatavenClient
client = KatavenClient()
agent = client.agents.create(
name="Front Desk",
description="Greets callers and routes them.",
status="active",
system_prompt=(
"You are the front desk for Acme Co. "
"Greet callers warmly. If they ask about pricing, refer them to "
"https://acme.com/pricing. If they need to book, use the "
"book_appointment tool."
),
greeting_message="Acme Co., how can I help you today?",
llm_model="gpt-4o",
voice_provider="cartesia",
voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",
)
print("Agent:", agent["id"])
2. Connect the carrier
Store your provider credentials (encrypted at rest):
provider = client.telephony.create_provider(
provider="twilio",
label="Production Twilio",
credentials={
"account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"auth_token": "your_auth_token",
},
)
3. Register the phone number
number = client.telephony.create_number(
e164="+12025550123",
provider="twilio",
credentials_id=provider["id"],
agent_id=agent["id"],
inbound_enabled=True,
outbound_enabled=True,
)
4. Place a test outbound call
result = client.calls.originate(
from_number="+12025550123",
to_number="+14155550100", # your own cell, for testing
agent_id=agent["id"],
)
print("Call dispatched:", result["provider_call_id"])
print("Watch live at:", f"https://hub.kataven.ai/conversations/{result['session_id']}")
5. Add knowledge
Attach a playbook of FAQs so the agent can answer common questions:
faq = client.faqs.create(
name="hours",
category="general",
title="What are your business hours?",
content="Mon–Fri 9am–6pm Pacific. Closed on US federal holidays.",
)
client.agents.attach_faq(agent["id"], faq["id"])
6. Watch a campaign run
If you have a CSV of leads:
with open("leads.csv", "rb") as f:
campaign = client.campaigns.create(
name="Cold outreach week 1",
agent_id=agent["id"],
phone_number_id=number["id"],
contacts=f,
max_concurrent_calls=3,
)
client.campaigns.start(campaign["id"])
for event in client.campaigns.stream_events(campaign["id"]):
metrics = event.get("metrics", {})
print(f"connected={metrics.get('connected')} "
f"completed={metrics.get('completed')} "
f"failed={metrics.get('failed')}")
What’s next
