Buy your own toll-free, local or (inter)national numbers directly online
+353 1 800 816 446 Cart: 0 Ireland flagIreland
🤖 AI-ready IVR

IVR toolkit

Build fully customized call flows and automate every step of your customer interactions with our powerful IVR actions toolkit.

Use simple commands to play audio, collect digits, connect callers, trigger logic, stream audio to AI systems, and more - all inside your existing telephony setup.

  • Integrate AI, automation, or custom back-end logic
  • Build complete IVR flows without extra hardware
  • Control call behavior with precise commands

Benefits of IVR toolkit feature

Discover how our features help you work smarter, save time, and improve how your business communicates.

🧩

Flexible call automation

Define exactly how each call should behave. Play prompts, gather input, route callers, or run conditional logic - all from one clear, developer-friendly toolkit.

⚙️

Designed for development teams

Use structured actions that fit naturally into your backend logic. Each action has predictable results, error handling, and examples to help you build confidently.

🔧

Works with your existing setup

No new infrastructure needed. Use your Callfactory number and simply extend your call logic through the API, your scripts, or internal automation tools.

IVR Actions Toolkit

Click on an action to view its description, signature and examples.

Answers an incoming call. Must be called before playing audio or collecting input on an inbound call.

Description

  • Marks the call as answered on the telephony side.
  • Required before using actions like Play, PromptDigit, GatherDigits, Dial, Record, etc., on inbound calls.

Throws

  • InvalidOperationException - if the call has already been answered.

Signature

void Answer();

Example

protected override async Task 
HandleCallAsync(CancellationToken ct)
{
    // Always answer first on inbound calls
    Answer();

    await Play("welcome.wav", ct);
}

Plays an audio file to the caller or to an outbound channel.

Description

  • Plays an audio file (e.g., .wav) located in the server’s audio directory.
  • Can target the inbound caller or a specific OutboundChannel.

Parameters

  • audioFile - File name/path relative to the IVR audio directory.
  • channel - (optional) Outbound channel to play audio to.
  • ct - Cancellation token; cancelled when the caller or channel disconnects.

Returns

  • PlayResult.Success - Audio played fully.
  • PlayResult.Fail - Playback failed (e.g., invalid file).
  • PlayResult.Cancel - Operation cancelled (e.g., caller hung up).
  • PlayResult.Error - Unexpected error during playback.

Throws

  • OperationCanceledException - If ct is cancelled during playback.
  • Other transport/IO exceptions depending on implementation.

Signatures

Task<PlayResult> Play(
    string audioFile,
    CancellationToken ct = default);

Task<PlayResult> Play(
    string audioFile,
    OutboundChannel channel,
    CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    Answer();
    var result = await Play("welcome.wav", ct);

    if (result != PlayResult.Success)
    {
        Logger.LogWarning("Failed to play welcome message (Result:
        {Result})", result); return;
    }

    await Play("next_prompt.wav", ct);
}

Plays an audio prompt and collects a single DTMF digit.

Description

  • Plays a menu prompt (e.g., ‘Press 1 for sales, 2 for support, 3 to leave a message.’).
  • Waits for a single DTMF digit: 0-9, *, or #.
  • Intended for main menu selections.

Parameters

  • audioFile - Prompt file to play.
  • timeoutSeconds - How long to wait for a digit (default 10).
  • ct - Cancellation token; canceled when the caller disconnects.

Returns

  • MenuResult.Success with Digit set when a digit is received.
  • MenuResult.Timeout when no digit is received within timeoutSeconds.
  • MenuResult.Cancel when operation is cancelled.

Throws

  • OperationCanceledException - If ct is cancelled (e.g., caller hangs up).

Signatures

Task<(MenuResult Result, char? Digit)> PromptDigit(
    string audioFile,
    int timeoutSeconds = 10,
    CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    Answer();
    await Play("welcome.wav", ct);

    var (menuResult, digit) = await PromptDigit(
        "main_menu.wav",
        timeoutSeconds: 10,
        ct);

    if (menuResult == MenuResult.Success && digit.HasValue)
    {
        switch (digit.Value)
        {
            case '1':
                await HandleSales(ct);
                break;
            case '2':
                await HandleSupport(ct);
                break;
            default:
                await Play("invalid_option.wav", ct);
                await Hangup(ct);
                break;
        }
    }
    else if (menuResult == MenuResult.Timeout)
    {
        await Play("no_input_goodbye.wav", ct);
        await Hangup(ct);
    }
    else
    {
        await Play("system_error.wav", ct);
        await Hangup(ct);
    }
}

Plays a prompt and collects multiple DTMF digits (e.g., account number, PIN).

Description

  • Plays a prompt asking the caller to enter several digits.
  • Stops when either:
    • maxDigits is reached
    • A termination digit (e.g., #) is pressed
    • Timeout expires

Parameters

  • audioFile – Prompt to play (e.g., “Please enter your account number followed by #”).
  • maxDigits – Maximum digits to collect before stopping.
  • terminationDigits – String of digits that end collection when entered.
  • timeoutSeconds – Maximum time to wait for input.
  • ct – Cancellation token.

Returns

  • Tuple (GatherResult Result, string? Digits):
  • GatherResult.Success and Digits set when input is collected.
  • GatherResult.Timeout when no input received.
  • GatherResult.Cancel when operation is cancelled.
  • GatherResult.Error on unexpected error.

Throws

  • OperationCanceledException - If ct is cancelled (caller hangs up).

Signatures

Task<(GatherResult Result, string? Digits)> GatherDigits(
    string audioFile,
    int maxDigits = 20,
    string terminationDigits = "#",
    int timeoutSeconds = 30,
    CancellationToken ct = default);

Example

protected override async Task 
HandleCallAsync(CancellationToken ct)
{
    Answer();
    await Play("welcome.wav", ct);

    var (result, digits) = await GatherDigits(
        "enter_account.wav",
        maxDigits: 10,
        terminationDigits: "#",
        timeoutSeconds: 30,
        ct);

    if (result == GatherResult.Success && !string.IsNullOrEmpty(digits))
    {
        await ProcessAccountNumber(digits, ct);
    }
    else if (result == GatherResult.Timeout)
    {
        await Play("no_input_goodbye.wav", ct);
        await Hangup(ct);
    }
    else
    {
        await Play("system_error.wav", ct);
        await Hangup(ct);
    }
}

Dials one or more outbound phone numbers and returns an OutboundChannel when answered.

Description

  • Initiates an outbound call to a single destination or to multiple destinations in parallel.
  • For multiple destinations, the first to answer wins; all others are cancelled.

Parameters

  • destination / destinations – Phone number(s) to dial.
  • callerId – Number to present as Caller ID.
  • ringTimeoutSeconds – Maximum time to ring before giving up.
  • ct – Cancellation token.

Returns

  • Single destination:
  • (DialerResult Result, OutboundChannel? Channel)
  • Multiple destinations:
  • (DialerResult Result, string? AnsweredDestination, OutboundChannel? Channel)
  • DialerResult may be: Init, Ringing, Answered, Busy, Rejected, NoAnswer, Failed, Cancel.

Throws

  • OperationCanceledException – If the operation is cancelled while dialing.

Signatures

Task<(DialerResult Result, OutboundChannel? Channel)> Dial(
    string destination,
    string callerId,
    int ringTimeoutSeconds = 60,
    CancellationToken ct = default);

Task<(DialerResult Result, string? AnsweredDestination,
OutboundChannel? Channel)> Dial(
    string[] destinations,
    string callerId,
    int ringTimeoutSeconds = 40,
    CancellationToken ct = default);

Example (single destination)

private async Task TransferToSupport(CancellationToken ct)
{
    var (dialResult, channel) = await Dial(
        destination: "18885554444",
        callerId: Context.Ani,
        ringTimeoutSeconds: 30,
        ct);

    if (dialResult == DialerResult.Answered && channel != null)
    {
        await Play("connecting_to_support.wav", ct);
        await Connect(channel, ct);
    }
    else
    {
        await Play("support_unavailable.wav", ct);
        await HandleVoicemail(ct);
    }
}

Example (multiple destinations)

private async Task TransferToSalesHuntGroup(CancellationToken ct)
{
    var salesTeam = new[]
    {
        "18885551111",
        "18885552222",
        "18885553333"
    };

    var (result, answeredNumber, channel) = await Dial(
        destinations: salesTeam,
        callerId: Context.Ani,
        ringTimeoutSeconds: 40,
        ct);

    if (result == DialerResult.Answered && channel != null)
    {
        Logger.LogInformation("Connected to sales agent {Number}", answeredNumber);
        await Connect(channel, ct);
    }
    else
    {
        await Play("sales_unavailable.wav", ct);
        await HandleVoicemail(ct);
    }
}

Bridges audio between two channels.

Description

  • For inbound flows: bridges the inbound caller to an outbound channel.
  • For outbound-only scenarios: bridges two outbound channels together.
  • Blocks until one side hangs up or the connection is otherwise terminated.

Parameters

  • channel – Outbound channel to connect to the inbound call.
  • primary, secondary – Two outbound channels to bridge.
  • ct – Cancellation token.

Returns

  • ConnectResult.Success – Connection ended normally (call terminated).
  • ConnectResult.Error – Connection could not be established or failed.

Throws

  • OperationCanceledException – If ct is cancelled while connected.

Signatures

Task<ConnectResult> Connect(
    OutboundChannel channel,
    CancellationToken ct = default);

Task<ConnectResult> Connect(
    OutboundChannel primary,
    OutboundChannel secondary,
    CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    Answer();

    await Play("connecting_you_now.wav", ct);

    var (dialResult, channel) = await Dial(
        destination: "18885550000",
        callerId: Context.Ani,
        ringTimeoutSeconds: 30,
        ct);

    if (dialResult == DialerResult.Answered && channel != null)
    {
        var connectResult = await Connect(channel, ct);
        Logger.LogInformation("Connection ended with result: {Result}", connectResult);
    }
    else
    {
        await Play("agent_unavailable.wav", ct);
    }

    await Hangup(ct);
}

Records audio from the caller or an outbound channel.

Description

  • Starts recording from either the inbound caller or a specific outbound channel.
  • Ends when:
    • timeLimitSeconds is reached
    • A termination digit is pressed (if configured)
    • Caller or channel hangs up

Parameters

  • timeLimitSeconds – Maximum recording length.
  • fileName – Optional custom filename (auto-generated when null).
  • terminationDigits – DTMF digits that stop the recording.
  • playBeep – Whether to play a beep before recording.
  • channel – Optional outbound channel.
  • ct – Cancellation token.

Returns

  • Tuple (RecordResult Result, string? FilePath):
  • RecordResult.Success with FilePath is saved.
  • RecordResult.Timeout, MaxDurationReached, TerminationDigit, Cancel, Error.

Throws

  • OperationCanceledException if cancelled.

Signatures

Task<(RecordResult Result, string? FilePath)> Record(
    int timeLimitSeconds = 120,
    string? fileName = null,
    string? terminationDigits = null,
    bool playBeep = true,
    CancellationToken ct = default);

Task<(RecordResult Result, string? FilePath)> Record(
    OutboundChannel channel,
    int timeLimitSeconds = 120,
    string? fileName = null,
    string? terminationDigits = null,
    bool playBeep = true,
    CancellationToken ct = default);

Example

private async Task HandleVoicemail(CancellationToken ct)
{
    await Play("leave_message_after_beep.wav", ct);

    var (recordResult, filePath) = await Record(
        timeLimitSeconds: 180,
        fileName: null,
        terminationDigits: "#",
        playBeep: true,
        ct: ct);

    if (recordResult == RecordResult.Success && !string.IsNullOrEmpty(filePath))
    {
        Logger.LogInformation("Voicemail saved at {Path}", filePath);
        await Play("thank_you_message_received.wav", ct);
    }
    else
    {
        Logger.LogWarning("Recording failed: {Result}", recordResult);
        await Play("recording_failed.wav", ct);
    }

    await Hangup(ct);
}

Rejects an inbound call with a SIP reason code and terminates the call.

Description

  • Used for call screening, blocking, and out-of-hours behaviour.
  • Returns a SIP error code to the upstream carrier.

Parameters

  • reason – RejectReason.Busy, .TemporarilyUnavailable, .Declined.
  • ct – Cancellation token.

Returns

  • RejectResult.Success – Call rejected.
  • RejectResult.AlreadyAnswered – Call already answered.
  • RejectResult.Error – Failed to reject.

Throws

  • OperationCanceledException if cancelled.

Signatures

Task<RejectResult> Reject(
    RejectReason reason = RejectReason.Busy,
    CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    if (IsBlockedNumber(Context.Ani))
    {
        await Reject(RejectReason.Declined, ct);
        return;
    }

    if (!IsWithinBusinessHours(DateTime.UtcNow))
    {
        await Reject(RejectReason.TemporarilyUnavailable, ct);
        return;
    }

    // Normal flow
    Answer();
    await Play("welcome.wav", ct);
}

Cleanly terminates the active call.

Description

  • Ends the call from the IVR side.

Returns

  • HangupResult.Success – Call ended successfully.
  • HangupResult.NotAnswered – Never answered.
  • HangupResult.AlreadyDisconnected – Caller hung up.
  • HangupResult.Error – Hangup failed.

Throws

  • OperationCanceledException if cancelled.

Signature

Task<HangupResult> Hangup(CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    Answer();

    await Play("goodbye.wav", ct);

    var result = await Hangup(ct);
    Logger.LogInformation("Hangup result: {Result}", result);
}

Pauses execution for a given number of seconds.

Description

  • Waits for durationSeconds while keeping the call open.
  • May be interrupted by DTMF input depending on implementation.

Parameters

  • durationSeconds – Duration in seconds.
  • ct – Cancellation token.

Returns

  • PauseResult.Success – Pause completed normally.
  • PauseResult.Interrupted – Caller pressed a key during pause (if supported).
  • PauseResult.Cancel – Operation cancelled.
  • PauseResult.Error – Pause failed.

Throws

  • OperationCanceledException – If ct is cancelled.

Signatures

Task<PauseResult> Pause(
    int durationSeconds,
    CancellationToken ct = default
);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    Answer();

    await Play("please_wait.wav", ct);

    var result = await Pause(3, ct);

    if (result == PauseResult.Interrupted)
    {
        await Play("you_pressed_a_key.wav", ct);
    }
    else
    {
        await Play("thank_you_for_waiting.wav", ct);
    }

    await Hangup(ct);
}

Sends a busy signal to the caller and terminates the call.

Description

  • Presents a standard busy tone.
  • Commonly used when all agents/lines are occupied.

Returns

  • BusyResult.Success – Busy signal sent and call ended.
  • BusyResult.Cancel – Operation cancelled.
  • BusyResult.Error – Failed to send busy signal or end the call.

Throws

  • OperationCanceledException – If ct is cancelled.

Signature

Task<BusyResult> Busy(CancellationToken ct = default);

Example

protected override async Task HandleCallAsync(CancellationToken ct)
{
    if (AllAgentsBusy())
    {
        var result = await Busy(ct);
        Logger.LogInformation("Busy result: {Result}", result);
        return;
    }

    // Otherwise, proceed with normal flow
    Answer();
    await Play("welcome.wav", ct);
}

Starts streaming the live audio of the call to an external endpoint (e.g., AI or STT engine).

Description

  • Opens a real-time media stream from the call to the given url (e.g., WebSocket endpoint).
  • Typically used to send audio to:
    • an AI assistant,
    • a speech-to-text engine,
    • a custom analytics/monitoring service.
  • Only one active stream per call is recommended.

Parameters

  • url – Target streaming endpoint (e.g., wss://ai.callfactory.nl/voice-stream).
  • options – Optional streaming configuration (direction, metadata, name).
  • ct – Cancellation token. If cancelled, the stream is torn down.

Throws

  • OperationCanceledException – If ct cancelled during setup.
  • Connection/transport exceptions depending on implementation.

Signatures

Task<StreamResult> StartStream(
    string url,
    StreamOptions? options = null,
    CancellationToken ct = default
);

Parameters

public class StreamOptions
{
    public string? Name { get; set; }                           //
Optional stream name
    public StreamDirection Direction { get; set; } =
        StreamDirection.Both;
    public Dictionary<string, string>? Metadata { get; set; }
}

public enum StreamDirection
{
    Inbound,   // From caller to AI
    Outbound,  // From agent/system to AI
    Both
}

Returns

public enum StreamResult
{
    Started,        // Stream successfully started
    Stopped,        // Stream successfully stopped (for
StopStream)
    AlreadyStarted, // A stream is already active
    NotActive,      // No active stream (for StopStream)
    Error           // Failed to start/stop
}

Example

protected override async Task
HandleCallAsync(CancellationToken ct)
{
    Answer();

    // Start streaming caller audio to AI
    var streamResult = await StartStream(
        url: "wss://ai.callfactory.nl/voice-stream",
        options: new StreamOptions
        {
            Name = "support-ai",
            Direction = StreamDirection.Inbound,
            Metadata = new Dictionary<string, string>
            {
                ["caller"] = Context.Ani,
                ["dnis"] = Context.Dnis
            }
        },
        ct
    );

    if (streamResult != StreamResult.Started)
    {
        Logger.LogWarning("Failed to start AI stream:
{Result}", streamResult);
        await Play("ai_unavailable.wav", ct);
        await Hangup(ct);
        return;
    }

    await Play("connected_to_ai.wav", ct);

    // Continue IVR logic while streaming is active...
    var (menuResult, digit) = await
PromptDigit("ai_menu.wav", 30, ct);

    if (menuResult == MenuResult.Success && digit == '0')
    {
        // Caller wants a human agent
        await StopStream(ct);
        await Play("transferring_to_human_agent.wav", ct);
        await TransferToHuman(ct);
    }
    else
    {
        await Play("thank_you_goodbye.wav", ct);
        await StopStream(ct);
        await Hangup(ct);
    }
}

Stops an active audio stream that was previously started with StartStream.

Description

  • Gracefully shuts down the active media stream.
  • Does not hang up the call - only stops sending audio.
  • Safe to call even if no stream is active (returns NotActive).

Parameters

  • ct – Cancellation token.

Returns

  • StreamResult.Stopped – Stream successfully stopped.
  • StreamResult.NotActive – No active stream found.
  • StreamResult.Error – Failed to stop stream.

Throws

  • OperationCanceledException – If ct is cancelled.

Signatures

Task<StreamResult> StopStream(
    CancellationToken ct = default);

Example

private async Task TransferToHuman(CancellationToken ct)
{
    // Stop AI streaming before transferring to human
    var stopResult = await StopStream(ct);
    Logger.LogInformation("StopStream result: {Result}",
stopResult);

    await Play("transferring_to_agent.wav", ct);

    var (dialResult, channel) = await Dial(
        destination: "18005550000",
        callerId: Context.Ani,
        ringTimeoutSeconds: 30,
        ct
    );

    if (dialResult == DialerResult.Answered && channel !=
null)
    {
        await Connect(channel, ct);
    }
    else
    {
        await Play("agent_unavailable.wav", ct);
        await Hangup(ct);
    }
}

Why it matters

The IVR toolkit gives your team complete control over call flows. From simple menus to complex AI-driven interactions - everything is possible with our action library.

These tools are especially useful for teams building custom telephony solutions, implementing AI integrations, or extending existing systems with advanced call logic.

This feature is included free with every Business number or International number.

Learn more about other features

Find more information about our features that can boost your business communications.

DenyList routing

Block unwanted callers automatically by adding numbers to your denylist. Keep your lines open for the calls that matter most.

Change final destinations

Forward calls to any phone: mobile, landline or VOIP. Change destinations anytime, as often as you like.

Whisper tone

Many businesses use multiple phone numbers. A whisper tone tells you which number was called before you answer, so you’re immediately prepared.

IVR toolkit FAQ

Get clear answers about IVR toolkit and how they work for your business.

You can build flows using our IVR actions inside your dashboard. Each action includes examples, signatures, and predictable behavior, so you can implement logic without needing new telephony hardware.

You can create simple flows without coding, but the toolkit is built for teams that want to automate or integrate logic. Developers can use structured actions to trigger prompts, capture digits, or connect callers programmatically.

Yes. You can trigger API calls, send data to your back-end, or stream audio to AI or STT services. The toolkit fits naturally into your existing infrastructure.

Absolutely. You don’t need to change your setup. All IVR actions work with your existing Callfactory numbers, routing, and call settings.

Yes. You can build and preview your flows safely. The toolkit lets you simulate prompts, input collection, and routing behavior before activating changes for real callers.

You decide the behavior. You can replay a prompt, route to voicemail, connect to support, or end the call. Each IVR action supports custom error handling.

Yes. Every action includes timeout handling and optional fallback logic. You can define what happens when no input is received or when a caller hangs up.

Yes. The toolkit was designed for chaining actions together. You can play audio, gather digits, run logic, call an API, and transfer callers - all in a single flow.

Yes. The system is designed for reliability and scale. Whether you run a small business or a high-volume call center, all actions deliver predictable performance.

If your team needs guidance, we can help review your flow design, test your configuration, or support more advanced routing logic.

Happy Callfactory customers:

SignDirect logo
Bosch logo
Trigion logo
ANWB logo
UWV logo
Sogeti logo
Dille & Kamille logo
Nationale Ombudsman logo
KRO-NCRV logo
Swiss Sense logo