Skip to main content
Send real-time messages to agents deployed on the www.bithuman.ai platform. Make agents speak proactively or inject background knowledge to improve their responses.
This API is for agents created on the bitHuman platform, not for local SDK agents.

​
Make Agent Speak

POST /v1/agent/{agent_code}/speak
Triggers the agent to speak a message to users in the session. Request Body
ParameterTypeRequiredDescription
messagestringYesText the agent will speak
room_idstringNoTarget a specific room. If omitted, delivers to all active rooms.
Response 
{
  "agent_code": "A12345678",
  "context_type": "speak",
  "delivered_to_rooms": 1
}
Example 
import requests

response = requests.post(
    "https://api.bithuman.ai/v1/agent/A12345678/speak",
    headers={
        "Content-Type": "application/json",
        "api-secret": "YOUR_API_SECRET"
    },
    json={
        "message": "We have a 20% discount available today.",
        "room_id": "customer_session_1"
    }
)
print(response.json())

​
Add Context

POST /v1/agent/{agent_code}/add-context
Adds background knowledge the agent will use to inform future responses. Can also trigger speech by setting type to speak. Request Body
ParameterTypeRequiredDefaultDescription
contextstringYes—Context text or message to speak
typestringNoadd_contextadd_context to inject knowledge silently, speak to trigger speech
room_idstringNo—Target a specific room. If omitted, delivers to all active rooms.
Response 
{
  "agent_code": "A12345678",
  "context_type": "add_context",
  "delivered_to_rooms": 1
}

​
Adding background context

import requests

response = requests.post(
    "https://api.bithuman.ai/v1/agent/A12345678/add-context",
    headers={
        "Content-Type": "application/json",
        "api-secret": "YOUR_API_SECRET"
    },
    json={
        "context": "Customer has VIP status. Preferred name: Alex. Account since 2021.",
        "type": "add_context",
        "room_id": "vip_session_42"
    }
)

​
Triggering speech via add-context

response = requests.post(
    "https://api.bithuman.ai/v1/agent/A12345678/add-context",
    headers={
        "Content-Type": "application/json",
        "api-secret": "YOUR_API_SECRET"
    },
    json={
        "context": "Your issue has been resolved. Let me know if you need anything else.",
        "type": "speak",
        "room_id": "support_session_1"
    }
)

​
Error Codes

HTTP StatusError CodeDescription
401UNAUTHORIZEDInvalid or missing api-secret
404AGENT_NOT_FOUNDNo agent with the given code exists
404NO_ACTIVE_ROOMSAgent has no active sessions
422VALIDATION_ERRORInvalid request body (e.g., bad type value)