Skip to main content
POST
/
v3
/
video-agents
/
sessions
/
{session_id}
/
messages
Send message to Video Agent session
curl --request POST \
  --url https://api.heygen.com/v3/video-agents/sessions/{session_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "message": "<string>",
  "avatar_id": "<string>",
  "voice_id": "<string>",
  "files": [
    {
      "type": "<string>",
      "url": "<string>"
    }
  ],
  "auto_proceed": false
}
'
{}

Authorizations

​
x-api-key
string
header
required

HeyGen API key. Obtain from your HeyGen dashboard.

Path Parameters

​
session_id
string
required

Session ID

Body

application/json

Request body for sending a follow-up message to a session.

​
message
string
required

Text message to the agent

Required string length: 1 - 10000
​
avatar_id
string | null

Override avatar for this message

​
voice_id
string | null

Override voice for this message

​
files
(AssetUrl · object | AssetId · object | AssetBase64 · object)[] | null

Optional file attachments (max 20 files)

Maximum array length: 20

Asset input via publicly accessible HTTPS URL.

​
auto_proceed
boolean
default:false

If true, skip interactive review and go straight to video generation (no storyboard approval step)

Response

Successful response

​
data
SendMessageResponse · object

Response from sending a message to a session.