Skip to main content

​
What are remote interactions?

Remote interactions let your agent execute custom JavaScript code in the end-user’s browser during a live conversation. This enables your agent to interact with the webpage, access browser APIs, and perform client-side actions - like getting the user’s location, filling out a form, or reading data from the page.
Remote interactions only work with web widget deployments, since the code runs in the user’s browser.

​
Use cases

Use caseWhat the code does
GeolocationGet the user’s latitude/longitude for location-aware responses
Form interactionPre-fill or submit forms on the page
UI updatesShow/hide elements, display notifications, or update content
Local storageRead or write user preferences
ClipboardCopy information to the user’s clipboard
Page dataRead product details, cart contents, or other page data

​
Creating a remote interaction

Remote interactions are configured in the Export Widget settings under the Remote Interactions tab.
1

Open widget settings

Navigate to your agent and open the widget/export modal.
2

Go to Remote Interactions tab

Click the Remote Interactions tab. You’ll see a list of any existing interactions and an Add Remote Interaction button.
3

Click Add Remote Interaction

A form opens where you define your custom function.
4

Configure the interaction

Fill in the following fields:
  • Method Name (required) - A unique identifier using snake_case (e.g., get_user_location). Max 64 characters, must start with a letter.
  • Display Name (optional) - A human-readable name shown to the AI (e.g., “Get User Location”).
  • Function Description (required) - Explain what this function does so the AI knows when to call it. Minimum 10 characters.
  • Arguments - Define input parameters the function accepts (see below).
  • Returns (optional) - Describe what the function returns.
  • Function Code (required) - The JavaScript code that runs in the browser.
  • Custom Error Message (optional) - What to show if the function fails.
  • Timeout - How long to wait for completion (1-30 seconds, default 10).
  • Enabled - Toggle the interaction on or off.
5

Save

Click Save. The interaction is now available to the agent during widget conversations.

​
Defining arguments

Each remote interaction can accept parameters from the AI agent. For each argument, define:
FieldDescription
NameParameter name (alphanumeric and underscores)
Typestring, number, boolean, or object
DescriptionWhat this parameter is for
RequiredWhether the AI must provide this parameter
Click Add Argument to add parameters. Each argument name must be unique within the function.

​
Writing function code

The function code runs in the user’s browser and has access to:
  • data - The full RPC payload (includes payload and responseTimeout)
  • params - The parsed arguments from the AI agent
The function must return a string. If returning structured data, use JSON.stringify().

​
Example: Get user location

return new Promise((resolve, reject) => {
  if (!navigator.geolocation) {
    reject("Geolocation is not supported by this browser");
    return;
  }

  navigator.geolocation.getCurrentPosition(
    (position) => {
      resolve(JSON.stringify({
        latitude: position.coords.latitude,
        longitude: position.coords.longitude
      }));
    },
    (error) => {
      reject("Unable to retrieve location: " + error.message);
    },
    { timeout: params.timeout || 5000 }
  );
});

​
Example: Read page data

const productName = document.querySelector('.product-title')?.textContent;
const price = document.querySelector('.product-price')?.textContent;

return JSON.stringify({
  product: productName || "Unknown",
  price: price || "N/A"
});

​
Example: Show a notification

const notification = document.createElement('div');
notification.textContent = params.message;
notification.style.cssText =
  'position:fixed;top:20px;right:20px;padding:16px;' +
  'background:#10b981;color:white;border-radius:8px;z-index:9999;';
document.body.appendChild(notification);
setTimeout(() => notification.remove(), 3000);

return "Notification displayed";

​
Managing remote interactions

​
Viewing interactions

The Remote Interactions tab shows all defined methods with:
  • Method name (in monospace)
  • Display name (if set)
  • Description
  • Argument tags showing name and type
  • Enabled/disabled status

​
Editing

Click the edit icon on any interaction to modify its configuration.

​
Enabling / Disabling

Use the toggle switch to enable or disable an interaction without deleting it. Disabled interactions are not available to the agent.

​
Deleting

Click the delete icon and confirm to permanently remove an interaction.
Only enabled remote interactions are made available to the agent during widget conversations. Disabled interactions are saved but not callable.

​
Validation rules

FieldRule
Method nameMax 64 chars, starts with letter, alphanumeric + underscores only
Function descriptionMin 10 characters, max 255
ArgumentsEach must have name, type, and description; names must be unique
Function codeRequired, cannot be empty
TimeoutBetween 1 and 30 seconds
Duplicate namesCannot have two interactions with the same method name per agent