Handling Inbound Calls

The Audian API provides comprehensive tools for receiving and processing inbound calls. You can route calls to different destinations, present IVR menus, record conversations, and integrate with your systems.

Inbound Call Basics

When an inbound call arrives at one of your Audian phone numbers, it can be:

1. Automatically routed based on a call flow
2. Answered and controlled via your application
3. Handled by IVR menus you define
4. Forwarded to external numbers

Setting Up Call Flows

Call flows define how inbound calls are handled:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Line",
    "phone_number": "+14155552671",
    "routing": [
      {
        "pattern": "*",
        "destination": "ivr_main",
        "destination_type": "ivr_menu"
      }
    ]
  }'

Response:

{
  "call_flow_id": "cf_abc123",
  "name": "Support Line",
  "phone_number": "+14155552671",
  "routing": [
    {
      "pattern": "*",
      "destination": "ivr_main",
      "destination_type": "ivr_menu"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

Call Flow Parameters

Required Parameters

Parameter	Type	Description
name	string	Name for this call flow
routing	array	Array of routing rules

Optional Parameters

Parameter	Type	Description
phone_number	string	Specific phone number this flow applies to
description	string	Detailed description
active	boolean	Whether this flow is active (default: true)

Routing Rules

Define how calls are routed with routing rules:

{
  "pattern": "PATTERN",
  "destination": "DESTINATION_ID",
  "destination_type": "DESTINATION_TYPE",
  "conditions": { /* optional conditions */ }
}

Routing Pattern Matching

Patterns determine which calls this rule matches:

Pattern	Matches
*	Any call (catch-all)
1	Calls where caller pressed key 1
2	Calls where caller pressed key 2
[0-9]	Any single digit
1[0-9]	Calls where first digit is 1, any second digit

Destination Types

Type	Description	Example
ivr_menu	IVR menu to present	ivr_main
phone_number	External phone number	+14155552673
voicemail	Voicemail system	voicemail_default
queue	Call queue	queue_support
webhook	Webhook URL	https://example.com/calls

Simple Call Routing

Route all calls to a specific phone number:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Direct Line",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Time-Based Routing

Route calls differently based on time of day:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number",
        "conditions": {
          "time_range": {
            "start": "09:00",
            "end": "17:00",
            "timezone": "America/New_York",
            "days": ["MON", "TUE", "WED", "THU", "FRI"]
          }
        }
      },
      {
        "pattern": "*",
        "destination": "voicemail_default",
        "destination_type": "voicemail"
      }
    ]
  }'

IVR-Based Routing

Present an IVR menu and route based on selection:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Menu",
    "routing": [
      {
        "pattern": "*",
        "destination": "ivr_support_menu",
        "destination_type": "ivr_menu"
      },
      {
        "pattern": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "pattern": "2",
        "destination": "+14155552674",
        "destination_type": "phone_number"
      },
      {
        "pattern": "3",
        "destination": "voicemail_default",
        "destination_type": "voicemail"
      }
    ]
  }'

Webhook-Based Routing

Forward call information to your webhook for dynamic routing:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "https://your-api.example.com/route-call",
        "destination_type": "webhook"
      }
    ]
  }'

Your webhook receives:

{
  "call_id": "call_xyz789",
  "from": "+14155552672",
  "to": "+14155552671",
  "call_type": "inbound",
  "timestamp": "2024-01-15T10:30:00Z"
}

Respond with the routing decision:

{
  "destination": "+14155552673",
  "destination_type": "phone_number",
  "tags": {
    "routed_by": "webhook",
    "queue": "support"
  }
}

Handling Missed Calls

Configure fallback routing for when primary destination fails:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fallback Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number",
        "fallback": {
          "timeout": 30,
          "action": "voicemail",
          "action_id": "voicemail_default"
        }
      }
    ]
  }'

Caller ID Screening

Block or route calls based on caller ID:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Screened Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "voicemail_default",
        "destination_type": "voicemail",
        "conditions": {
          "blocked_numbers": ["+14155552699", "+14155552698"]
        }
      },
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Programmatic Call Control

Handle calls with webhooks for custom logic:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/answer \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "play_audio",
    "message": "Thank you for calling. You will be connected shortly.",
    "language": "en-US"
  }'

Call Action Endpoints

Action	Endpoint	Description
Answer	POST /calls/{id}/answer	Answer an incoming call
Decline	POST /calls/{id}/decline	Decline an incoming call
Transfer	POST /calls/{id}/transfer	Transfer to another number
Record	POST /calls/{id}/record	Start recording
Play Audio	POST /calls/{id}/play-audio	Play audio to caller
Gather Input	POST /calls/{id}/gather-dtmf	Collect DTMF input

Recording Inbound Calls

Enable automatic recording for inbound calls:

curl -X PATCH https://api.audian.com:8443/v2/call-flows/cf_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recording": {
      "enabled": true,
      "format": "mp3",
      "participant": "all"
    }
  }'

Voicemail Configuration

Set up voicemail for calls that aren't answered:

curl -X POST https://api.audian.com:8443/v2/voicemail-boxes \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default Voicemail",
    "greeting": "Thank you for calling. Please leave a message.",
    "max_duration": 120,
    "prompt": "Please record your message after the beep."
  }'

Webhook Events for Inbound Calls

You'll receive these webhook events for inbound calls:

call.initiated

{
  "event": "call.initiated",
  "data": {
    "call_id": "call_xyz789",
    "call_type": "inbound",
    "from": "+14155552672",
    "to": "+14155552671",
    "initiated_at": "2024-01-15T10:30:00Z"
  }
}

call.ringing

{
  "event": "call.ringing",
  "data": {
    "call_id": "call_xyz789",
    "ringing_at": "2024-01-15T10:30:02Z"
  }
}

call.answered

{
  "event": "call.answered",
  "data": {
    "call_id": "call_xyz789",
    "answered_by": "+14155552673",
    "answered_at": "2024-01-15T10:30:05Z"
  }
}

Best Practices

1. Always have a fallback: Define what happens if primary route fails
2. Use time-based routing: Route differently for business hours vs off-hours
3. Implement screening: Block unwanted callers
4. Record when needed: Enable recording for compliance/QA
5. Monitor call flow: Track routing decisions
6. Test thoroughly: Test all routing paths before production
7. Use webhooks for flexibility: Forward to APIs for dynamic routing

Error Handling

Invalid Phone Number

{
  "error": "invalid_number",
  "message": "The destination number format is invalid",
  "code": 400
}

Call Flow Not Found

{
  "error": "not_found",
  "message": "Call flow not found",
  "code": 404
}

Maximum Retries Exceeded

{
  "error": "routing_failed",
  "message": "All routing attempts failed",
  "code": 503
}

Next Steps

• Make outbound calls
• Control active calls
• Build IVR menus
• Set up recording
• Monitor with webhooks