Voice Prompts API

Create and manage interactive voice prompts for building sophisticated IVR (Interactive Voice Response) systems. Define menu options, collect input, and control call flow.

Endpoint

POST https://api.audian.com:8443/v2/media/prompts

Request

Headers

Content-Type: application/json
X-Auth-Token: YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
name	String	Yes	Prompt name
media_id	String	Yes	Media file ID or text for TTS
type	String	No	Prompt type (collect, menu, announce)
options	Object	No	Prompt options and configuration
timeout	Number	No	Timeout in seconds (default: 5)
max_digits	Number	No	Max digits to collect (default: 1)
retry_attempts	Number	No	Number of retries (default: 3)

Prompt Types

Type	Description	Use Case
announce	Play audio without input	Announcements, waiting messages
menu	Play audio and collect DTMF	Menu selection
collect	Collect digits or voice	Phone number, account number

Examples

Create Menu Prompt

curl -X POST https://api.audian.com:8443/v2/media/prompts \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-menu",
    "media_id": "media_abc123def456",
    "type": "menu",
    "options": {
      "1": "sales",
      "2": "support",
      "3": "billing",
      "0": "operator"
    },
    "timeout": 5,
    "max_digits": 1,
    "retry_attempts": 3
  }'

JavaScript/Node.js

const axios = require('axios');

const createPrompt = async () => {
  try {
    const response = await axios.post(
      'https://api.audian.com:8443/v2/media/prompts',
      {
        name: 'main-menu',
        media_id: 'media_abc123def456',
        type: 'menu',
        options: {
          '1': 'sales',
          '2': 'support',
          '3': 'billing',
          '0': 'operator'
        },
        timeout: 5,
        max_digits: 1,
        retry_attempts: 3
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Prompt created:', response.data);
  } catch (error) {
    console.error('Creation failed:', error);
  }
};

createPrompt();

Python

import requests

def create_prompt(api_key, name, media_id, prompt_type='menu', 
                 options=None, timeout=5, max_digits=1, retry_attempts=3):
    url = 'https://api.audian.com:8443/v2/media/prompts'
    headers = {
        'X-Auth-Token': api_key,
        'Content-Type': 'application/json'
    }
    
    payload = {
        'name': name,
        'media_id': media_id,
        'type': prompt_type,
        'timeout': timeout,
        'max_digits': max_digits,
        'retry_attempts': retry_attempts
    }
    
    if options:
        payload['options'] = options
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Usage
result = create_prompt(
    api_key='YOUR_API_KEY',
    name='main-menu',
    media_id='media_abc123def456',
    prompt_type='menu',
    options={
        '1': 'sales',
        '2': 'support',
        '3': 'billing',
        '0': 'operator'
    }
)
print(result)

Collect Digits Prompt

curl -X POST https://api.audian.com:8443/v2/media/prompts \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "account-number",
    "media_id": "media_xyz789",
    "type": "collect",
    "options": {
      "input_type": "dtmf",
      "terminator": "#"
    },
    "timeout": 10,
    "max_digits": 10,
    "retry_attempts": 2
  }'

Response

Success (200)

{
  "id": "prompt_abc123def456",
  "name": "main-menu",
  "media_id": "media_abc123def456",
  "type": "menu",
  "options": {
    "1": "sales",
    "2": "support",
    "3": "billing",
    "0": "operator"
  },
  "timeout": 5,
  "max_digits": 1,
  "retry_attempts": 3,
  "created_at": "2024-02-04T10:40:00Z",
  "updated_at": "2024-02-04T10:40:00Z"
}

Error (400)

{
  "error": "invalid_media_id",
  "message": "The specified media file does not exist"
}

IVR Flow Example

Build a complete IVR system using prompts:

const ivrFlow = {
  start: {
    prompt_id: 'prompt_main_menu',
    transitions: {
      '1': 'sales_queue',
      '2': 'support_queue',
      '3': 'billing_queue',
      '0': 'operator'
    }
  },
  sales_queue: {
    prompt_id: 'prompt_sales_wait',
    action: 'queue_call',
    destination: '+15551234567'
  },
  support_queue: {
    prompt_id: 'prompt_support_wait',
    action: 'queue_call',
    destination: '+15559876543'
  },
  operator: {
    prompt_id: 'prompt_connecting_operator',
    action: 'transfer_call',
    destination: '+15551111111'
  }
};

Best Practices

1. Clear Instructions: Use concise, clear language in prompts
2. Logical Flow: Design intuitive menu hierarchies
3. Timeouts: Set appropriate timeout values for user input
4. Retry Strategy: Balance retry attempts with user frustration
5. Fallback Handling: Always provide fallback options for invalid input
6. Testing: Test IVR flows before deployment

Common Configurations

Sales Menu (Fast)

• Timeout: 3 seconds
• Max digits: 1
• Retries: 2

Account Lookup (Slow)

• Timeout: 10 seconds
• Max digits: 10
• Retries: 3

Confirmation (Very Slow)

• Timeout: 15 seconds
• Max digits: 1
• Retries: 4

Limits and Quotas

• Max prompt name length: 255 characters
• Max options: 12 per prompt
• Min timeout: 1 second
• Max timeout: 30 seconds
• Max digits: 20
• Max retry attempts: 5