Use APIs for interactive voice calls with IVR, where users provide feedback through key presses.-Voice Service(VS)-阿里云帮助中心

Interactive Voice Response (IVR) lets you make interactive voice calls using an API. When a user answers a call, the system plays a specified audio file. The user then responds to the audio prompts by pressing keys on their phone.

How it works

The complete Interactive Voice Response (IVR) workflow is a four-stage process that includes an API call, cloud processing, user interaction, and a result callback:

IVR

Initiate call: Your application server calls the IvrCall API to request that the Alibaba Cloud Voice Service make a call to a specified user. The request contains the core interactive logic in the MenuKeyMap parameter, which defines the subsequent voice prompts to play based on the keys that the user presses.
Process and call: The Voice Service platform receives the request and then calls the end user from the specified number.
Interact with the user: After the user answers the call, the system plays an introductory audio message. The user then presses keys based on the audio prompts.
Result callback: The Voice Service platform captures the user's key presses, such as 1, 2, or #, and pushes the key press information (digits) and other data, such as the unique call identifier (call_id), to your business server in real time through a preset HTTP webhook address or a message queue (MNS).
Process the business logic: Your server receives the key press information and processes it based on your business logic. For example, you can record survey results, verify a user's identity, or trigger another action.

Procedure

This section guides you through a basic IVR call. In this example, you will play a welcome message to a user's phone and capture the first key they press.

Step 1: Complete the preparations

Before you call the API, complete the following preparations to ensure that the service functions correctly.

Complete enterprise identity verification: This service is available only to enterprise users. Go to the Qualification Management page in the Voice Service console to complete identity verification and wait for approval.
Register a script: Register a script and wait for approval. You must register a script to declare your business scenario. The content of the script is not used in the actual voice call. For more information, see Add a script.
Request a real number: Request a real number in the Voice Service console. For more information, see Request a real number.
Create an AccessKey: Create and obtain an AccessKey ID and AccessKey secret. These credentials are used for API authentication.
Prepare a webhook address: Prepare a publicly accessible URL to receive key press receipts from the Voice Service platform. Using HTTP batch push is recommended for better real-time performance.
- In the Voice Service console, click General Settings > Subscribe to Receipts.
- Select HTTP Batch Push and enter your public URL.

Step 2: Prepare audio materials

All voice files or Text-to-Speech (TTS) templates must be uploaded or created in the console and approved before they can be used. Approval usually takes one business day.

Option 1: Use a voice file: Log on to the Voice Service console and upload a WAV or MP3 voice file. After the file is approved, obtain the Voice ID.
Option 2: Use a TTS template: Log on to the Voice Service console and create a TTS template. After the template is approved, obtain the Template ID. Note that you cannot create TTS templates or pass custom text for TTS templates directly through the API. All TTS content must be based on templates that are approved in the console. For more information, see Create a voice template.

Step 3: Make an IVR call

Use the IvrCall API operation to make an interactive voice call.
Use QueryCallDetailByCallId to query call details.

Step 4: Receive and process key press receipts

When a user presses a key during a call, the Voice Service sends a POST request to the HTTP address that you configured in Step 1. The request body is in JSON format.

1. Analyze the receipt message

For example, if the user presses 1 during the call, your server receives JSON data similar to the following:

{
  "call_id": "115480011020^1034120****_12345",
  "call_time": "2023-03-15 14:20:30",
  "called_num": "1390000****",
  "digits": "1",
  "out_id": "your-unique-business-id-123",
  "event": "dyvms.Ivr.Digits"
}

digits: The key pressed by the user. This is the most important field.
call_id: The unique ID for this call. You can use it to query call details later.
out_id: The external business ID that is passed when you call the API. This ID helps you associate the receipt with your business data.

2. Ensure your receiving service is secure and stable

Verify signatures: To ensure that callback requests originate from Alibaba Cloud, you must verify the signature of each request. For more information, see Introduction to receipt messages and configuration process.
IP address whitelist: Set up an IP address whitelist on your server or network firewall.
Handle requests idempotently: The Voice Service platform may retry sending a receipt if a network error occurs. Your receiving service must be able to handle these retries idempotently. You can use a combination of call_id and digits to identify and ignore duplicate messages.