Intelligent outbound call callback API-Voice Service(VS)-阿里云帮助中心

After you initiate a call using the voice service API, the voice service sends the transcribed text back to your business through the callback HTTP interface for intelligent outbound calls. Your business then returns the next action to the voice service, which facilitates the Intelligent Speech Interaction between the bot and the user. This topic describes the configuration, request parameters, response parameters, and request and response examples for the callback HTTP interface for intelligent outbound calls used in Intelligent Speech Interaction.

Business process

The voice platform uses the HTTP protocol to push real-time speech-to-text transcripts. The voice platform sends an exception status even when the user is silent. In the response message, you can specify the platform's next action, such as playing an audio file, stopping the current audio playback, transferring the call to an agent, or hanging up. For a complete description of the business process for Intelligent Speech Interaction outbound calls, see Intelligent Speech Interaction outbound call business process.

Configure the callback API

Log in to the Voice Service console.
In the left-side navigation pane, go to General Settings > Callback URLs and turn on the Intelligent Speech Interaction Callback URL switch.
In the Callback URL field, enter a callback URL (for example, https://push.example.com/contextpath/receive.do). The Response Info area shows the required JSON response format. This information is read-only.

Note
The callback URL receives real-time speech-to-text results and returns the next action.

Important
Before saving, ensure that the server corresponding to the receiving address is fully deployed and can return a response in the required JSON format. The response must contain the result, msg, code, and data fields, where the data field must contain the call_id, action, action_code, and extend fields. For the specific format, see the Response Example section.
Click Save. The system sends a one-time HTTP validation request to the callback URL to verify that the response conforms to the specified JSON format. If the callback URL is unreachable or the response format is incorrect, the settings will not be saved.
You can also click Test on the right to verify the configuration.

Callback API

Parameter	Description
Protocol	HTTP
Method	POST
Character encoding	UTF-8

Request example

http://127.0.0.1/test?call_id=100001616500^1000018****&timestamp=1504174341229&content_type=normal&content={"words": "Hello","begin_offset": "1000","end_offset": "9000","begin_time": "2017-06-01 10:00:00"}

Request parameters

Parameter	Type	Required	Example	Description
call_id	String	required	100001616500^1000018****	The unique ID for the call.
timestamp	Long	required	1504174341229	The request timestamp, in milliseconds.
content_type	String	required	normal	The message type. Valid values: normal: A standard message. mute: A mute message. timebreak: A message that interrupts playback after a predefined duration. dtmf: A message indicating a DTMF key press. parallel_transfer: A parallel transfer status message.
content	JSON	required	{"role": "B","identity": "id2","words": "Hello","begin_offset": "1000","end_offset": "9000","begin_time": "2017-06-01 10:00:00"}	The voice content in JSON format. For details, see the following tables.

When content_type is set to normal, the content parameter contains the following fields:

Parameter	Type	Required	Example	Description
words	String	required	Hello	The transcribed text of an utterance.
begin_offset	String	required	6000000	The start time of the utterance, as an offset in milliseconds from the beginning of the session.
end_offset	String	required	7000000	The end time of the utterance, as an offset in milliseconds from the beginning of the session.
begin_time	String	required	7000000	The call start time, as a Unix timestamp in milliseconds.
is_playing	String	optional	true	Specifies whether audio is currently playing.
current_media_code	String	optional	xxxx.wav	The audio file that is currently being played. If the value is 'early_media', it indicates an early media message.
dynamic_id	String	optional	abcdefgh	A custom dynamic extension ID. This ID is returned in subsequent callback URLs for tracking purposes.
record_begin_time	Long	optional	1543856399000	The recording start time, as a Unix timestamp in milliseconds.
asr_begin_time	String	optional	1543856399000	The user speech start time, as a Unix timestamp in milliseconds.
asr_end_time	String	optional	1543856399000	The user speech end time, as a Unix timestamp in milliseconds.
play_begin_time	String	optional	1543856399000	The server playback start time, as a Unix timestamp in milliseconds.
play_end_time	String	optional	1543856399000	The server playback end time, as a Unix timestamp in milliseconds. If playback has not finished, the value is 0.

When content_type is set to mute, the content parameter contains the following fields:

Parameter	Type	Required	Example	Description
dynamic_id	String	optional	abcdefgh	A custom dynamic extension ID. This ID is returned in subsequent callback URLs for tracking purposes.

When content_type is set to dtmf, the content parameter contains the following fields:

Parameter	Type	Required	Example	Description
dynamic_id	String	optional	abcdefgh	A custom dynamic extension ID. This ID is returned in subsequent callback URLs for tracking purposes.
dtmf_digits	String	optional	1	The DTMF key pressed by the user. If no key is pressed before the timeout, the value is 'noInputTimeout'.

When content_type is set to timebreak, the content parameter contains the following fields:

Parameter	Type	Required	Example	Description
current_media_code	String	optional	xxxx.wav	The audio file that is currently being played.
asr_begin_time	String	optional	1543856399000	The user speech start time, as a Unix timestamp in milliseconds.
play_begin_time	String	optional	1543856399000	The server playback start time, as a Unix timestamp in milliseconds.
dynamic_id	String	optional	abcdefgh	A custom dynamic extension ID. This ID is returned in subsequent callback URLs for tracking purposes.

When content_type is set to parallel_transfer, the content parameter contains the following fields:

Parameter	Type	Required	Example	Description
dynamic_id	String	optional	abcdefgh	A custom dynamic extension ID. This ID is returned in subsequent callback URLs for tracking purposes.
transfer_status	String	optional	success\fail	The status of the parallel transfer. Valid values: 'success' and 'fail'.
fail_cause	String	optional	transfer fail.	The reason for the transfer failure. This field is present only when transfer_status is 'fail'.
is_monitor	Boolean	optional	true	Specifies whether to monitor the call after it is successfully transferred to a call center.
cc_name	String	optional	aliyun_cc	The name of the call center to which the call was successfully transferred.

Response examples

Successful call

{
    "result": "success",
    "msg": "success",
    "code": 200,
    "data": {
        "call_id": "100001616500^100001871490",
        "action": "play",
        "action_code": "411111",
        "extend": "111"
    }
}

Failed call

{"result":"fail","msg":"fail reason", "data":{}}

Return parameters

Parameter	Type	Required	Example	Description
call_id	String	Required	B	The unique identifier for the call.
action	String	Required	play	Specifies the next action to perform. Valid values: play: Plays the next audio file. break: Breaks the currently playing audio. continue: Resumes playback of the current audio. hangup: Hangs up the call. transfer: Transfers the call. donothing: Performs no action. dtmf: Receives DTMF tones. parallel_transfer: Initiates a parallel transfer.
action_break	Boolean	Optional	true	Specifies whether to break the previous action. Defaults to `true`. The previous action cannot be broken if its `action_code_break` parameter is set to `false`.
action_code	String	Optional	abc.wav,def.wav,$name$	The code for the audio file to play. To play multiple files, separate their codes with a comma. This parameter supports TTS variables, which must be enclosed in dollar signs (`$`).
action_code_break	Boolean	Optional	true	Specifies whether the playback of the current media file can be broken. Valid values: true (default): The playback can be broken. false: The playback cannot be broken, even if the `action_break` parameter of the next action is set to `true`. Note The `action_code_break` parameter has a higher priority than the `action_break` parameter.
mute_time	Integer	Optional	10000	The duration of silence, in milliseconds (ms). The value must be between 1,000 and 20,000. If the value is outside this range, the system uses the default value of 10,000.
dynamic_id	String	Optional	abc	An opaque string for tracking the request. The system passes this ID back in the subsequent callback URL.
action_code_param	String	Optional	{"name":"Hello, there"}	The TTS parameters in JSON format. The keys in this object correspond to the variables specified in `action_code`.
number	String	Optional	1370000****	The destination phone number for the transfer. This parameter is valid only when `action` is set to `transfer`.
action_code_time_break	Integer	Optional	120	The duration of continuous user speech, in milliseconds (ms), that triggers a break. If the `action_code_break` for the current media file is `true`, the user's speech can break the playback. If this parameter is not set or is set to `0`, this feature is disabled.
dtmf_nonin_overtime	Integer	Optional	3	The no-input timeout in seconds (s), specific to the `dtmf` action. The value must be between 3 and 60. The default value is 3.
dtmf_max_numbers	Integer	Optional	5	The maximum number of digits to collect, specific to the `dtmf` action. The value must be between 1 and 50.
dtmf_end_character	String	Optional	#	The character that terminates digit collection. This parameter is specific to the `dtmf` action. Supported characters are `* #`. You can also leave this parameter empty.
transfer_playfile	String	Optional	#	The audio file to play to the agent after a successful parallel transfer.
is_monitor	Boolean	Optional	true	Indicates whether to monitor the call after a successful parallel transfer to a call center.
cc_name	String	Optional	aliyun_cc	The name of the destination call center for a successful parallel transfer.

Usage

The Intelligent Speech Interaction outbound callback HTTP interface pushes real-time speech-to-text results and interaction statuses for a single call. This interface does not record or return a cumulative call count. To get a total call count, use the call record query APIs to retrieve call logs and then aggregate the results yourself.