> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heysonara.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Remote Interactions (RPC)
> Run custom JavaScript functions in the user's browser during conversations.
## 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 case | What the code does |
| -------------------- | -------------------------------------------------------------- |
| **Geolocation** | Get the user's latitude/longitude for location-aware responses |
| **Form interaction** | Pre-fill or submit forms on the page |
| **UI updates** | Show/hide elements, display notifications, or update content |
| **Local storage** | Read or write user preferences |
| **Clipboard** | Copy information to the user's clipboard |
| **Page data** | Read 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.
Navigate to your agent and open the widget/export modal.
Click the **Remote Interactions** tab. You'll see a list of any existing interactions and an **Add Remote Interaction** button.
A form opens where you define your custom function.
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.
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:
| Field | Description |
| --------------- | --------------------------------------------- |
| **Name** | Parameter name (alphanumeric and underscores) |
| **Type** | `string`, `number`, `boolean`, or `object` |
| **Description** | What this parameter is for |
| **Required** | Whether 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
```javascript theme={null}
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
```javascript theme={null}
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
```javascript theme={null}
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
| Field | Rule |
| -------------------- | ----------------------------------------------------------------- |
| Method name | Max 64 chars, starts with letter, alphanumeric + underscores only |
| Function description | Min 10 characters, max 255 |
| Arguments | Each must have name, type, and description; names must be unique |
| Function code | Required, cannot be empty |
| Timeout | Between 1 and 30 seconds |
| Duplicate names | Cannot have two interactions with the same method name per agent |