Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Retrieve agent history

GET
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/history

Call this endpoint while the agent is running to retrieve the conversation history between the user and the Conversational AI agent.

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.

Response​

  • If the returned status code is 200, the request was successful. The response body contains the result of the request.

    OK
    • agent_id string

      Unique identifier of the agent.

    • start_ts integer

      Agent creation timestamp.

    • status string

      Possible values: RUNNING

      Agent status. Only supports querying the running agent.

    • contents array

      Agent history.

      Show propertiesHide properties
      • role string

        Possible values: user, assistant

        The message sender.

        • user: User
        • assistant: AI agent
      • content string

        Message content.

      • speech_start_ms integer

        Unix timestamp in milliseconds indicating when the user started speaking or the agent started TTS playback. Only returned when llm.vendor is custom.

      • speech_end_ms integer

        Unix timestamp in milliseconds indicating when the user stopped speaking, or when TTS playback completed or was interrupted. Only returned when llm.vendor is custom.

      • speech_algorithmic_delay integer

        The total delay in milliseconds introduced by audio processing algorithms, including noise reduction, background voice suppression, and voiceprint locking, after audio is captured from the user's microphone. Use this value to align timestamps with cloud recording audio.

        Only returned when:

        • llm.vendor is custom
        • contents[].role is user
        • Actual voice input is present

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

Request example


_3
curl --request get \
_3
--url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/history \
_3
--header 'Authorization: Basic <credentials>'

Response example


_15
{
_15
"agent_id": "xxxx",
_15
"start_ts": 123,
_15
"status": "RUNNING",
_15
"contents": [
_15
{
_15
"role": "user",
_15
"content": "hello."
_15
},
_15
{
_15
"role": "assistant",
_15
"content": "hi, how can I help you?"
_15
}
_15
]
_15
}