Conversations API

Send messages to the AI assistant and receive contextual responses.

Widget users

If you're using the Embeddable Widget, the widget handles conversations automatically. It uses dedicated widget endpoints (POST /widget/message) instead of the endpoints below. You don't need to call these endpoints directly — the widget's built-in UI manages the full conversation flow.

Send a message

POST /api/conversations/message
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "What should I enter in the account number field?",
  "context": {
    "url": "https://app.example.com/registration",
    "title": "Registration Form",
    "forms": [
      {
        "id": "reg-form",
        "fields": [
          {
            "name": "account_number",
            "type": "text",
            "label": "Account Number",
            "required": true,
            "placeholder": "Enter your 10-digit account number"
          }
        ]
      }
    ]
  },
  "conversationId": "optional-existing-conversation-id"
}

Response:

{
  "response": "The account number field expects a 10-digit number...",
  "conversationId": "uuid",
  "sources": [
    {
      "type": "knowledge",
      "title": "Registration Guide",
      "url_pattern": "/registration"
    }
  ]
}

List conversations

GET /api/conversations
Authorization: Bearer <token>

Get conversation history

GET /api/conversations/:id/messages
Authorization: Bearer <token>

Context object

The context object tells the AI about the user's current page. The more context you provide, the better the answers:

interface PageContext {
  url: string;
  title: string;
  forms?: FormContext[];
  selectedText?: string;
  pageStructure?: {
    headings: string[];
    navigation: string[];
  };
}

interface FormContext {
  id?: string;
  action?: string;
  method?: string;
  fields: FieldContext[];
}

interface FieldContext {
  name: string;
  type: string;
  label?: string;
  placeholder?: string;
  required?: boolean;
  options?: string[];
  value?: string;
}

aviso

Avoid sending actual field values in the context unless necessary. Use field metadata (labels, types, placeholders) for context. If you must send values, ensure PII masking is enabled.