Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Broadcast a message using TTS

    Broadcast a message using TTS

    POST
    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.

    Request​

    Path parameters​

    appid stringrequired

    The App ID of the project.

    agentId stringrequired

    The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.

    Request body​

    APPLICATION/JSON
    BODYrequired
    • text stringrequired

      The broadcast message text. The maximum length of the text content is 512 bytes.

    • priority stringnullable

      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 booleannullable

      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.

    • 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.

    Authorization

    This endpoint requires Basic Auth.

    Request example


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

    vundefined