Real-time Conversational AI provides the following API operations for token generation, messaging, and agent instance management.
getRtcAuthToken
Generates a token for a real-time communication (RTC) call.
Usage notes
-
Request protocol: HTTP or HTTPS
-
Request path: /api/v2/aiagent/getRtcAuthToken
-
Authorization required: Yes
-
Request method: POST
-
Content-Type: JSON
-
Required configurations: biz.live_mic.app_id and biz.live_mic.app_key
Request parameters
|
Name |
Type |
Required |
Example |
Description |
|
user_id |
String |
Yes |
userid**** |
The user ID. |
|
channel_id |
String |
No |
channelid**** |
The channel ID. Note
If you do not specify this parameter, the server will generate a 32-character UUID (without hyphens). |
Response parameters
|
Name |
Type |
Example |
Description |
||||
|
code |
Integer |
200 |
The HTTP status code returned. |
||||
|
rtc_auth_token |
String |
eyJnc2xiIjp**** |
The RTC token. |
||||
|
channel_id |
String |
channelid**** |
The channel ID used. |
||||
|
timestamp |
Long |
1700000000 |
The validity period. Unit: seconds. By default, the token is valid for 24 hours. |
||||
Examples
Sample request
{
"user_id": "usertid****",
"channel_id":"channelid****"
}Sample success response
{
"code": 200,
"rtc_auth_token": "eyJnc2xiIjp****",
"channel_id": "channelid****",
"timestamp": 1700000000
}generateMessageChatToken
Generates the token required for interactive messaging.
Usage notes
-
Request protocol: HTTP or HTTPS
-
Request path: /api/v2/aiagent/generateMessageChatToken
-
Authorization required: Yes
-
Request method: POST
-
Content-Type: JSON
-
Required configurations: biz.openapi.access.key and biz.openapi.access.secret
Request parameters
|
Name |
Type |
Required |
Example |
Description |
|
ai_agent_id |
String |
Yes |
19de81b3b3d94abda22**** |
The agent ID. |
|
user_id |
String |
Yes |
userid**** |
The user ID. It can be up to 64 characters in length and can contain only letters, digits, and underscores (_). |
|
role |
String |
No |
admin |
The role. Set this parameter to admin to allow the user to call management-related API operations. By default, this parameter is left empty. |
|
expire |
Integer |
No |
3600 |
The timeout period. Unit: seconds. Default value: 3600. |
|
region |
String |
Yes |
cn-shanghai |
The region where the agent resides. For more information, see Endpoints. |
Response parameters
|
Name |
Type |
Example |
Description |
||||
|
code |
Integer |
200 |
The HTTP status code returned. |
||||
|
message |
String |
success |
The description. |
||||
|
request_id |
String |
7B117AF5-2A16-412C-B127-**** |
The request ID. |
||||
|
app_id |
String |
**** |
The application ID. |
||||
|
token |
String |
acet**** |
The generated token. |
||||
|
user_id |
String |
userid**** |
The user ID for joining the call. |
||||
|
nonce |
String |
AK-**** |
The nonce used to generate the token. |
||||
|
role |
String |
admin |
The role used to generate the token. |
||||
|
timestamp |
Long |
1700000000 |
The expiration time. Unit: seconds. Expiration time = Current time + Validity period. |
||||
|
app_sign |
String |
H4sIAAAAAAAE**** |
The application signature. |
||||
Examples
Sample request
{
"user_id": "userid****",
"ai_agent_id":"19de81b3b3d94abda22******",
"role":"admin",
"expire":1800,
"region":"cn-shanghai"
}Sample success response
{
"code": 200,
"message": "success",
"role": "admin",
"user_id": "userid****",
"app_id": "****",
"nonce": "AK-****",
"request_id": "7B117AF5-2A16-412C-B127-****",
"token": "acet****",
"timestamp": 1700000000,
"app_sign": "H4sIAAAAAAAE****",
}describeAIAgentInstance
Queries the details of an agent instance.
Usage notes
-
Request protocol: HTTP or HTTPS
-
Request path: /api/v2/aiagent/describeAIAgentInstance
-
Authorization required: Yes
-
Request method: POST
-
Content-Type: JSON
-
Required configurations: biz.openapi.access.key and biz.openapi.access.secret
Request parameters
|
Name |
Type |
Required |
Example |
Description |
|
user_id |
String |
Yes |
userid**** |
The user ID. |
|
ai_agent_instance_id |
String |
Yes |
39f8e0bc005e4f309379701645f4**** |
The ID of the agent instance. |
|
region |
String |
Yes |
cn-shanghai |
The region where the agent resides. For more information, see Endpoints. |
Response parameters
|
Name |
Type |
Example |
Description |
||||
|
code |
Integer |
200 |
The HTTP status code returned. |
||||
|
message |
String |
success |
The description. |
||||
|
request_id |
String |
7B117AF5-2A16-412C-B127-**** |
The request ID. |
||||
|
call_log_url |
String |
https://example.com/call_logs/12345 |
The call log URL. |
||||
|
runtime_config |
String |
{"VoiceChat":{"AgentUserId":"voice_agent_001","ChannelId":"voice_channel_001","AuthToken":"your_voice_chat_auth_token"}} |
The agent's runtime configuration. For more information, see |
||||
|
status |
String |
Finished |
The agent's status. Valid values:
|
||||
|
template_config |
String |
{"VoiceChat": {"AppId": "your_voice_chat_app_id"}} |
The template configuration for setting up an agent call. For more information, see AIAgentTemplateConfig. |
||||
|
user_data |
String |
{"Email":"johndoe@example.com","Preferences":{"Language":"en"}} |
The custom user data. |
||||
|
agent_config |
String |
{"xxx":"xx"} |
The agent template configuration, merged with the console configuration. If left empty, the default console configuration is used. For more information, see AIAgentConfig. |
||||
Examples
Sample request
{
"user_id":"userid****",
"ai_agent_instance_id": "39f8e0bc005e4f309379701645f4****",
"region":"cn-shanghai"
}Sample success response
{
"code": 200,
"message": "success",
"request_id": "7B117AF5-2A16-412C-B127-****",
"agent_config": "{\"VoiceChat\": {\"AppId\": \"your_voice_chat_app_id\"}}",
"template_config": "{\"VoiceChat\": {\"AppId\": \"your_voice_chat_app_id\"}}",
"call_log_url": "https://example.com/call_logs/12345",
"user_data": "{\"user_id\": \"test\"}",
"runtime_config": "{\"VoiceChat\":{\"AgentUserId\":\"voice_agent_001\",\"ChannelId\":\"voice_channel_001\",\"AuthToken\":\"your_voice_chat_auth_token\"}}",
"status": "Finished"
}