Skip to content

5-Minute Quickstart

Add intelligent chat to your app in under 5 minutes. This guide uses OAuth mode for the fastest integration.

Before You Begin

You'll need a Coherence account to get started:

  1. A Coherence account - Sign up free
  2. Create your app and copy the App ID from the Coherence dashboard (will be used below)

  3. This guide assumes your app uses JWT authentication. Add the JWKS URL or JWT secret to your Coherence app.

    • Supports many popular providers such as Supabase, Clerk, Auth0, firebase, and more!
    • See our Backend SDK mode for custom authentication systems

Step 1: Add the SDK

Add this script tag to your HTML:

<script src="https://app.withcoherence.com/sdk/coherence-sdk.js"></script>

Step 2: Initialize Coherence

Add this JavaScript to your app:

// Initialize when your page loads
window.addEventListener('DOMContentLoaded', async () => {
  await Coherence.init({
    oauth: {
      enabled: true,
      appId: 'YOUR_APP_ID', // Get this from app.withcoherence.com
      getToken: async () => {
        // Return your user's auth token
        // Examples for common auth providers:

        // Firebase Auth
        // return await firebase.auth().currentUser?.getIdToken();

        // Auth0
        // return await getAccessTokenSilently();

        // Supabase
        // const { data: { session } } = await supabase.auth.getSession();
        // return session?.access_token;

        // Custom auth
        return localStorage.getItem('authToken');
      }
    }
  });
});

Step 3: Done! 🎉

That's it! A chat button will appear in the bottom-right of your app. Your users can now chat with an intelligent AI assistant.

Try It Out

  1. Click the chat button that appeared
  2. Ask a general question like "What can you help me with?" or "Tell me about this app"
  3. The AI will respond and be ready to help your users

Want the AI to access your data? Continue to Step 4 to connect your API endpoints.

Step 4: Add Your API Tools (Optional)

Now let's connect your API so the AI can access your app's data and functionality:

  1. Go to your Coherence Dashboard
  2. Navigate to your app settings
  3. Click "Add API Tools"
  4. Add your API endpoints as tools the AI can use
  5. The AI will automatically call these endpoints with proper authentication

Once configured, users can ask questions like:

  • "Show me my recent orders"
  • "What's my account status?"
  • "Update my profile settings"

The AI will use your API to fetch real data and perform actions on behalf of your users.

Customize the Experience

Most customizations are now configured in your Coherence dashboard for centralized management. However, you can still provide frontend fallbacks:

// Optional: Frontend fallbacks (overridden by backend config)
await Coherence.init({
  oauth: {
    enabled: true,
    appId: 'YOUR_APP_ID',
    getToken: async () => localStorage.getItem('authToken')
  },
  // These are fallbacks - dashboard settings take precedence
  modalConfig: {
    showTriggerButton: true,
    position: "bottom-right"
  }
});

Note: Trigger text, theme, and other UI settings are configured in your Coherence dashboard for easier management without code changes.

Pass Additional Context

// Optional: Include headers or cookies for your API
await Coherence.init({
  oauth: {
    enabled: true,
    appId: 'YOUR_APP_ID',
    getToken: async () => localStorage.getItem('authToken'),

    // Send additional headers with API requests
    getHeaders: async () => ({
      'X-User-Id': currentUser.id,
      'X-Workspace': currentWorkspace.id
    }),

    // Include specific cookies
    cookieNames: ['sessionId', 'preferences']
  },

  // Optional: Add context information for the AI
  extraContext: {
    userRole: 'admin',
    currentPage: 'dashboard',
    features: ['analytics', 'reporting']
  }
});

What is extraContext?

The extraContext parameter allows you to provide additional context information that gets passed to the AI with every conversation. This helps the AI understand the user's current situation and provide more relevant responses.

Coherence supports three types of context:

  1. Static context: Set once during initialization for app-wide context (extraContext)
  2. Dynamic context: Updated automatically for every message using a callback (getExtraContext)
  3. Per-message context: Provided when sending individual messages via sendMessage()

Context precedence (higher precedence overwrites lower): - Per-message context (highest) - Dynamic context from callback - Static context (lowest)

Examples of useful context: - Current user role or permissions - Active page or section of your app
- Selected items or filters - Available features or tools - Workspace or project information - User preferences or settings

Dynamic Context with Callback:

For context that changes based on your app's current state, use the getExtraContext callback. This function is automatically called for every message in both the default UI and programmatic sendMessage() calls:

await Coherence.init({
  oauth: {
    enabled: true,
    appId: 'YOUR_APP_ID',
    getToken: async () => localStorage.getItem('authToken')
  },
  // Dynamic context - called for every message
  getExtraContext: async () => {
    return {
      currentPage: window.location.pathname,
      userRole: await getCurrentUserRole(),
      selectedItems: getSelectedDashboardItems(),
      activeFilters: getActiveFilters(),
      timestamp: new Date().toISOString()
    };
  },
  // Static fallback context
  extraContext: {
    appVersion: '1.0.0',
    environment: 'production'
  }
});

Key benefits: - Automatic updates: Context is refreshed for every message without manual intervention - Works everywhere: Both default UI and sendMessage() calls use dynamic context - Error resilient: Falls back to static context if callback fails - Async support: Can make API calls or complex state calculations

Per-Message Context:

You can also pass context for individual messages using the sendMessage method:

// Send a message with specific context
await Coherence.sendMessage("Help me with this dashboard", {
  extraContext: {
    currentView: 'analytics',
    selectedTimeRange: 'last-30-days',
    chartType: 'revenue'
  }
});

When multiple context sources are provided, they are automatically merged with per-message context taking highest precedence, followed by dynamic context, then static context.

Common Questions

Q: How does Coherence access my data?
A: Coherence forwards your user's auth token to your API, just like your frontend does. We never store credentials.

Q: What if I don't use OAuth?
A: Check out Backend SDK mode for custom authentication systems.

Q: How do I configure what data the AI can access?
A: Add API tools in your dashboard (Step 4). You control exactly which endpoints the AI can call.

Q: Is this secure?
A: Yes! We use the same authentication as your app. Users can only access their own data. Learn more about security.

Get Help

Using custom authentication? See Backend SDK mode for legacy auth systems.