Send Conversation Message

curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "And who created it?",
  "mode": "queue"
}
'

import requests

url = "https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages"

payload = {
    "text": "And who created it?",
    "mode": "queue"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: 'And who created it?', mode: 'queue'})
};

fetch('https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_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([
    'text' => 'And who created it?',
    'mode' => 'queue'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages"

	payload := strings.NewReader("{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}"

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

{
  "action": "queued",
  "message_id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f",
  "queue_depth": 1,
  "steer_target": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

agents

{agent_id}

conversations

{conversation_id}

messages

Send Conversation Message

curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "And who created it?",
  "mode": "queue"
}
'

import requests

url = "https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages"

payload = {
    "text": "And who created it?",
    "mode": "queue"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: 'And who created it?', mode: 'queue'})
};

fetch('https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_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([
    'text' => 'And who created it?',
    'mode' => 'queue'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages"

	payload := strings.NewReader("{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents/{agent_id}/conversations/{conversation_id}/messages")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"And who created it?\",\n  \"mode\": \"queue\"\n}"

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

{
  "action": "queued",
  "message_id": "9d9d9d9d-8c8c-7b7b-6a6a-5f5f5f5f5f5f",
  "queue_depth": 1,
  "steer_target": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

mode=auto queues the message while a turn is running and signals started when the conversation is idle. mode=queue queues the message while a turn is running. mode=steer hands the message to the running turn so the agent takes it into account at its next skill call. Check is_steerable on Run State first. mode=interrupt stops the running turn and runs this message as the next turn. When no turn is running, queue and steer also signal started and queue nothing. Run the turn yourself with Run Conversation Turn. On a CLI agent whose process is still live, every mode signals steered: the message goes straight to that process. A started response means the message was not enqueued (queue_depth: 0): the conversation is idle, so run the turn yourself with Run Conversation Turn passing id = conversation_id. A queued response means it waits behind the running turn; if a stream is open on that turn it runs next on the same stream, otherwise run the queue with Drain Queue. See the Conversations overview for the full conversation model.

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

agent_id

string

required

conversation_id

string

required

Body

application/json

Body of the chat-backend messages / steer endpoints.

text

string

default:""

files

string[]

mode

enum<string>

default:auto

How an inbound message to a (possibly running) conversation is handled.

Available options:

auto,

queue,

steer

idempotency_key

string | null

user

User · object | null

Response

Successful Response

Result of accepting an inbound message for a running conversation.

action

string

required

message_id

string | null

queue_depth

integer

default:0

steer_target

string | null

Overview

REST API - Conversations

REST API - Agents

REST API - Tasks

Agent Workspace

REST API - Knowledge

REST API - Skills

REST API - Workflows

REST API - Custom Functions

REST API - Scheduled Tasks

REST API - Self-Schedules

REST API - Misc

SDK: get started

SDK integrations

Memory

Knowledge

Channels and webhooks

Skills in code

Advanced

CLI Reference

SDK Reference

Send Conversation Message

Authorizations

Path Parameters

Body

Response