Creating Conversations

Overview

Conversations can be created in three ways:

1. Automatic: The SDK creates a conversation when a visitor taps the floating avatar or clicks a suggested prompt chip.

1. Client Programmatic: Your frontend application calls Asiyst.conversations.create() in response to custom UI events (e.g. clicking a "Help with this form" button).

1. Server-Side REST API: Your backend creates a conversation context using secret API keys and passes the token to the frontend.

Automatic Client Initialization

In standard installations, no explicit creation code is needed. When the SDK loads, it listens for visitor clicks on the avatar widget:

import { Asiyst } from "@asiyst/sdk";
// The SDK automatically handles session bootstrap and conversation creation
await Asiyst.init({
  projectId: "proj_9f8a2b3c4d",
  publicKey: "pk_live_8e7d6c5b4a3f2e1d",
});

Programmatic Creation via SDK

To open the chat programmatically with initial context (for example, when a user clicks a "Request AI Breakdown" button):

import { Asiyst } from "@asiyst/sdk";
async function openCheckoutSupport() {
  const conversation = await Asiyst.conversations.create({
    initialMessage: "I see you are having trouble with Stripe 3DS verification. Can I assist?",
    metadata: {
      cartTotal: 149.00,
      currency: "USD",
      checkoutStep: "payment_method",
    },
  });
  // Open the UI drawer immediately
  Asiyst.open();
}

Server-Side Creation via REST API

If you want to pre-populate conversations from your backend using administrative credentials:

curl -X POST https://asiyst.com/api/v1/projects/proj_9f8a2b3c4d/conversations \
  -H "Authorization: Bearer $ASIYST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorId": "usr_992140",
    "metadata": {
      "subscriptionTier": "Enterprise",
      "accountManager": "Alex Chen"
    }
  }'

Response Payload:

{
  "id": "conv_9a8b7c6d5e",
  "projectId": "proj_9f8a2b3c4d",
  "visitorId": "usr_992140",
  "status": "active",
  "createdAt": "2026-09-28T03:15:00Z"
}

Custom Metadata & Routing

You can attach arbitrary JSON metadata to any conversation. Metadata is:

• Visible in the Asiyst Analytics Dashboard conversation inspector.

• Passed to webhook event payloads on conversation.completed.

• Usable in custom system prompt templates via double-bracket variables (e.g., {{metadata.subscriptionTier}}).