Call Actions

Once a call is in progress, you can perform real-time actions to control the call. These include transferring calls, putting them on hold, muting participants, and more.

Transfer Calls

Transfer an active call to another phone number:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/transfer \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+14155552673"
  }'

Response:

{
  "call_id": "call_xyz789",
  "status": "transferred",
  "transfer_from": "+14155552672",
  "transfer_to": "+14155552673",
  "transferred_at": "2024-01-15T10:33:00Z"
}

Transfer Parameters

Parameter	Type	Required	Description
destination	string	Yes	Phone number to transfer to
caller_id	string	No	Caller ID for transferred call
transfer_type	string	No	blind (default) or attended

Blind Transfer

Complete the transfer immediately:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/transfer \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+14155552673",
    "transfer_type": "blind"
  }'

Attended Transfer

Stay on the call while setting up the transfer:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/transfer \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+14155552673",
    "transfer_type": "attended",
    "hold_original": true
  }'

With attended transfer, the original call is held while you speak with the transfer destination.

Put Call on Hold

Place an active call on hold:

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

Response:

{
  "call_id": "call_xyz789",
  "status": "held",
  "held_at": "2024-01-15T10:33:30Z"
}

Hold Options

You can optionally play hold music while the call is on hold:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/hold \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hold_music": "https://example.com/hold-music.mp3"
  }'

Resume Call from Hold

Resume a call that's on hold:

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

Response:

{
  "call_id": "call_xyz789",
  "status": "resumed",
  "resumed_at": "2024-01-15T10:34:00Z"
}

Mute Audio

Mute a call participant:

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

Response:

{
  "call_id": "call_xyz789",
  "muted": true,
  "muted_at": "2024-01-15T10:33:45Z"
}

Unmute Audio

Unmute a call participant:

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

Response:

{
  "call_id": "call_xyz789",
  "muted": false,
  "unmuted_at": "2024-01-15T10:34:15Z"
}

Play Audio During Call

Play audio to one or both call participants:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/play-audio \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/message.mp3",
    "participant": "both"
  }'

Parameters

Parameter	Type	Options	Description
audio_url	string	-	URL to audio file
message	string	-	Text-to-speech message (alternative to audio_url)
participant	string	caller, callee, both	Who hears the audio
interrupt	boolean	-	Whether to interrupt current audio

Using Text-to-Speech

Instead of an audio file, provide a message:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/play-audio \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thank you for your patience. An agent will be with you shortly.",
    "language": "en-US",
    "participant": "callee"
  }'

End Call

Terminate an active call:

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

Response:

{
  "call_id": "call_xyz789",
  "status": "completed",
  "ended_at": "2024-01-15T10:35:10Z"
}

Gather DTMF Input

Collect keypad input from the call participant:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/gather-dtmf \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Press 1 for billing, 2 for support, or 3 for sales.",
    "max_digits": 1,
    "timeout": 10
  }'

Response:

{
  "call_id": "call_xyz789",
  "digits_collected": "2",
  "input_type": "dtmf"
}

Parameters

Parameter	Type	Default	Description
prompt	string	-	Message to play before collecting input
max_digits	integer	1	Maximum digits to collect
timeout	integer	10	Seconds to wait for input
finish_key	string	#	Key to finish input early
language	string	en-US	Language for TTS prompt

Conference Calls

Add another participant to an existing call to create a conference:

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/conference \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant": "+14155552673"
  }'

Response:

{
  "call_id": "call_xyz789",
  "conference_id": "conf_abc123",
  "participants": [
    "+14155552671",
    "+14155552672",
    "+14155552673"
  ]
}

Remove Conference Participant

curl -X POST https://api.audian.com:8443/v2/conferences/conf_abc123/participants/+14155552673/remove \
  -H "X-Auth-Token: YOUR_API_KEY"

Send DTMF Tones

Send DTMF tones to the call destination (useful for navigating automated systems):

curl -X POST https://api.audian.com:8443/v2/calls/call_xyz789/send-dtmf \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "digits": "1234",
    "duration": 100
  }'

Parameters

Parameter	Type	Default	Description
digits	string	-	DTMF digits to send
duration	integer	100	Milliseconds per digit
pause_between	integer	100	Milliseconds between digits

Call Status

Get current status of an active call:

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

Response:

{
  "call_id": "call_xyz789",
  "status": "answered",
  "duration": 125,
  "from": "+14155552671",
  "to": "+14155552672",
  "muted": false,
  "on_hold": false,
  "recording_active": true,
  "initiated_at": "2024-01-15T10:30:00Z",
  "answered_at": "2024-01-15T10:30:05Z"
}

Real-Time Call Monitoring

Monitor call progress through webhooks:

{
  "event": "call.held",
  "data": {
    "call_id": "call_xyz789",
    "held_at": "2024-01-15T10:33:30Z"
  }
}

Available events:

• call.held - Call placed on hold
• call.resumed - Call resumed from hold
• call.muted - Audio muted
• call.unmuted - Audio unmuted
• call.transferred - Call transferred
• call.completed - Call ended
• ivr.input_received - DTMF input collected

Error Handling

Call Not Found

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

Invalid State

{
  "error": "invalid_state",
  "message": "Cannot transfer a call that is not answered",
  "code": 409
}

Transfer Failed

{
  "error": "transfer_failed",
  "message": "Transfer destination is not available",
  "code": 503
}

Code Examples

Node.js

const axios = require('axios');

async function transferCall(callId, destination) {
  try {
    const response = await axios.post(
      `https://api.audian.com:8443/v2/calls/${callId}/transfer`,
      { destination },
      {
        headers: {
          'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
        }
      }
    );
    console.log('Call transferred:', response.data);
  } catch (error) {
    console.error('Transfer failed:', error.response?.data);
  }
}

async function holdCall(callId) {
  try {
    const response = await axios.post(
      `https://api.audian.com:8443/v2/calls/${callId}/hold`,
      {},
      {
        headers: {
          'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
        }
      }
    );
    console.log('Call on hold:', response.data);
  } catch (error) {
    console.error('Hold failed:', error.response?.data);
  }
}

async function gatherInput(callId) {
  try {
    const response = await axios.post(
      `https://api.audian.com:8443/v2/calls/${callId}/gather-dtmf`,
      {
        prompt: 'Press 1 for billing or 2 for support',
        max_digits: 1,
        timeout: 10
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.AUDIAN_API_KEY}`
        }
      }
    );
    console.log('Input collected:', response.data.digits_collected);
  } catch (error) {
    console.error('Gather failed:', error.response?.data);
  }
}

Python

import requests
import os

def transfer_call(call_id, destination):
    url = f'https://api.audian.com:8443/v2/calls/{call_id}/transfer'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}",
        'Content-Type': 'application/json'
    }
    payload = {'destination': destination}

    response = requests.post(url, json=payload, headers=headers)
    print('Call transferred:', response.json())

def hold_call(call_id):
    url = f'https://api.audian.com:8443/v2/calls/{call_id}/hold'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}"
    }

    response = requests.post(url, headers=headers)
    print('Call on hold:', response.json())

def gather_input(call_id):
    url = f'https://api.audian.com:8443/v2/calls/{call_id}/gather-dtmf'
    headers = {
        'Authorization': f"Bearer {os.getenv('AUDIAN_API_KEY')}",
        'Content-Type': 'application/json'
    }
    payload = {
        'prompt': 'Press 1 for billing or 2 for support',
        'max_digits': 1,
        'timeout': 10
    }

    response = requests.post(url, json=payload, headers=headers)
    print('Input collected:', response.json())

Best Practices

1. Check call state: Verify call status before performing actions
2. Handle timeouts: Set appropriate timeouts for user input
3. Provide feedback: Tell users what actions are happening
4. Use webhooks: Monitor call state asynchronously
5. Error handling: Always handle action failures gracefully
6. Test thoroughly: Test all action combinations

Next Steps

• Set up call recording
• Work with DTMF input
• Build IVR menus
• Monitor with webhooks