Send messages

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "message": "<string>",
  "images": [
    "<string>"
  ],
  "files": [
    {}
  ],
  "caller_id": "<string>",
  "skills": [
    {}
  ],
  "messages": [
    {}
  ]
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages"

payload = {
    "type": "<string>",
    "message": "<string>",
    "images": ["<string>"],
    "files": [{}],
    "caller_id": "<string>",
    "skills": [{}],
    "messages": [{}]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    message: '<string>',
    images: ['<string>'],
    files: [{}],
    caller_id: '<string>',
    skills: [{}],
    messages: [{}]
  })
};

fetch('https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'message' => '<string>',
    'images' => [
        '<string>'
    ],
    'files' => [
        [
                
        ]
    ],
    'caller_id' => '<string>',
    'skills' => [
        [
                
        ]
    ],
    'messages' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

POST

api

sessions

{id}

messages

Send messages

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "message": "<string>",
  "images": [
    "<string>"
  ],
  "files": [
    {}
  ],
  "caller_id": "<string>",
  "skills": [
    {}
  ],
  "messages": [
    {}
  ]
}
'

import requests

url = "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages"

payload = {
    "type": "<string>",
    "message": "<string>",
    "images": ["<string>"],
    "files": [{}],
    "caller_id": "<string>",
    "skills": [{}],
    "messages": [{}]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    message: '<string>',
    images: ['<string>'],
    files: [{}],
    caller_id: '<string>',
    skills: [{}],
    messages: [{}]
  })
};

fetch('https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'message' => '<string>',
    'images' => [
        '<string>'
    ],
    'files' => [
        [
                
        ]
    ],
    'caller_id' => '<string>',
    'skills' => [
        [
                
        ]
    ],
    'messages' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://agp.eu.hcompany.ai/api/v2/sessions/{id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"message\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"files\": [\n    {}\n  ],\n  \"caller_id\": \"<string>\",\n  \"skills\": [\n    {}\n  ],\n  \"messages\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

Sends one or more messages to a session: extra instructions, answers to the agent’s questions, or a new direction. The agent reads them on its next step. Delivery adapts to the session’s state: a paused session is resumed first, a queued session buffers the message until it starts, and a finished session restarts (back to pending, subject to your token budget) with the message delivered to the relaunched agent. Returns 202 Accepted. The message is delivered asynchronously.

Path parameters

string

required

The session ID.

Request body

Send either a single message or a batch, discriminated by type.

Single message

string

default:"user_message"

"user_message". May be omitted.

string

required

The message text.

string[]

Base64 data URIs to attach (e.g. data:image/png;base64,...).

object[]

Files to attach, up to 10 and 7 MB in total. Each is { name, source, type: "base64", media_type? } (media_type is guessed if omitted). Saved under files/ in a workstation or code sandbox workspace, and ~/Downloads on a cloud browser.

string

default:"user"

The sender. Leave it unset for normal user input.

object[]

Skills for this message only, as inline skill objects (name, description, body). The agent gets their instructions with this message; the agent’s own skills are unchanged. A skill with files returns 422: add those to the agent’s skills instead.

"skills": [
  {"name": "team-tone", "description": "Write like our team", "body": "Answer in three short bullets."}
]

Batch

string

required

"batch".

object[]

required

At least one single-message object, processed in order.

Examples

Send a single message

hai sessions send "$SESSION_ID" 'Focus on hotels near Kiyomizu-dera temple, under $200/night'

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user_message",
    "message": "Focus on hotels near Kiyomizu-dera temple, under $200/night"
  }'

from hai_agents import Client
from hai_agents.sessions import SendSessionMessagesRequestBody_UserMessage

client = Client()

client.sessions.send_session_messages(
    session_id,
    request=SendSessionMessagesRequestBody_UserMessage(
        message="Focus on hotels near Kiyomizu-dera temple, under $200/night",
    ),
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.sessions.sendSessionMessages({
  id: sessionId,
  body: {
    type: "user_message",
    message: "Focus on hotels near Kiyomizu-dera temple, under $200/night",
  },
});

Send a batch of messages

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/messages \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "batch",
    "messages": [
      {"type": "user_message", "message": "Also check availability for June 15-20"},
      {"type": "user_message", "message": "I prefer traditional ryokans over modern hotels"}
    ]
  }'

from hai_agents import Client, UserMessageEvent
from hai_agents.sessions import SendSessionMessagesRequestBody_Batch

client = Client()

client.sessions.send_session_messages(
    session_id,
    request=SendSessionMessagesRequestBody_Batch(
        messages=[
            UserMessageEvent(message="Also check availability for June 15-20"),
            UserMessageEvent(message="I prefer traditional ryokans over modern hotels"),
        ],
    ),
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.sessions.sendSessionMessages({
  id: sessionId,
  body: {
    type: "batch",
    messages: [
      { type: "user_message", message: "Also check availability for June 15-20" },
      { type: "user_message", message: "I prefer traditional ryokans over modern hotels" },
    ],
  },
});

Errors

Status	Cause
`402`	The message would restart a finished session, but your organization’s token budget is exhausted. See Plans and limits.
`404`	Session not found or you don’t have access.
`422`	Invalid message body, for example an image that isn’t a decodable base64 data URI, or a message skill with `files`.
`429`	The message would restart a finished session, but no slot is free: you are at your concurrency limit, or the platform is at capacity. `detail[].type` says which (see Quota errors). The session stays finished and the message is not delivered. A restart never queues, so retry later.

Agents

Environments

Sessions

Skills

Vaults

Browser Profiles

Webhooks

Schedules

Send messages

Path parameters

Request body

Single message

Batch

Examples

Send a single message

Send a batch of messages

Errors

​Path parameters

​Request body

​Single message

​Batch

​Examples

​Send a single message

​Send a batch of messages

​Errors

Path parameters

Request body

Single message

Batch

Examples

Send a single message

Send a batch of messages

Errors