Altan
HomeDiscordStatus
HomeDiscordStatus
  1. Altan Frontend SDK
  • What is Altan?
  • Support Options
  • Projects
    • Create Your First Project
    • App Navigation & Settings
    • Building Tips
    • The Art of Prompting
    • Publishing Your App
    • Rollback and Checkpoints
    • Instantly Resolve Errors
  • Databases
    • Introduction
    • Security
    • Technical Overview
  • AI Agents
    • What is an AI Agent?
    • Create your first AI Agent
    • Tools
    • Interacting with Your AI Agent
    • Technical Overview
    • Altan Frontend SDK
      • Altan Frontend SDK
  • Flows
    • Create your first Flow
    • Automation basics
    • Adding modules
    • Types of modules
    • Passing data
    • Filters
    • Debugging
    • Retrigger events
    • Version History
    • Overwrite connection
    • Task credits
  • Integration
    • Magic Link
    • Altan Integrator
    • Create your integration
  • Authentication
    • Authentication
  • Payments
    • Checkout Session
    • Object Storage
  • Media
    • Media
  • Partner Program
    • Who are our Partners?
    • Partner Program Benefits
    • How to import projects into Altan
    • How to export projects from Altan
    • Work collaboratively
    • How to start on Altan
    • Become an Altan Partner
  • API Reference
    • account
      • Create Account
      • Get Account Gq
      • Get Account Public
      • Get Account Usage
      • Patch Account
      • Delete Account
      • Get Account Users
      • Create Custom Webhook
      • Create Media
      • Create Media From Url
      • Create Multiple Media
      • Create Token
      • Create Agent
      • Upsert Flow
      • Fetch User Account Notifications
      • Create Altaner
      • Get Selected Template Version
      • Get Latest Template Version
      • Get Template Version
      • Invite User
      • Create Interface
      • Get Members
      • Get Account Connections
      • Get Apikey
      • Delete Apikey
    • project
      • Get Altaner
      • Create Project V2
      • Update Altaner
      • Delete Altaner
      • Get Altaner Flows
      • Clone Altaner
      • Update Altaner Positions
      • Create Altaner Component
      • Update Altaner Component
      • Get Altaner Component
      • Atomic Update Altaner Component
      • Delete Altaner Component
      • Duplicate Altaner
      • Create Idea
    • interface
      • Start Dev Server
      • Get Dev Status
      • Send Dev Error To Agent
      • Revise Interface
      • Get Dev Errors
      • Log Error
      • Create Or Overwrite File
      • Update File
      • Create Multiple Files
      • Read File
      • Read Multiple Files
      • Delete File
      • Rename File
      • Update Files Pattern
      • Search In Files
      • Search And Replace
      • Preview Updates
      • Install Libraries
      • List Tree
      • List Tree Json
      • Get Repo Status
      • List Branches
      • Create Branch
      • Delete Branch
      • Switch Branch
      • Clone Repo
      • Merge Branch
      • Commit Changes
      • Get Diff Changes
      • Accept Changes
      • Discard Changes
      • Push Changes
      • Pull Changes
      • Reset Repo
      • Get Repo Log
      • Restore Main
      • Get Public Interface
      • Get Interface By Name
      • Get Interface
      • Update Interface
      • Delete Interface
      • Get Interface Screenshot
      • Update Interface With Ai
      • Publish Interface
      • Vercel Webhook
      • Get Deployment Status
      • Add Collaborator
      • Get Deployment Logs
      • Fix Deployment With Ai
      • Add Domain
      • Get Domains
      • Remove Domain
      • Verify Domain
      • Add Env Variables
      • Get Env Variables
      • Delete Env Variable
      • Sync Env Variables
      • Rollback Deployment
      • Get Commit Details
      • Restore To Commit
    • flows
      • modules
        • Fetch Module
        • Update Flow Module
        • Delete Module
        • Fetch Graph Module
        • Rename Module
        • Update Position In Canvas
        • Update In Edge Filter
        • Update Route Condition Filter
        • Add Condition
        • Get Available Variables For Mappings
      • hooks
        • Get Webhook
        • Update Hook
      • executions
        • Get File Signed Url
        • Stream Execution
      • Fetch Flow Execution
      • Fetch Flow
      • Update Flow
      • Delete Flow
      • Get Latest Execution
      • Fetch Flow Schema
      • Get Flow From Hook
      • Get Flow Hook
      • Fetch Flow Executions
      • Fetch Flow Executions
      • Upsert Flow Module
      • Add Flow Module
      • Create Flow Duplicate
      • Clone Flow Modules
      • Paste Flow Modules
      • Delete Modules
      • Update Edge
    • media
      • Get Media Url
      • Delete Media
      • Get Multiple Media
      • Get 3D Media
      • Delete Model
      • Create 3D Model
    • agents
      • tools
        • Patch Tool
        • Patch Tool
      • authorizaiton requests
        • Create Authorization Request
        • List Authorization Requests
        • Get Authorization Request
        • Delete Authorization Request
        • Reject Authorization Request
      • Get Altan Agents
      • List Voices
      • Get Agent
      • Update Agent
      • Delete Agent
      • Get Agent
      • Create And Add Tool To Agent
      • Remove Tool And Space
      • Get User Agent Dm Room
      • Get Agent Gate
      • Get Agent Member Usage
  1. Altan Frontend SDK

Altan Frontend SDK

Altan Frontend SDK#

The altan SDK let's you add chat rooms with AI Agents directly into your product.

Installation#

Usage#

Agent Mode (1-on-1 Chat)#

Chat with an AI agent. Automatically finds existing conversation or creates new one.
import { Room } from '@altanlabs/sdk';

<Room
  mode="agent"
  accountId="account-id"
  agentId="agent-123"
  guestInfo={{ first_name: "John", external_id: "user-123" }}
/>

Compact Mode (Floating Widget)#

Shows a floating text field that expands to full chat on click.
<Room
  mode="compact"
  ....
/>
When to use it: Use it for projects where the agent is a core element. Like FAQs agents or simple assistants. When in doubt, favor the use compact mode.

SDK Parameters#

PropTypeRequiredDescription
mode"agent"✅Chat with agent or join room
accountIdstring✅Your Altan account ID
agentIdstring✅Agent ID (required for agent mode)
guestInfoobject❌User info (name, external_id, email)
guestInfo:
external_id (string): user’s ID in your Supabase users table (enables history).
first_name, last_name, email (strings): user’s personal info.
MUST RULE: All IDs and user data must be loaded dynamically from your database. Do NOT hard‑code any values.

How to fetch each value#

1.
accountId
If not in memory: use get_project action.
2.
agentId
If missing: prompt the user (or upstream system) to supply the correct identifier.
3.
guestInfo.external_id
Retrieve from your Supabase users table’s primary key for the current user.
4.
guestInfo.first_name, last_name, email
Collect from your own user store or prompt the user on first access.

Requirements#

Agents must be public for agent mode to work
Allowlist your domains in Altan dashboard for better security

Guest Info#

You control whether history is enabled by supplying guestInfo. You must follow these rules exactly when populating it:
1.
external_id is the primary key for user history.
You must supply guestInfo.external_id only if it matches an existing user ID in your users table.
If you cannot reliably resolve the current session to a user, set it to null.
This value is how you load and recover per-user conversation history; it must come from the database.
2.
Never hardcode or fabricate data.
Do not hardcode first_name, last_name, email, or external_id (except null).
Do not generate external_id dynamically (e.g., guest_${Date.now()}) or make up any user fields.
Only pull values from your authenticated user record in the database. If unavailable, use null.
3.
Respect your logging/history mechanism.
If your project has a logging or history system enabled, you must fetch all guestInfo values directly from the canonical user store (users table).
If there is no logging/history mechanism or you cannot securely identify the user, you must leave those fields as null.
4.
Enforce authentication when you rely on history.
Any feature that uses conversation history must require that the user is authenticated so guestInfo.external_id is valid and consistent.
5.
Validate before use.
Before passing external_id into the SDK, verify it exists in the users table. If the required users table is missing, trigger your orchestration logic to create it. Do not proceed assuming history will work without that validation.

Correct Usage Example#

const user = await fetchCurrentUserFromDB(); // must come from your users table

<Room
  mode="agent"
  accountId={resolveAccountId()}    // loaded dynamically
  agentId={resolveAgentId()}        // loaded dynamically
  guestInfo={{
    first_name: user?.first_name || null,
    last_name: user?.last_name || null,
    email: user?.email || null,
    external_id: user?.id || null, // MUST be an existing user ID
  }}
/>

Incorrect / Forbidden Examples#

guestInfo={{
  first_name: "Guest",                    // ❌ hardcoded
  external_id: `guest_${Date.now()}`,     // ❌ invented
  email: "someone@example.com",           // ❌ hardcoded
  last_name: "User"                       // ❌ hardcoded
}}
guestInfo={{
  external_id: "nonexistent-id",          // ❌ not verified against users table
}}

Customization#

Agent Mode#

PropertyTypeDefaultDescription
tabsbooleantrueShow/hide tab navigation
conversation_historybooleantrueShow/hide conversation history
membersbooleantrueShow/hide members panel
settingsbooleantrueShow/hide settings panel
themestringundefinedTheme mode: 'light', 'dark', or 'system'
titlestringundefinedCustom title
descriptionstringundefinedCustom description
voice_enabledbooleantrueEnable/disable voice functionality
suggestionsstring[][]Predefined message suggestions

Compact Mode (Widget Mode)#

PropertyTypeDefaultDescription
primary_colorstring#007bffPrimary color (hex) for buttons and accents
background_colorstring#ffffffBackground color (hex) for the widget
background_blurbooleantrueEnable glassmorphism background blur effect
positionstringbottom-centerPosition: 'bottom-right', 'bottom-left', 'bottom-center'
widget_widthnumber350Widget width in pixels
room_widthnumber450Room width in pixels when expanded
room_heightnumber600Room height in pixels when expanded
border_radiusnumber16Border radius in pixels for rounded corners

Complete Example#

import React from 'react';
import { Room } from '@altanlabs/sdk';

function App() {
  return (
    <div style={{ height: '600px' }}>
      <Room
        mode="agent"
        accountId="altan-account-id"
        agentId="agent-123"
        guestInfo={{
          first_name: 'Jane',
          last_name: 'Doe',
          email: 'jane@example.com',
          external_id: 'user-456'
        }}
        onConversationReady={(room) => console.log('Chat ready!')}
        onAuthSuccess={(guest) => console.log('User authenticated:', guest.id)}
      />
    </div>
  );
}
Modified at 2025-08-05 09:59:09
Previous
Technical Overview
Next
Create your first Flow
Built with