Skip to main content

​
Calls

Ringyo AI can handle both inbound and outbound phone calls. This guide covers how calls work and how to manage them.

​
Call Types

​
Inbound Calls

When someone calls your Ringyo AI phone number:
  1. Call is answered by your voice agent
  2. Agent greets the caller
  3. Conversation happens naturally
  4. Agent can book appointments, answer questions, or transfer
  5. Call ends and you receive a webhook with details

​
Outbound Calls

Make calls programmatically via API: 
curl https://api.ringyo.ai/v1/calls \
  -X POST \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "agent_id": "agent_xyz",
    "context": {
      "customer_name": "John Smith",
      "purpose": "appointment_reminder",
      "appointment_date": "January 20th at 2 PM"
    }
  }'

​
Call Context

Pass context to personalize the conversation: 
{
  "context": {
    "customer_name": "John Smith",
    "customer_type": "returning",
    "last_visit": "December 15th",
    "purpose": "follow_up",
    "notes": "Interested in teeth whitening"
  }
}
Your agent can use this context naturally:
“Hello John! I’m following up on your visit in December. I remember you were interested in our teeth whitening services…”

​
Call Lifecycle

initiated → ringing → answered → in_progress → completed
                                             → transferred
                         → no_answer
                         → busy
                         → failed

​
States

StateDescription
initiatedCall started, dialing
ringingPhone is ringing
answeredCall connected
in_progressConversation happening
completedCall ended normally
transferredTransferred to human
no_answerNo answer after timeout
busyLine busy
failedTechnical failure

​
Call Results

After a call ends, you get detailed results: 
{
  "call_id": "call_abc123",
  "status": "completed",
  "duration_seconds": 145,
  "outcome": "appointment_booked",
  "transcript": "Agent: Hello! Thanks for calling...\nCustomer: Hi, I'd like to book...",
  "recording_url": "https://...",
  "extracted_data": {
    "appointment_date": "2024-01-20",
    "appointment_time": "14:00",
    "service": "dental_cleaning"
  },
  "sentiment": {
    "overall": "positive",
    "score": 0.85
  }
}

​
Outcomes

Common call outcomes:
OutcomeDescription
appointment_bookedSuccessfully booked appointment
information_providedAnswered caller’s questions
callback_requestedCaller wants a callback
transferredTransferred to human
voicemail_leftLeft voicemail
no_actionCall ended without action

​
Transcripts

Every call generates a transcript: 
[00:00] Agent: Hello! Thanks for calling Acme Dental. This is Sarah. How can I help you today?

[00:05] Customer: Hi Sarah, I'd like to schedule a cleaning appointment.

[00:08] Agent: I'd be happy to help you schedule that! What day works best for you?

[00:12] Customer: Do you have anything available next Tuesday afternoon?

[00:15] Agent: Let me check... Yes! I have 2 PM and 3:30 PM available next Tuesday. Which would you prefer?

​
Recordings

Calls are recorded by default (can be disabled). Access recordings: 
curl https://api.ringyo.ai/v1/calls/call_abc123 \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY"
Response includes recording_url for the audio file.
Ensure you comply with call recording laws in your jurisdiction. Some regions require two-party consent.

​
Bulk Calls (Campaigns)

Make multiple calls with a campaign: 
curl https://api.ringyo.ai/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer vb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminders",
    "agent_id": "agent_xyz",
    "contacts": [
      {"phone": "+1234567890", "context": {"name": "John", "appointment": "Monday 2pm"}},
      {"phone": "+0987654321", "context": {"name": "Jane", "appointment": "Monday 3pm"}}
    ],
    "settings": {
      "max_concurrent": 5,
      "retry_no_answer": true,
      "schedule": "2024-01-15T09:00:00Z"
    }
  }'

​
Handling Transfer

When a caller asks to speak to a human:
  1. Agent acknowledges the request
  2. Plays hold music/message
  3. Dials your transfer number
  4. Connects caller to human
  5. Webhook sent with transferred status
Configure transfer settings: 
{
  "transfer_enabled": true,
  "transfer_number": "+1234567890",
  "transfer_message": "One moment while I connect you with a team member."
}

​
Pricing

Calls are billed based on duration:
  • Outbound calls: Charged per minute connected
  • Inbound calls: Charged per minute connected
  • Credits deducted from your balance
Check your usage in Dashboard → Billing.

​
Best Practices

  1. Test before bulk calling — Make test calls to verify agent behavior
  2. Respect calling hours — Don’t call late at night or early morning
  3. Include context — Personalized calls are more effective
  4. Handle failures — Set up retry logic for no-answers
  5. Monitor outcomes — Use webhooks to track results

​
Next Steps