This topic describes the API operations related to Real-time Conversational AI.
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. A value of admin indicates that the user can 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's template configuration, which will be merged with the console configuration. If it is left empty, the default configuration from the console 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"
}