Stopped csharpivr

Function Documentation

Overview

This function implements a simple interactive voice response (IVR) system for incoming phone calls using Sinch Voice API. When a caller dials the company’s number, they hear a greeting and are prompted to press 1 for "Yes" or 2 for "No." Based on the caller’s input, the system responds with a confirmation message and then ends the call. If the caller enters an invalid option or does not respond, the system politely asks them to try again once before ending the interaction.

From a business perspective, this function provides a straightforward way to collect a binary response from callers, such as confirming an appointment, opting into a service, or answering a yes/no question. It automates call handling, reduces the need for live agents, and ensures consistent caller experience.

Caller Experience

1. Call Initiation: When the caller dials the company’s number, the call is answered automatically.
2. Welcome Prompt: The caller hears a friendly greeting: "Welcome to [Company Name]! Press 1 for Yes, or press 2 for No."
3. Input Collection: The system waits up to 5 seconds for the caller to press a key (1 or 2).
4. Valid Input:
   • If the caller presses 1, they hear: "Great! You selected Yes." followed by "Thank you for calling. Goodbye!" and the call ends.
   • If the caller presses 2, they hear: "Okay, you selected No." followed by "Thank you for calling. Goodbye!" and the call ends.
5. Invalid Input or No Input:
   • The system says: "Invalid selection. Please try again." and repeats the menu prompt once more.
   • If the caller again fails to provide valid input, the call ends without further prompts.
6. Call End: The call disconnects gracefully after the final message.

Key Features

• Simple Yes/No IVR Menu: Provides a clear, easy-to-understand prompt for callers to respond with a binary choice.
• Retry Logic: Handles invalid or no input by giving callers a second chance to respond correctly, improving data accuracy and user experience.
• Automated Call Handling: Eliminates the need for human intervention for simple confirmations, saving operational costs.
• Configurable Company Name: The greeting dynamically includes the company name from configuration, allowing easy branding without code changes.
• Robust Logging: Logs key events such as incoming calls, user selections, invalid inputs, and call disconnects for monitoring and troubleshooting.

Integration Points

• Sinch Voice API: Receives webhook callbacks for call events (incoming call, input received, call answered, call ended).
• Configuration System: Reads the company name from environment or configuration settings to personalize prompts.
• Logging Framework: Uses built-in logging to record call events and errors for operational insight.
• SVAML (Sinch Voice Application Markup Language): Constructs voice menus and instructions dynamically using SVAML builders to control call flow and voice prompts.

Error Handling

• Null or Malformed Callbacks: Returns HTTP 400 Bad Request if incoming webhook data is missing or invalid.
• Invalid User Input: Detects invalid DTMF input and prompts the caller to try again once before ending the call.
• Timeouts: If the caller does not respond within 5 seconds, the prompt repeats once.
• Unknown Event Types: Returns an error if the webhook event type is unrecognized.
• JSON Parsing Errors: Catches and logs JSON deserialization errors, returning appropriate HTTP error codes.
• Graceful Call End: Logs call disconnect reasons and durations without attempting further SVAML responses.

Technical Notes

• The function is implemented as an ASP.NET Core Web API controller with multiple POST endpoints handling different Sinch voice callback events: ICE (incoming call), PIE (prompt input), ACE (answer call), and DICE (disconnect).
• Uses dependency injection to access configuration, logging, and storage via a FunctionContext object.
• The IVR menu is built using a fluent MenuFactory pattern specifying prompts, options, timeouts, and retries, then converted into SVAML using IceSvamletBuilder or PieSvamletBuilder.
• The main webhook endpoint inspects the "event" property in the JSON payload to route requests to the appropriate handler method.
• The function supports only DTMF input for menu selection and ignores speech input.
• The call flow logic and SVAML generation closely mirror the Node.js Sinch template for consistency and ease of maintenance.
• The function uses clear separation of concerns: input validation, business logic, SVAML construction, and error handling are modularized.
• Logging includes structured messages with placeholders for dynamic data to facilitate monitoring and diagnostics.

Call Flow Diagram

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#F5F5F5",
    "primaryTextColor": "#000000",
    "primaryBorderColor": "#666666",
    "lineColor": "#1565C0",
    "secondaryColor": "#E8F5E8",
    "tertiaryColor": "#FFF3E0",
    "background": "#FFFFFF",
    "mainBkg": "#F5F5F5",
    "secondaryBorderColor": "#28A745",
    "tertiaryBorderColor": "#FF9800",
    "primaryColorLight": "#F5F5F5",
    "edgeLabelBackground": "#FFFFFF",
    "nodeTextColor": "#000000"
  },
  "flowchart": {
    "curve": "linear"
  }
}}%%
graph TD
    A[Incoming Call]:::callControl --> B[Play Welcome Message]:::voiceOutput
    B --> C{Menu Choice}:::inputCollection
    C -->|Press 1| D[Say Yes Confirmation]:::voiceOutput
    D --> E[Say Goodbye]:::voiceOutput
    E --> F[Hangup Call]:::callControl
    C -->|Press 2| G[Say No Confirmation]:::voiceOutput
    G --> E
    C -->|Invalid Input| H[Say Invalid Selection]:::errorHandling
    H --> I[Repeat Menu Once]:::inputCollection
    I --> J{Menu Choice Retry}:::inputCollection
    J -->|Press 1| D
    J -->|Press 2| G
    J -->|Invalid Input| K[Hangup Call]:::callControl
    J -->|Timeout| K
    C -->|Timeout| I

classDef voiceOutput fill:#E8F5E8,stroke:#28A745,stroke-width:2px,color:#000000
classDef callControl fill:#E3F2FD,stroke:#3089F0,stroke-width:2px,color:#000000  
classDef inputCollection fill:#FFF3E0,stroke:#FF9800,stroke-width:2px,color:#000000
classDef businessLogic fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px,color:#000000
classDef errorHandling fill:#FFEBEE,stroke:#F44336,stroke-width:2px,color:#000000
classDef recording fill:#E0F2F1,stroke:#00695C,stroke-width:2px,color:#000000
classDef default fill:#F5F5F5,stroke:#666666,stroke-width:2px,color:#000000

Documentation generated on 8/15/2025, 3:40:01 PM using Sinch AI