---
title: Broadcast a message using TTS
description: Broadcast a custom message using the TTS module.
sidebar_position: 7
platform: android
exported_from: https://docs.agora.io/en/conversational-ai/rest-api/agent/speak
exported_on: '2026-06-05T05:02:52.319940Z'
exported_file: speak.md
---

> For a complete site index fetch https://docs.agora.io/llms.txt. For all pages in this product fetch https://docs.agora.io/en/conversational-ai/overview/product-overview.md

[HTML Version](https://docs.agora.io/en/conversational-ai/rest-api/agent/speak)

# Broadcast a message using TTS


**Method:** POST
**Endpoint:** `https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speak`

Use this endpoint to broadcast a custom message using the TTS module.

During a conversation with a Conversational AI agent, call this endpoint to immediately broadcast a custom message using the TTS module. Upon receiving the request, Conversational AI Engine interrupts the agent’s speech and thought process to deliver the message. This broadcast can be interrupted by human voice.
The speak API is not supported when using `mllm` configuration.

## Request

### Path parameters

- **appid** (string, required): The App ID of the project.
- **agentId** (string, required): The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md).
### Request body

APPLICATION/JSON
**BODY**

- **text** (string, required): The broadcast message text. The maximum length of the text content is 512 bytes.
- **priority** (string, optional, default: `INTERRUPT`, possible values: `INTERRUPT`, `APPEND`, `IGNORE`): Sets the priority of the message broadcast.

    - `INTERRUPT`: High priority. The agent immediately interrupts the current interaction to announce the message.
    - `APPEND`: Medium priority. The agent announces the message after the current interaction ends.
    - `IGNORE`: Low priority. If the agent is busy interacting, it ignores and discards the broadcast; the message is only announced if the agent is not interacting.
- **interruptable** (boolean, optional, default: `true`): Whether to allow users to interrupt the agent's broadcast by speaking:
    - `true`: Allow
    - `false`: Don't allow

## Response

- If the returned status code is `200`, the request was successful. The response body is empty, and the agent starts to broadcast the specified message.

  **OK**

- **agent_id** (string, optional): Unique id of the agent instance.
- **channel** (integer, optional): The name of the channel.
- **start_ts** (integer, optional): Agent creation timestamp.    

- If the returned status code is not `200`, the request failed. The response body includes the error code and description. Refer to [status codes](https://docs-md.agora.io/en/conversational-ai/rest-api/reference.md) to understand the possible reasons for failure.

## Authorization

This endpoint requires [authentication](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.md).

## Request example

**curl**
```bash
      curl --request post \
        --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/speak \
        --header 'Authorization: Basic' \
        --data '
      {
        "text": "Sorry, the conversation content is not compliant.",
        "priority": "INTERRUPT",
        "interruptable": false
      }'
```

**Python**
```python
    import requests

    url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/speak"

    payload = {
        "text": "Sorry, the conversation content is not compliant.",
        "priority": "INTERRUPT",
        "interruptable": False
    }
    headers = {"Authorization": "Basic"}

    response = requests.request("post", url, json=payload, headers=headers)

    print(response.text)
```

**Node.js**
```js
    const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/speak';
    const options = {
      method: 'post',
      headers: { Authorization: 'Basic' },
      body: JSON.stringify({
        text: 'Sorry, the conversation content is not compliant.',
        priority: 'INTERRUPT',
        interruptable: false
      })
    };

    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json))
      .catch(err => console.error(err));
```

## Response example

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