Chat API

Send messages to an agent and receive AI-generated responses.

Send a Message


POST /api/public/agents/{agentId}/chat

Path Parameters

Parameter	Type	Required	Description
`agentId`	`string`	Yes	The unique identifier of the agent

Request Body

Field	Type	Required	Description
`message`	`string`	Yes	The user’s message text
`sessionId`	`string`	Yes	A unique session identifier for conversation continuity
`visitorId`	`string`	No	Persistent visitor identifier (survives sessions)
`visitorEmail`	`string`	No	Visitor’s email address (used for lead capture)
`visitorName`	`string`	No	Visitor’s display name
`metadata`	`object`	No	Arbitrary key-value metadata to attach to the message

Headers

Header	Value	Required
`Authorization`	`Bearer agx_live_YOUR_KEY`	Yes
`Content-Type`	`application/json`	Yes

Response

The response is a streaming text response by default. The Content-Type is text/plain with chunked transfer encoding. Each chunk contains a portion of the agent’s response as it is generated.

The response also includes these headers:

Header	Description
`X-Conversation-Id`	The conversation ID for this session
`X-Message-Id`	The unique ID of the assistant’s response message
`X-UI-Spec`	JSON-encoded rich UI specification (when applicable)

Examples

cURL


curl -X POST https://app.agentix.cl/api/public/agents/abc123/chat \
  -H "Authorization: Bearer agx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you have under $50?",
    "sessionId": "visitor-session-001",
    "visitorEmail": "customer@example.com"
  }'

JavaScript (fetch)


const response = await fetch(
  'https://app.agentix.cl/api/public/agents/abc123/chat',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer agx_live_YOUR_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: 'What products do you have under $50?',
      sessionId: 'visitor-session-001',
    }),
  }
)
 
// Read streaming response
const reader = response.body.getReader()
const decoder = new TextDecoder()
 
while (true) {
  const { done, value } = await reader.read()
  if (done) break
  const chunk = decoder.decode(value)
  process.stdout.write(chunk)
}

Python (requests)


import requests
 
response = requests.post(
    'https://app.agentix.cl/api/public/agents/abc123/chat',
    headers={
        'Authorization': 'Bearer agx_live_YOUR_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'message': 'What products do you have under $50?',
        'sessionId': 'visitor-session-001',
    },
    stream=True,
)
 
for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
    print(chunk, end='')

Error Responses

Status	Code	When
`400`	`INVALID_AGENT_ID`	Agent ID is missing or empty
`400`	`INVALID_REQUEST_DATA`	Missing `message` or `sessionId`
`400`	`INVALID_JSON`	Request body is not valid JSON
`401`	`MISSING_API_KEY`	No API key provided
`401`	`INVALID_API_KEY`	API key is invalid
`403`	`AGENT_NOT_PUBLIC`	Agent is not public
`403`	`AGENT_INACTIVE`	Agent status is not active
`403`	`ORG_MISMATCH`	API key org does not match agent org
`403`	`DOMAIN_NOT_ALLOWED`	Request origin not in allowed domains
`404`	`AGENT_NOT_FOUND`	Agent does not exist
`429`	`RATE_LIMITED`	Rate limit exceeded (60 req/min)

Conversation Continuity

The sessionId is the key to maintaining conversation context. Messages with the same sessionId are grouped into a single conversation. The agent retains the full message history for context.

Best practices:

Use a consistent sessionId per user session (e.g., browser session ID)
Generate a new sessionId when the user explicitly starts a new conversation
The visitorId persists across sessions for returning user identification

Rich UI Responses

When an agent has ecommerce tools enabled and generates structured data (product cards, order details, etc.), the X-UI-Spec response header contains a JSON-encoded UI specification. Your client can parse this to render rich components.


{
  "type": "product-grid",
  "data": [
    {
      "title": "Blue Widget",
      "price": "$24.99",
      "image": "https://...",
      "url": "https://..."
    }
  ]
}