Conversations API

Retrieve conversation history and update conversation metadata.

Get Conversation


GET /api/public/agents/{agentId}/conversations/{sessionId}

Fetches the message history for a specific conversation session.

Path Parameters

Parameter	Type	Required	Description
`agentId`	`string`	Yes	The agent’s unique identifier
`sessionId`	`string`	Yes	The session identifier used when sending messages

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	`50`	Number of messages to return (max 100)
`offset`	`number`	`0`	Number of messages to skip (for pagination)

Headers

Header	Value	Required
`Authorization`	`Bearer agx_live_YOUR_KEY`	Yes

Response


{
  "id": "conv_abc123",
  "sessionId": "session-001",
  "agentId": "agent_xyz",
  "agentName": "Support Bot",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2025-01-15T10:30:00.000Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Our business hours are Monday to Friday, 9 AM to 6 PM EST.",
      "timestamp": "2025-01-15T10:30:02.500Z",
      "tokens": 45,
      "responseTime": 2500
    }
  ],
  "messageCount": 2,
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:02.500Z",
  "metadata": {
    "visitorId": "visitor_123",
    "visitorEmail": "user@example.com",
    "visitorName": "John",
    "source": "widget",
    "ipAddress": "192.168.1.1"
  }
}

Response Fields

Field	Type	Description
`id`	`string`	Internal conversation ID
`sessionId`	`string`	The session ID you provided
`agentId`	`string`	The agent ID
`agentName`	`string`	The agent’s display name
`messages`	`array`	Array of message objects
`messages[].id`	`string`	Unique message ID
`messages[].role`	`string`	`user` or `assistant`
`messages[].content`	`string`	Message text content
`messages[].timestamp`	`string`	ISO 8601 timestamp
`messages[].tokens`	`number`	Token count (assistant messages only)
`messages[].responseTime`	`number`	Response time in ms (assistant messages only)
`messageCount`	`number`	Total messages returned
`createdAt`	`string`	Conversation creation timestamp
`updatedAt`	`string`	Last update timestamp
`metadata`	`object`	Visitor and session metadata

Example


curl "https://app.agentix.cl/api/public/agents/abc123/conversations/session-001?limit=20" \
  -H "Authorization: Bearer agx_live_YOUR_KEY"

Error Responses

Status	Code	When
`400`	`INVALID_AGENT_ID`	Agent ID is missing
`400`	`INVALID_SESSION_ID`	Session ID is missing
`401`	`MISSING_API_KEY`	No API key provided
`403`	`AGENT_NOT_PUBLIC`	Agent is not public
`404`	`AGENT_NOT_FOUND`	Agent does not exist
`404`	`CONVERSATION_NOT_FOUND`	No conversation for this session

Update Conversation


PATCH /api/public/agents/{agentId}/conversations/{sessionId}

Updates conversation metadata such as visitor information, rating, and feedback.

Path Parameters

Parameter	Type	Required	Description
`agentId`	`string`	Yes	The agent’s unique identifier
`sessionId`	`string`	Yes	The session identifier

Request Body

All fields are optional. Include only the fields you want to update.

Field	Type	Description
`visitorEmail`	`string`	Visitor’s email address
`visitorName`	`string`	Visitor’s display name
`rating`	`number`	Conversation rating (1-5)
`feedback`	`string`	Text feedback from the visitor
`metadata`	`object`	Arbitrary key-value metadata

Headers

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

Response


{
  "success": true,
  "updated": {
    "visitorEmail": "user@example.com",
    "rating": 5,
    "feedback": "Very helpful!"
  }
}

Example


curl -X PATCH "https://app.agentix.cl/api/public/agents/abc123/conversations/session-001" \
  -H "Authorization: Bearer agx_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "feedback": "The agent was very helpful!",
    "visitorEmail": "customer@example.com"
  }'

Validation Rules

rating must be a number between 1 and 5
visitorEmail must be a valid email format (if provided)
metadata values must be JSON-serializable

Error Responses

Status	Code	When
`400`	`INVALID_RATING`	Rating is not a number between 1-5
`400`	`INVALID_JSON`	Request body is not valid JSON
`401`	`MISSING_API_KEY`	No API key provided
`404`	`AGENT_NOT_FOUND`	Agent does not exist
`404`	`CONVERSATION_NOT_FOUND`	Conversation not found