Making Outbound Calls

The Audian API makes it easy to initiate outbound calls to any phone number. You can control how calls are placed, set up call actions, and track call progress through webhooks.

Basic Outbound Call

The simplest way to make a call:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672"
  }'

Response:

{
  "call_id": "call_xyz789",
  "call_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "+14155552671",
  "to": "+14155552672",
  "status": "initiated",
  "created_at": "2024-01-15T10:30:00Z"
}

Call Parameters

Required Parameters

Parameter	Type	Description
from	string	Caller ID (must be a phone number your account owns)
to	string	Destination phone number (E.164 format recommended)

Optional Parameters

Parameter	Type	Default	Description
call_type	string	outbound	Type of call (always outbound for this endpoint)
timeout	integer	30	Ring timeout in seconds
max_duration	integer	3600	Maximum call duration in seconds
tags	object	{}	Custom tags for tracking
custom_fields	object	{}	Custom data to store with call
recording	object	{}	Recording configuration
call_control	object	{}	Call control and actions

Example: Call with Timeout and Tags

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "timeout": 45,
    "max_duration": 600,
    "tags": {
      "campaign": "winter_sale",
      "agent_id": "agent_123",
      "priority": "high"
    },
    "custom_fields": {
      "customer_id": "cust_456",
      "order_id": "ord_789"
    }
  }'

Response:

{
  "call_id": "call_xyz789",
  "call_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "+14155552671",
  "to": "+14155552672",
  "status": "initiated",
  "timeout": 45,
  "max_duration": 600,
  "tags": {
    "campaign": "winter_sale",
    "agent_id": "agent_123",
    "priority": "high"
  },
  "custom_fields": {
    "customer_id": "cust_456",
    "order_id": "ord_789"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Call Control Actions

Use call_control to define actions that happen during the call:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "call_control": {
      "on_answered": [
        {
          "action": "play_audio",
          "audio_url": "https://example.com/greeting.mp3",
          "message": "Hello! Thank you for calling."
        }
      ],
      "on_no_answer": [
        {
          "action": "play_audio",
          "message": "Sorry, no one is available right now. Please leave a message."
        }
      ]
    }
  }'

Supported Actions

Action	Description	Parameters
play_audio	Play audio file or TTS message	audio_url, message, language
record_audio	Record the call	max_duration, beep_start
transfer	Transfer call to another number	destination, caller_id
hangup	End the call	-
gather_dtmf	Collect DTMF input	max_digits, timeout, finish_key

Example: Call with IVR Menus

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "call_control": {
      "on_answered": [
        {
          "action": "play_audio",
          "message": "Welcome to support. Press 1 for billing, 2 for technical support, or 3 for sales."
        },
        {
          "action": "gather_dtmf",
          "max_digits": 1,
          "timeout": 10,
          "routes": [
            {
              "digit": "1",
              "action": "transfer",
              "destination": "+14155552673"
            },
            {
              "digit": "2",
              "action": "transfer",
              "destination": "+14155552674"
            },
            {
              "digit": "3",
              "action": "transfer",
              "destination": "+14155552675"
            }
          ]
        }
      ]
    }
  }'

Recording Calls

Enable call recording by adding the recording parameter:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "recording": {
      "enabled": true,
      "format": "mp3",
      "participant": "all"
    }
  }'

Recording Parameters

Parameter	Type	Options	Description
enabled	boolean	-	Enable/disable recording
format	string	wav, mp3, opus	Audio format
participant	string	all, caller, callee	Who to record
bitrate	integer	-	Audio bitrate in kbps

When recording completes, you'll receive a recording.completed webhook event with the download URL.

Using Text-to-Speech

Instead of pre-recorded audio, use TTS messages:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "call_control": {
      "on_answered": [
        {
          "action": "play_audio",
          "message": "Hello! You have a $50 credit available. Would you like to use it?",
          "language": "en-US",
          "voice": "female"
        }
      ]
    }
  }'

TTS Parameters

Parameter	Type	Options	Description
message	string	-	Text to speak
language	string	en-US, en-GB, es-ES, etc.	Language code
voice	string	male, female	Voice gender
rate	float	0.5 - 2.0	Speech rate multiplier

Scheduled Calls

Schedule calls to be placed at a future time:

curl -X POST https://api.audian.com:8443/v2/calls \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552671",
    "to": "+14155552672",
    "scheduled_for": "2024-01-15T15:00:00Z",
    "call_control": {
      "on_answered": [
        {
          "action": "play_audio",
          "message": "This is your appointment reminder for tomorrow at 2 PM."
        }
      ]
    }
  }'

Response:

{
  "call_id": "call_scheduled_123",
  "status": "scheduled",
  "scheduled_for": "2024-01-15T15:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Batching Multiple Calls

Create multiple calls in one request:

curl -X POST https://api.audian.com:8443/v2/calls/batch \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "from": "+14155552671",
        "to": "+14155552672",
        "tags": { "batch_id": "batch_123" }
      },
      {
        "from": "+14155552671",
        "to": "+14155552673",
        "tags": { "batch_id": "batch_123" }
      },
      {
        "from": "+14155552671",
        "to": "+14155552674",
        "tags": { "batch_id": "batch_123" }
      }
    ]
  }'

Response:

{
  "batch_id": "batch_123abc",
  "total": 3,
  "queued": 3,
  "failed": 0,
  "calls": [
    {
      "call_id": "call_1",
      "status": "initiated"
    },
    {
      "call_id": "call_2",
      "status": "initiated"
    },
    {
      "call_id": "call_3",
      "status": "initiated"
    }
  ]
}

Retrieve Call Status

Get information about a call in progress:

curl https://api.audian.com:8443/v2/calls/call_xyz789 \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "call_id": "call_xyz789",
  "call_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from": "+14155552671",
  "to": "+14155552672",
  "status": "answered",
  "duration": 45,
  "initiated_at": "2024-01-15T10:30:00Z",
  "answered_at": "2024-01-15T10:30:05Z",
  "tags": {
    "campaign": "winter_sale"
  }
}

Call Progress Monitoring

Monitor call progress through webhooks:

{
  "id": "evt_1234567890abcdef",
  "timestamp": "2024-01-15T10:30:00Z",
  "event": "call.initiated",
  "data": {
    "call_id": "call_xyz789",
    "status": "initiated"
  }
}

Events you'll receive:

1. call.initiated - Call created
2. call.ringing - Destination is ringing
3. call.answered - Call was answered
4. call.completed - Call ended normally
5. call.failed - Call failed to connect

Handling Call Failures

If a call fails, you'll receive a call.failed webhook:

{
  "event": "call.failed",
  "data": {
    "call_id": "call_xyz789",
    "reason": "no_answer",
    "reason_code": 408
  }
}

Possible failure reasons:

Reason	Code	Description
no_answer	408	Destination didn't answer within timeout
declined	603	Call was explicitly declined
invalid_number	404	Invalid destination number
busy	486	Destination line is busy
network_error	503	Network connectivity issue

Error Responses

Common error scenarios:

Invalid Destination Number

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

Unauthorized Caller ID

{
  "error": "unauthorized_caller_id",
  "message": "You are not authorized to use this caller ID",
  "code": 403
}

Rate Limited

{
  "error": "rate_limited",
  "message": "Too many concurrent calls. Maximum: 100",
  "code": 429
}

Best Practices

1. Always use E.164 format: +14155552671 not (415) 555-2671
2. Handle retries: Implement exponential backoff for failed calls
3. Set appropriate timeouts: 30-45 seconds for most use cases
4. Monitor webhooks: Track call progress asynchronously
5. Test with test numbers: Use test destinations before production
6. Limit call duration: Set max_duration to prevent runaway calls
7. Use tags: Tag calls for easy tracking and filtering

Code Examples

Node.js

const axios = require('axios');

async function makeCall() {
  try {
    const response = await axios.post('https://api.audian.com:8443/v2/calls', {
      from: '+14155552671',
      to: '+14155552672',
      call_control: {
        on_answered: [
          {
            action: 'play_audio',
            message: 'Hello! Thank you for calling.'
          }
        ]
      }
    }, {
      headers: {
        'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
      }
    });

    console.log('Call created:', response.data.call_id);
  } catch (error) {
    console.error('Error creating call:', error.response?.data);
  }
}

makeCall();

Python

import requests
import os

def make_call():
    url = 'https://api.audian.com:8443/v2/calls'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}",
        'Content-Type': 'application/json'
    }
    payload = {
        'from': '+14155552671',
        'to': '+14155552672',
        'call_control': {
            'on_answered': [
                {
                    'action': 'play_audio',
                    'message': 'Hello! Thank you for calling.'
                }
            ]
        }
    }

    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()
        print(f"Call created: {response.json()['call_id']}")
    except requests.exceptions.RequestException as e:
        print(f"Error creating call: {e.response.json()}")

make_call()

Next Steps

• Handle inbound calls
• Perform call actions
• Build IVR menus
• Monitor with webhooks