# 播报自定义消息 (/zh-CN/api-reference/api-ref/conversational-ai/speak)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

让指定智能体播报自定义消息。

- OpenAPI: /openapi/conversational-ai/rest-api.zh-CN.yaml
- Operation ID: agent-speak
- Method: POST
- Path: /v2/projects/{appid}/agents/{agentId}/speak
- Endpoint: https://api.agora.io/cn/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speak

## Servers

- https://api.agora.io/cn/api/conversational-ai-agent

与智能体对话期间，调用该接口可以让智能体使用 TTS 模块立刻播报自定义消息。智能体收到请求后，播报行为会打断当前说话和思考流程。


## Authorization

This endpoint requires authentication.

- `Basic Auth`
- `Agora Token`

## Parameters

No parameters.

## Request body

- `text` (string, required) - 播报的文本内容，最长不超过 512 字节 (bytes)。
- `priority` (string) - 播报行为的优先级，支持设为以下值：
- `"INTERRUPT"`：（默认）高优先级，打断并播报。智能体会终止当前交互，直接播报消息。
- `"APPEND"`: 中优先级，追加播报。智能体会在当前交互结束后播报消息。
- `"IGNORE"`: 低优先级，空闲时播报。如果此时智能体正在交互，智能体会直接忽略并丢弃要播报的消息；只有智能体不在交互中才会播报消息。
- `interruptable` (boolean) - 是否允许用户说话打断智能体播报：
- `true`：（默认）允许。
- `false`：不允许。
  - Default: `true`

### Request body example

```json
{
  "text": "抱歉，对话内容不符合规范。",
  "priority": "INTERRUPT",
  "interruptable": false
}
```

## Responses

### 200

- 若返回的状态码为 `200` 则表示请求成功。响应包体为智能体信息，智能体开始播报指定内容。
- 若返回的状态码不为 `200` 则表示请求失败。响应包体中包含错误的类别和描述，你可以参考[响应状态码](/zh-CN/api-reference/conversational-ai/rest-api/api/response-code)了解可能的原因。

- `agent_id` (string) - 对话式智能体 ID，即智能体唯一标识。
- `channel` (string) - 智能体所在 RTC 频道名。
- `start_ts` (integer) - 智能体创建时间戳。

## Response examples

### 200

```json
{
  "agent_id": "1NT29XxxxxxxxxELWEHC8OS",
  "channel": "test_channel",
  "start_ts": 1744877089
}
```