Messages

Overview

Every conversation consists of an ordered sequence of Messages. Messages alternate between the user (the human website visitor) and the assistant (the AI agent), enriched with structured metadata, citations, and suggested quick actions.

Message Schema Reference

interface AsiystMessage {
  id: string;                      // msg_01h9x...
  conversationId: string;          // conv_01h9x...
  role: "user" | "assistant" | "system";
  content: string;                 // Markdown formatted text
  citations?: AsiystCitation[];    // Knowledge grounding references
  suggestedActions?: string[];     // Quick-reply chips
  createdAt: string;               // ISO 8601 timestamp
  latencyMs?: number;              // Total generation latency
}

Citation Object Structure

When knowledge grounding is active, assistant responses contain citation objects pointing directly to the verified source documents:

interface AsiystCitation {
  sourceId: string;        // src_9f8a2b3c4d
  sourceTitle: string;     // "Enterprise SLA & Security Whitepaper"
  sourceUrl?: string;      // "https://docs.acme.com/sla"
  snippet: string;         // Exact indexed text excerpt used
  similarityScore: number; // 0.89 (Cosine similarity)
}

Programmatic Message Dispatch

You can send messages on behalf of the user or inject assistant announcements programmatically:

import { Asiyst } from "@asiyst/sdk";
// Send a user prompt as if typed
await Asiyst.sendMessage("What are your enterprise support hours?");
// Make the assistant speak a proactive announcement
Asiyst.say("Don't forget to check our API reference for updated SDK methods!");

Streaming Token Events

Listen to incremental token chunks to build custom UI chat interfaces:

Asiyst.on("message:token", ({ token, messageId }) => {
  // Append token to custom DOM container
  customChatContainer.textContent += token;
});
Asiyst.on("message:complete", (fullMessage) => {
  console.log("Completed response:", fullMessage.content);
  console.log("Sources cited:", fullMessage.citations);
});