Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
End-to-end: Outbound calling bot

A complete walkthrough — from zero to a working agent that calls leads, captures their info, and books demos. Every step in one place.

​
What you’re building

An AI agent that:
  1. Calls a lead by name
  2. Qualifies them and captures their details
  3. Books a demo if they’re interested
  4. Transfers to a human if they ask

​
Before you start

You need:

​
Step 1 — Create the agent

curl -X POST https://api.oneinbox.ai/v1/agents \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Bot",
    "language": "en",
    "first_message": "Hi {{lead_name}}, this is Aria from Acme. I'\''m reaching out about our product — do you have two minutes?",
    "silence_timeout_seconds": 10,
    "max_duration_seconds": 300,
    "enable_recording": true,
    "voicemail_detection": true,
    "voicemail_message": "Hi {{lead_name}}, this is Aria from Acme. Please call us back at 555-0100 — we'\''d love to chat."
  }'
Save both IDs from the response: 
{
  "id": "agt_abc123",
  "llm_id": "llm_xyz789"
}
  • id — the agent (voice, language, call behavior)
  • llm_id — the AI brain (what it knows, what it can do). They’re separate so multiple agents can share one brain — update the brain once, all agents using it pick up the change.
{{lead_name}} is a variable. You pass the value when you start each call — so you don’t need a separate agent per lead.

​
Step 2 — Give it a personality

The default system prompt is a general assistant. Replace it with a script for your use case: 
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "system_prompt": "You are Aria, a friendly sales rep for Acme Corp. Your goal is to introduce our product, qualify the lead, and book a 30-minute demo if they are interested.\n\nGuidelines:\n- Keep replies short — one or two sentences\n- If they ask what Acme does: we help teams automate customer outreach with AI voice agents\n- Qualify by asking: their company size, current tool, and biggest pain point\n- If they want a demo, use the book_demo tool\n- If they want to talk to a human, use transfer_to_human\n- If they are not interested, thank them and use end_call",
    "temperature": 0.6
  }'

​
Step 3 — Add tools

Create each tool, then attach all of them to the llm_id in one PATCH.

​
Create the tools

# 1. Capture lead info
curl -X POST https://api.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "capture_lead",
    "type": "extract_information",
    "description": "Extract lead qualification data once the caller has answered the qualifying questions.",
    "extraction_schema": {
      "fields": [
        { "name": "company_name", "type": "string", "required": true, "description": "Name of their company" },
        { "name": "team_size", "type": "string", "description": "Number of people in their team" },
        { "name": "pain_point", "type": "string", "description": "Their main challenge or pain point" }
      ]
    }
  }'

# 2. Book a demo
curl -X POST https://api.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "book_demo",
    "type": "schedule_calendar_event",
    "description": "Book a 30-minute demo when the caller agrees to a meeting.",
    "calendar_config": {
      "calendar_id": "primary",
      "duration_minutes": 30,
      "timezone": "America/New_York"
    }
  }'

# 3. Transfer to human
curl -X POST https://api.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "transfer_to_human",
    "type": "transfer_call",
    "description": "Transfer to a human agent when the caller asks to speak to a person.",
    "transfer_to": "+15105550100"
  }'

# 4. End call cleanly
curl -X POST https://api.oneinbox.ai/v1/tools \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "end_call",
    "type": "end_call",
    "description": "End the call after the task is done or the caller says goodbye."
  }'

​
Attach all tools to the LLM model

This step is what makes tools available to your agent. Creating tools without attaching them does nothing — the agent has no idea they exist until you run this PATCH.
curl -X PATCH https://api.oneinbox.ai/v1/models/<llm_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_ids": ["<capture_lead_id>", "<book_demo_id>", "<transfer_id>", "<end_call_id>"]
  }'

​
Step 4 — Register your phone number

Register the phone number your agent will call from. You need SIP credentials from your provider — see How to get SIP credentials. 
curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15739693824",
    "friendly_name": "Sales Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "provider_config": {
      "trunk_address": "<your_sip_trunk_domain>",
      "auth_username": "<sip_username>",
      "auth_password": "<sip_password>"
    }
  }'

​
Step 5 — Make a call

Pass variables to fill in the {{lead_name}} placeholder in first_message: 
curl -X POST https://api.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "variables": {
      "lead_name": "Priya"
    }
  }'

{
  "id": "call_abc123",
  "status": "initiated"
}

​
Step 6 — Read the results

After the call ends: 
# 1. Stop the call (if not already ended by the agent)
curl -X POST https://api.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"

# 2. Wait 2–3 seconds, then fetch
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 124,
  "analysis": {
    "outcome": "Appointment Booked",
    "summary": "Priya agreed to a 30-minute demo on Thursday. She runs a team of 12 and is currently using spreadsheets."
  },
  "messages": [
    { "role": "agent", "content": "Hi Priya, this is Aria from Acme..." },
    { "role": "user", "content": "Yes, I've been looking for something like this..." }
  ],
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3"
}

​
What’s next

  • Web calls — embed a voice widget on your site instead of calling out
  • Webhooks — get notified the moment a call ends instead of polling
  • Knowledge bases — give your agent a product FAQ to answer questions from
  • Call outcomes — filter and report on results at scale