Documentation

Complete guide to setting up Warpway on your website

Overview

Warpway allows you to create AI-powered actions and widgets for your website. This guide walks you through the complete setup process, from installation to enabling your first live action.

Time to complete: 10-15 minutes

What you'll need: Access to your website's HTML, admin access to your Warpway dashboard

1Create Your Site

First, you need to register your website with Warpway.

Steps:

  1. Log in to your Warpway dashboard
  2. Navigate to the onboarding flow
  3. Enter your site name (e.g., "My Awesome App")
  4. Add your production domain (e.g., app.example.com)
  5. Optionally add a staging domain for testing
  6. Click "Continue" to save your site

Note: Enter domains without the https:// prefix

2Install the SDK

Add the Warpway SDK to your website to enable recording and widget functionality. Choose between script tag (easiest) or npm package (for bundled apps).

npm versionnpm downloadsbundle size

RECOMMENDEDOption 1: Script Tag (Static Sites)

Perfect for static sites, HTML pages, or any site without a build step.

  1. Copy the SDK script tag from the onboarding flow (includes your site ID)
  2. Paste it into the <head> section
  3. Deploy your changes
  4. Click "Check My Site" in the dashboard to verify

Example:

<script async src="https://unpkg.com/@warpway/sdk@0.1.49/dist/sdk.js"
  data-warp-site="YOUR_SITE_ID"
  data-warp-dev="query:param:warpway=dev"
  data-warp-widget="off"></script>

Option 2: npm Package (React, Next.js, Vue, etc.)

For modern frameworks with build tools. Includes TypeScript support.

Install via npm:

npm install @warpway/sdk

Usage Example (React/Next.js):

// components/WarpwaySDK.tsx
'use client';

import { useEffect } from 'react';

export default function WarpwaySDK() {
  useEffect(() => {
    // Create config script tag
    const script = document.createElement('script');
    script.src = '#warpway-sdk-config';
    script.setAttribute('data-warp-site', 'YOUR_SITE_ID');
    script.setAttribute('data-warp-widget', 'on');
    document.head.appendChild(script);

    // Import SDK
    import('@warpway/sdk');
  }, []);

  return null;
}

Configuration Options:

data-warp-site: Your unique site identifier (from dashboard)

data-warp-dev: Enables recorder mode with ?warpway=dev parameter

data-warp-widget: Set to "off" during setup, "on" to enable

3Create an API Key

API keys authenticate your recording sessions and keep your workflows secure.

Steps:

  1. In the onboarding flow, enter a name for your API key (e.g., "Recording Key")
  2. Click "Create API Key"
  3. Copy the key immediately - it won't be shown again for security reasons
  4. Store it securely (you'll need it in the next step)

Security Warning: Never share your API key publicly or commit it to version control. You can create multiple keys and revoke them anytime in Settings.

4Record Your First Action

Use the recorder sidebar to capture a workflow you want to automate.

Steps:

  1. Click "Open Recorder" in the onboarding flow (or visit your site with ?warpway=dev in the URL)
  2. Look for the Warpway recorder sidebar on the right side of your site
  3. Paste your API key into the sidebar and click "Save API Key"
  4. Click "Start Recording"
  5. Perform the workflow you want to automate (clicks, form fills, navigation, etc.)
  6. Click "Finalize" when done
  7. Give your action a clear name and description

Tip: Keep recordings focused on a single task or workflow. Use clear, descriptive names that explain what the action does.

5Review and Publish

Review your recorded action and publish it to make it available.

Steps:

  1. Navigate to your draft action in the dashboard
  2. Review the recorded steps and selectors to ensure they're correct
  3. Add intents - natural language phrases users might say to trigger this action
  4. Set visibility to "Admin Only" for initial testing, or "All Users" to make it public
  5. Click "Publish" to make the action live

Intents Example: For a "Book a Demo" action, add intents like: "schedule a demo", "book a meeting", "talk to sales"

6Enable the Widget

Turn on the end-user widget to allow users to discover and run actions through natural language.

Steps:

  1. In the onboarding flow or site settings, toggle the widget to "Enabled"
  2. Visit your production site to see the floating widget button
  3. Click the widget and describe an action to test it
  4. Customize widget appearance and position in Settings (optional)

Widget Features:

  • Natural language interface - users describe what they want in plain English
  • Automatic action matching based on intent
  • Real-time execution with visual feedback
  • No coding required for end users

✓You're All Set!

Congratulations! Your site is now powered by Warpway. Users can discover and run your actions through the widget.

Next Steps:

  • Create more actions to automate additional workflows
  • Monitor action runs and success rates in the Dashboard
  • Customize widget appearance and behavior in Settings
  • Invite team members to collaborate
  • Review analytics to understand user behavior

Troubleshooting

Common issues and how to resolve them.

SDK Not Detected

The dashboard says "SDK not detected yet" when you click "Check My Site".

Solutions:

  • Verify the script tag is in the <head> section of your HTML
  • Check that your domain is configured correctly (without https://)
  • Make sure the data-warp-site ID matches your site ID in the dashboard
  • Clear your browser cache and refresh the page
  • Wait a few seconds after adding the script, then try checking again
  • Check browser console for any JavaScript errors that might prevent SDK loading
  • Ensure your site is accessible from the public internet (not localhost or behind a firewall)

Recorder Sidebar Not Appearing

You visit your site but don't see the recorder sidebar on the right side.

Solutions:

  • Ensure the URL includes ?warpway=dev query parameter
  • Verify the SDK is properly installed (see "SDK Not Detected" above)
  • Check that data-warp-dev="query:param:warpway=dev" is in your script tag
  • Try using the "Open Recorder" button in the dashboard instead
  • Check browser console for errors
  • Try a different browser or incognito mode
  • Ensure no CSS on your site is hiding elements with high z-index values

API Key Invalid or Not Working

You paste your API key into the recorder but get an "Invalid API key" error.

Solutions:

  • Double-check you copied the entire API key without extra spaces
  • Verify the API key hasn't been revoked in Settings → API Keys
  • Create a new API key and try again
  • Ensure you're using the correct site (check site ID in both recorder and dashboard)
  • Check that your browser isn't blocking API requests (CORS issues)

Widget Not Showing on Production Site

You enabled the widget but don't see it on your production site.

Solutions:

  • Verify widget is enabled in Settings → Site Settings
  • Remove data-warp-widget="off" from your script tag (or change to "on")
  • Make sure you're visiting without ?warpway=dev parameter (widget and recorder are separate)
  • Check that at least one action is published and visible to users
  • Clear your browser cache and hard refresh
  • Verify your production domain matches what's configured in the dashboard
  • Check browser console for JavaScript errors

Recording Failed or Steps Not Captured

Your recording didn't capture all the steps or failed to finalize.

Solutions:

  • Ensure you're authenticated with a valid API key before starting the recording
  • Avoid navigating away from your site domain during recording
  • Click slowly and wait for elements to load between actions
  • If recording fails, try recording a simpler workflow first to test
  • Check that the elements you're clicking have stable selectors (not randomly generated IDs)
  • Check browser console for any errors during recording
  • Try breaking complex workflows into multiple smaller actions

Widget Can't Find Matching Action

Users describe what they want, but the widget says "No matching action found".

Solutions:

  • Add more intent phrases to your action that match how users might describe it
  • Use natural, conversational language in your intent phrases
  • Check that the action is published and visible (not "Admin Only" if testing as regular user)
  • Try different phrasings - the AI matches based on semantic similarity
  • Ensure your action has a clear name and description to help with matching
  • Test your intents by typing them exactly into the widget

Action Found But Execution Failed

The widget finds your action, but it fails when trying to execute it.

Solutions:

  • Check that the starting URL of the action matches the current page
  • Verify that element selectors are still valid (your site structure may have changed)
  • Try re-recording the action if your site's HTML structure was updated
  • Check the action logs in the dashboard for specific error messages
  • Ensure required form fields are visible and accessible
  • Test the action manually by clicking through the workflow yourself
  • If your site uses dynamic content, the timing might be off - consider re-recording with longer waits

CORS or Connection Errors

Browser console shows CORS errors or "Failed to fetch" messages.

Solutions:

  • Verify your domain is correctly configured in the dashboard settings
  • Ensure the domain you're visiting exactly matches what's configured (including subdomains)
  • Check that your site isn't blocking third-party scripts or APIs
  • If using a Content Security Policy, whitelist https://unpkg.com and the Warpway API domain
  • Try testing on a different domain (staging vs production)

Still Need Help?

If you're still experiencing issues after trying these troubleshooting steps, we're here to help!

Email Support

marcus@warpway.ai

Check the Dashboard

Look for error messages in the action logs and site health status in your Warpway dashboard