Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

ConvoAI Agent Join API Fails with “Input should be a valid string” and Avatar Not Rendering

Updated

Issue Description

When integrating the Agora Conversational AI (ConvAI) Engine, users may encounter issues during the Join API call.
Common symptoms include:

  • API call failing with the error:
    "agent_rtc_uid: Input should be a valid string"

  • Agent joining successfully, but the avatar audio/video does not render

  • The client shows a phantom user (e.g., UID 10053) or mismatched agora_uid

These issues are related to incorrect UID formatting in the Join API request payload.

 

Platform/SDK

  • Product: Agora Conversational AI Engine

  • API Type: RESTful API (Join API)

  • Client Platform: Web

Error Message

"agent_rtc_uid: Input should be a valid string"

Step-by-Step Solution

✅ To fix the issue:

  1. In your Join API request payload, keep:

    "enable_string_uid": false

    This ensures the SDK operates in integer UID mode.

  2. However, wrap both agent_rtc_uid and remote_rtc_uids values as strings:

    "agent_rtc_uid": "1299282093",
"remote_rtc_uids": ["1519147601"]

  3. Ensure that:

    • The same UID values are used on the client side when joining the RTC channel.

    • All UIDs are below 2147483647 (valid 32-bit integer range).

  4. Re-run the Join API request.
    The response should now return HTTP 200 OK and the agent will join the RTC channel correctly.

  5. Once connected:

    • Avatar video and audio should render correctly.

    • The “phantom” UID issue should disappear.

Root Cause

The Join API validates UID fields as strings, but internally, the ConvAI engine still uses integer-based RTC mode when enable_string_uid is set to false.
Passing numeric (non-string) UIDs directly leads to schema validation errors.
On the other hand, enabling enable_string_uid=true can cause avatar rendering issues due to string UID handling mismatch.

 

Prevention / Best Practice

  • Always use string-typed UIDs in the JSON payload, even when enable_string_uid is set to false.

  • Keep UIDs consistent and within the 32-bit integer range across both REST and client SDK joins.

  • Avoid toggling enable_string_uid frequently between requests; keep it consistent per project integration.

 

Corresponding Document / Link

Related to

Related articles