Broadcast a message using TTS
Updated
Broadcasts a custom message through the TTS module.
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speakUse 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 interrupts the agent’s speech and thought process to deliver the message. This broadcast can be interrupted by human voice.
Note
The speak API is not supported when using mllm configuration.
Path Parameters
appidstringThe App ID of the project.
agentIdstringThe agent instance ID you obtained after successfully calling join to Start a conversational AI agent.
Request Body
application/json
textstringThe broadcast message text. The maximum length of the text content is 512 bytes.
prioritystringSets 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.
interruptablebooleanWhether to allow users to interrupt the agent's broadcast by speaking:
true: Allowfalse: 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. -
If the returned status code is not
200, the request failed. The response body includes the error code and description. Refer to status codes to understand the possible reasons for failure.
Response Body
The request was successful. The response body contains the result of the request.
agent_idstringUnique id of the agent instance.
channelintegerThe name of the channel.
start_tsintegerAgent creation timestamp.
Request examples
curl --request post \ --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/speak \ --header 'Authorization: Basic <credentials>' \ --data ' { "text": "Sorry, the conversation content is not compliant.", "priority": "INTERRUPT", "interruptable": false }'Response example
{ "agent_id": "1NT29XxxxxxxxxELWEHC8OS", "channel": "test_channel", "start_ts": 1744877089}