Integrations and API documentation

API keys and access

Create and revoke API keys on the Developer page of the Avarole app. A key is shown once, when you create it, so copy it then. The Integrations page generates the embed key for the agent you pick. Avarole checks that you own the agent before a key can act on it.

• Server key: sign supported API requests with X-API-Key: YOUR_KEY. Never put it in public browser code.
• Agent embed key: belongs to one agent and is meant for the widget and the React Native client, like a publishable key.
• Dashboard session: some endpoints accept the signed-in app session instead of an API key. Knowledge base endpoints only accept the dashboard session.

Authentication

Generate a key on the Developer page, then send it on every request as an X-API-Key header.

$ curl https://app.avarole.com/assistant/agents?tenant_code=default \
  -H "X-API-Key: sk_YourGeneratedKey..."

API requests are metered against your active pricing tier. Real-time usage per key is visible on the Developer page.

First API request: list your agents

The app’s API reference documents GET /assistant/agents. Pick your API base URL (shown on the Integrations page) and include your workspace’s tenant code.

$ curl https://app.avarole.com/assistant/agents?tenant_code=default \
  -H "X-API-Key: sk_YourGeneratedKey..."

# -> [{ "agent_id": "...", "avatar_filename": "...", "voice_id": "...",
#       "extra": { "allowed_languages": ["en","hi"], "default_language": "en", ... },
#       ... }, ...]

Every persona you own (avatar, voice, allowed languages, tools), plus everyone’s public Explore templates. It requires X-API-Key: personas have no public listing, only your own and the public templates.

What the Integrations settings support

Integrations are set for a saved agent. The app offers a Gmail inbox connection and a generic CRM connection, plus a separate email mailbox setup. Integration routes sit under /assistant/agents/{agent_id}/integrations.

• GET/assistant/agents/{agent_id}/integrationsList an agent’s integrations
• POST/assistant/agents/{agent_id}/integrations/email/connectStart the Gmail connection
• POST/assistant/agents/{agent_id}/integrations/crm/genericConnect a generic CRM
• DELETE/assistant/agents/{agent_id}/integrations/{integration_id}Disconnect an integration

Gmail inbox

Connect Gmail with Google OAuth. The call returns an auth_url to send the user to; the integration shows as connected once they approve. Disconnect it with the delete route.

$ curl -X POST https://app.avarole.com/assistant/agents/AGENT_ID/integrations/email/connect \
  -H "X-API-Key: sk_YourGeneratedKey..." \
  -H "Content-Type: application/json" \
  -d '{"provider": "google", "tenant_code": "default"}'

# -> { "auth_url": "https://accounts.google.com/..." }  send the user there to approve access

Generic CRM

Give the agent your CRM’s base URL and API key. Avarole stores the key on the server and leaves it out of every read, so listing integrations never returns it.

$ curl -X POST https://app.avarole.com/assistant/agents/AGENT_ID/integrations/crm/generic \
  -H "X-API-Key: sk_YourGeneratedKey..." \
  -H "Content-Type: application/json" \
  -d '{"base_url": "https://crm.example.com/api", "api_key": "YOUR_CRM_KEY", "tenant_code": "default"}'

Zoho CRM and Zoho Desk

The Avarole Executive workspace connector supports Zoho. CRM covers accounts, contacts, deals and notes; Desk covers tickets (search, read, create and update). It is set up in the desktop app, not through the website agent API above.

Website widget

The quickest way to get started. Drop the script tag below into your website (WordPress, Shopify, Webflow, or any plain HTML site) and a floating Avarole avatar button appears in the bottom-right corner.

Add the script tag

In the app’s Integrations page, choose an agent and generate its embed key. Paste this just before the closing </body> tag:

<!-- Avarole Avatar Widget -->
<script src="https://app.avarole.com/widget.js" data-api-key="YOUR_AGENT_EMBED_KEY" data-agent-id="YOUR_AGENT_ID"></script>

How it works

1. 1
   The script loads a floating Avarole avatar button onto your page.
2. 2
   When a visitor clicks it, the button smoothly expands into an interactive iframe.
3. 3
   The iframe securely loads your persona’s assistant UI, connected to your own configuration.
4. 4
   With Live Site Guide switched on, the agent can also take visitors around your site: it opens the right page, scrolls to the right section and highlights it.
5. 5
   Works out of the box on CMS platforms and custom SPA frameworks alike.

React Native SDK

A live avatar your users talk to, inside your iOS and Android app. It can also act inside your app, with the user’s approval, and shows you on the dashboard where people drop off. Drop in one component, or build your own screen on the same call. Web page tools (clicking, scrolling) do not apply in an app; the agent is told so.

Or install straight from the link, no download needed:

$ npm i https://avarole.com/sdk/avarole-react-native.tgz

1. Install

$ npm i https://avarole.com/sdk/avarole-react-native.tgz \
  @livekit/react-native @livekit/react-native-webrtc \
  livekit-client react-native-live-audio-stream
$ cd ios && pod install

Add the permissions (the microphone is how the user talks to the agent):

<!-- iOS: Info.plist -->
<key>NSMicrophoneUsageDescription</key>
<string>Assistant listens so you can talk to it.</string>

<!-- Android: AndroidManifest.xml -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.INTERNET" />

In tsconfig.json set "allowImportingTsExtensions": true (the SDK ships TypeScript source; Metro handles it).

2. Add the agent

// index.js - once, before anything renders
import { setupAvarole } from '@avarole/react-native';
setupAvarole();

import { AvaroleAgent } from '@avarole/react-native';

export default function App() {
  return (
    <>
      <YourApp />
      <AvaroleAgent agentId="YOUR_AGENT_ID" apiKey="YOUR_AGENT_EMBED_KEY" name="Assistant" />
    </>
  );
}

A floating button opens the panel: live avatar, captions, mute and end call. The key is the agent’s embed key and is safe to ship in an app, like the one on a website.

3. Let the agent act in your app

List what your app can do. The agent can call these and nothing else. Mark anything that changes something with confirm: true: the user must tap Allow before it runs.

const actions = useMemo(() => [
  {
    name: 'apply_coupon',
    description: 'Apply a coupon code to the cart',
    params: { type: 'object', properties: { code: { type: 'string' } }, required: ['code'] },
    handler: async ({ code }) => cart.applyCoupon(String(code)),
  },
  {
    name: 'cancel_order',
    description: 'Cancel the current order',
    confirm: true,
    handler: () => orders.cancelCurrent(),
  },
], []);

<AvaroleAgent agentId="YOUR_AGENT_ID" apiKey="YOUR_AGENT_EMBED_KEY" actions={actions}
  screen={{ name: 'Checkout', summary: 'Cart with 2 items', fields: [{ id: 'email', label: 'Email', filled: true }] }} />

• Arguments come from what the user said: validate them in the handler like any user input.
• screen tells the agent where the user is. Labels only, never what they typed.
• Return data, or { ok: false, status, reason } to report a problem. The agent reads it and tells the user.

4. See where users drop off

On by default. Results appear on the Dashboard under Where visitors drop off.

const { client } = useAvarole({ agentId: 'YOUR_AGENT_ID', apiKey: 'YOUR_AGENT_EMBED_KEY' });

client.insights.screen('Checkout');          // done for you when you pass `screen`
client.insights.step('kyc_started');          // a milestone: shows up in the funnel
client.insights.touch(x, y);                  // from your root view's onTouchStart: finds rage taps
const f = client.insights.form('signup', 6);  // f.started() on the first edit, f.submitted() when it goes through

It records screen names, the steps you name and where people struggle. It never reads or sends what a user types. Pass storage (AsyncStorage works) to count returning users once. Turn it off per app with insights={false} or per agent with the toggle on the Build page.

5. Build your own screen

import { useAvarole, AvatarView } from '@avarole/react-native';

const a = useAvarole({ agentId: 'YOUR_AGENT_ID', apiKey: 'YOUR_AGENT_EMBED_KEY' });
// a.status, a.captions, a.agentStatus, a.secondsLeft, a.error, a.muted
// a.start(), a.stop(), a.toggleMute()

<AvatarView client={a.client} style={{ height: 320 }} />

Good to know

• Calls last at most the agent’s session limit (Build page); users see a countdown.
• If the connection drops the SDK retries three times, then ends the call and says so.
• Web page tools (clicking, scrolling) do not apply in an app; the agent is told so.
• Test on a real iPhone and Android phone: the simulator has no real microphone echo behaviour.

Your own client (WebRTC / LiveKit)

For teams who want full control of the UI. Once you’ve fetched config with your API key, open a direct, low-latency connection for the AI voice and video pipeline and render the assistant natively in your own React, iOS or Android app.

import { LiveKitRoom, VideoTrack } from '@livekit/components-react';

export default function CustomAssistantUI({ token }) {
  return (
    <LiveKitRoom
      serverUrl="wss://livekit.avarole.com"
      token={token}
      connect={true}
      audio={true}
      video={false} // you're only sending audio to the AI
    >
      {}
      <AgentStreamRenderer />
    </LiveKitRoom>
  );
}

Agents and configuration

The reference covers listing, creating, deleting and configuring agents.

• GET/assistant/agentsList agents for the key owner
• POST/assistant/agentsCreate an agent
• GET/assistant/agents/{agent_id}/configRead an agent’s settings
• PUT/assistant/agents/{agent_id}/configUpdate an agent’s settings
• DELETE/assistant/agents/{agent_id}Delete an agent you own

Creating and editing personas is ownership-checked: your key can only touch personas you created. The extra settings object is replaced as a whole when you update it. Read it first, keep the existing values, then add a setting like guided_navigation.

Sessions and analytics APIs

Sessions and post-call summaries

Every call is automatically summarized after it ends: a short summary, action items and overall sentiment, generated in the background (never something a live call waits on). Pull it into your own dashboard or CRM:

$ curl https://app.avarole.com/assistant/sessions?limit=50 \
  -H "X-API-Key: sk_YourGeneratedKey..."

# -> [{
#      "session_id": "...", "agent_id": "...", "source": "widget",
#      "started_at": "...", "ended_at": "...", "duration_seconds": 142,
#      "summary": "Caller asked about loan eligibility and next steps.",
#      "sentiment": "positive",
#      "action_items": ["Send pre-approval checklist", "Follow up in 3 days"]
#    }, ...]

The same endpoint powers the dashboard’s own Sessions page. An Authorization: Bearer <token> header works identically to X-API-Key here, and on /assistant/sessions/stats?days=30 for aggregate usage (active and total sessions, total and average minutes).

Analytics

Per agent, and shaped by what the agent does: a sales agent is measured on qualified conversations, a support agent on deflection. The response tells you which metric blocks apply (panels_order), so you can render it without hard-coding the job.

$ curl "https://app.avarole.com/assistant/analytics/agent/AGENT_ID?months=6" \
  -H "X-API-Key: sk_YourGeneratedKey..."

# -> { "agent": { "job": "sales", "job_label": "Sales & Lead Qualification" },
#      "series": [ { "month": "2026-04", "calls": 12, "minutes": 48.3, ... } ],
#      "totals": { "calls": 61, "satisfaction": 78.4, "resolved_unaided": 91.8,
#                  "escalation_rate": 8.2, "cost": 1.42 },
#      "panels": { "qualification": {...}, "outcomes": {...} },
#      "recent": [ { "session_id": "...", "sentiment": "positive", ... } ] }

Percentages are null, never zero, when there is nothing to divide by: “0% resolved” and “no calls yet” mean opposite things.

• GET/assistant/sessionsList sessions
• GET/assistant/sessions/statsSession totals
• GET/assistant/analytics/agentsAnalytics for all agents
• GET/assistant/analytics/agent/{agent_id}Analytics for one agent
• GET/agent/usageAccount usage

Live Site Guide and Page Insights

Live Site Guide (guided navigation)

Switch on Live Site Guide for the agent on the Build page. The same script tag then lets the agent move visitors around your website while it talks: ask for “pricing” or “the refund policy” and it finds the section, opens the page, scrolls to it and highlights it. It also opens buttons, forms and popups. Nothing else to install, and agents without the switch are not affected.

1. 1
   It learns your site in the visitor’s browser: sitemap.xml, your menus and footer, and a short crawl (robots.txt respected). The live page is always what counts, so redesigns and new pages are picked up on their own.
2. 2
   While it acts, the widget shows each step (“Finding Pricing”, “Opening page”, “Highlighting”) with a tick once verified, where it is going, and a confirmation when it arrives. When more than one place fits, it shows two or three options to tap instead of guessing.
3. 3
   The conversation carries on across pages. When a full page load is needed, the call is picked up again on the next page and the agent finishes what it was doing.
4. 4
   It stays on your site, asks before anything that buys, pays, deletes, cancels or submits, and never reads or fills passwords, card numbers or one-time codes.

Optional attributes, none required:

<!-- Keep guided navigation off on one page -->
<script src="https://app.avarole.com/widget.js" data-agent-id="YOUR_AGENT_ID" data-guided-nav="false"></script>

<!-- Never read or touch this part of the page -->
<div data-agent-skip>...</div>

<!-- Always ask the visitor before clicking this -->
<button data-agent-risky>Cancel subscription</button>

<!-- A name the agent can use for a link or button -->
<a href="/demo" data-agent-label="Book a demo">Get started</a>

<!-- Use normal page loads (for sites whose scripts only run on a full load) -->
<html data-ava-hard-nav>

Turn it on through the API

Switch it on per agent from the Build page, or through the config API: it is the guided_navigation flag in the agent’s extra. Agents without it get no navigation tools.

# extra is replaced as a whole: read it, add the flag, send it back
EXTRA=$(curl -s "https://app.avarole.com/assistant/agents/AGENT_ID/config?tenant_code=default" \
  -H "X-API-Key: sk_YourGeneratedKey..." | jq '.extra + {"guided_navigation": true}')

jq -n --argjson extra "$EXTRA" '{tenant_code: "default", extra: $extra}' | \
$ curl -X PUT https://app.avarole.com/assistant/agents/AGENT_ID/config \
  -H "X-API-Key: sk_YourGeneratedKey..." \
  -H "Content-Type: application/json" -d @-

With the widget, nothing else is needed. In your own UI, load the navigation module on your page, tell the call which page the visitor is on, and run the agent’s page actions when they arrive on the call’s WebSocket as nav_action messages:

<script src="https://app.avarole.com/navigation/ava-nav.js"></script>
<script type="module">
  const AI = 'https://ai.avarole.com:8080';   // the call service
  const post = (path, body) => fetch(AI + path, { method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ session_id: SESSION_ID, ...body }) });

  await AvaNav.init({ agentId: 'AGENT_ID', origin: 'https://app.avarole.com' });
  // the page the visitor is on (send again after every page change)
  post('/nav/context', { page: AvaNav.pageContext() });

  ws.addEventListener('message', async (e) => {
    if (typeof e.data !== 'string') return;
    const msg = JSON.parse(e.data);
    if (msg.type !== 'nav_action') return;
    // nav_find, nav_go, nav_scroll_to, nav_click, nav_fill, ...
    const result = await AvaNav.runTool(msg.tool, msg.args);
    post('/nav/result', { id: msg.id, tool: msg.tool, result });
  });
</script>

The agent’s tools are nav_find (the best section for a request, with a confidence and close alternatives), nav_go (open the page, scroll to the section, highlight it and report what is on screen), and page actions (nav_scroll_to, nav_highlight, nav_click, nav_fill, nav_select, nav_toggle, nav_press_key, nav_choices, nav_tour, nav_snapshot, nav_clear). A result of status: "opening" means a full page load is under way; when your page has finished it, send POST /nav/event {"event": {"kind": "arrived", "ok": true, "heading": "...", "onScreen": "..."}} and the agent says one short line about what is now on screen.

The site index is built in the visitor’s browser. A copy is kept per agent and site at /assistant/agents/{agent_id}/site-index?origin=... so first visits can answer sooner; it is only a hint, the live page always wins, and navigation keeps working without it.

Page Insights: see where visitors drop off

Add page and funnel insights to any website that embeds your selected agent. The widget loads the small insights collector automatically; no analytics package or separate script is required. Generate the agent’s embed key, then copy this script into the website where that agent’s widget will appear, immediately before </body>.

<!-- Avarole widget + Page Insights for YOUR_AGENT_ID -->
<script
  src="https://app.avarole.com/widget.js"
  data-api-key="YOUR_AGENT_EMBED_KEY"
  data-agent-id="YOUR_AGENT_ID"
></script>

• The widget loads ava-insights.js automatically. Do not add a second insights script.
• Use the key generated for this agent’s website widget. It is present in the browser snippet, so do not put a personal server-side API key there.
• The same snippet works on plain HTML sites and common site builders, and tracks client-side route changes in single-page apps.
• For another agent, select it in the app and install that agent’s updated snippet on the site where it is embedded.

Add the steps that define your funnel

Name the milestones you want to measure with data-ava-step. By default, a step is recorded when at least half of its element becomes visible. Set data-ava-step-on="click" to record it only when the visitor clicks that element.

<!-- Counts when the visitor sees this milestone -->
<section data-ava-step="signup_form_seen">
  <h2>Create your account</h2>
</section>

<!-- Counts when the visitor clicks this button -->
<button data-ava-step="signup_started" data-ava-step-on="click">
  Start sign-up
</button>

For milestones that happen after application logic succeeds, call the JavaScript API so completion is recorded only after your own flow confirms it:

function onPaymentComplete() {
  if (window.AvaInsights) {
    window.AvaInsights.step('payment_completed');
  }
}

Step names may use letters, numbers, spaces, underscores, colons, periods, slashes and hyphens (up to 60 characters). Each named step is counted once per page load, so use distinct names for separate funnel milestones.

What Page Insights records

• Page views: the page path, such as /pricing. Query strings and URL fragments are removed.
• Funnel steps: the milestone names you add with data-ava-step or AvaInsights.step().
• Visitor behavior: rage clicks, clicks that appear to do nothing, time stalled in an active form, forms left before submission, and quick back navigation.
• Agent activity: widget open and close, call start and end, and page actions with their success status.

The collector does not read field values or record what visitors type. It uses a random browser visitor ID and a session ID to count unique visitors and visits. Do Not Track prevents collection; an ad blocker or site content-security policy can also block the script or event request.

Control when collection is enabled

Insights are enabled by default for the widget. The agent owner can turn off Visitor insights in that agent’s Build settings. You can also opt out a whole website or a single page:

<!-- Disable insights on this website -->
<script src="https://app.avarole.com/widget.js"
  data-api-key="YOUR_AGENT_EMBED_KEY"
  data-agent-id="YOUR_AGENT_ID"
  data-insights="false"></script>

<!-- Or disable only on a specific page (keep the shared widget snippet there) -->
<script>window.AVA_INSIGHTS_OPTOUT = true;</script>

Set window.AVA_INSIGHTS_OPTOUT = true before the widget script to disable collection on that page. Do not set it when the widget should collect insights.

Verify the integration and troubleshoot

1. 1
   Publish the page with the selected agent’s widget snippet and make sure the agent’s Visitor insights setting is on.
2. 2
   Open the site in a browser with Do Not Track off, then navigate between pages and trigger one named funnel step.
3. 3
   Allow a few seconds for the widget to batch events. Page exit events are flushed when the page is hidden or closed.
4. 4
   Open Page Insights from the app navigation, select the same agent, and check the 7D, 30D or 90D range.

If no events appear:

• Confirm the snippet’s data-agent-id matches the agent selected on Page Insights.
• Confirm the script loads from https://app.avarole.com/widget.js and the browser network panel shows ava-insights.js and requests to /assistant/analytics/events.
• Check that data-insights="false", AVA_INSIGHTS_OPTOUT, Do Not Track, a content-security policy, or an ad blocker is not disabling collection.
• For a click step, verify the element has data-ava-step-on="click". For an automatically seen step, make sure its element enters the viewport after the page loads.

• POST/assistant/analytics/eventsInsights collector
• GET/assistant/analytics/site/{agent_id}?days=30Dashboard summary
• GET/assistant/agents/{agent_id}/site-index?origin=Stored site index (a speed hint)

Knowledge base endpoints

These take a signed-in dashboard session rather than an API key. Three ways in: upload a file, point at a website, or mail things to the agent. All three land in the same place: what the agent answers from. Importing a website also rewrites the persona around what the site says, unless you pass tailor_persona: false.

# Upload a document
# Knowledge-base routes take a dashboard session, not an API key.
$ curl -X POST "https://app.avarole.com/assistant/knowledge-base/upload?tenant_code=default&agent_id=AGENT_ID" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -F "file=@price-list.pdf"

# Learn a whole website
$ curl -X POST https://app.avarole.com/assistant/knowledge-base/import-url \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"yourbusiness.com","agent_id":"AGENT_ID","tenant_code":"default"}'

# What it knows, and correcting it
$ curl "https://app.avarole.com/assistant/knowledge-base?tenant_code=default&agent_id=AGENT_ID" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

$ curl -X PUT https://app.avarole.com/assistant/knowledge-base/DOC_ID/text \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Corrected text.","agent_id":"AGENT_ID","tenant_code":"default"}'

Editing re-chunks and re-embeds the document under the same id, so it keeps its identity and the old text stops being answerable immediately.

• GET/assistant/knowledge-baseList documents
• POST/assistant/knowledge-base/import-urlImport a website
• POST/assistant/knowledge-base/uploadUpload a document
• PUT/assistant/knowledge-base/{doc_id}/textEdit document text
• DELETE/assistant/knowledge-base/{doc_id}Delete a document

Email

Mail arrives through Amazon SES, or through an IMAP and SMTP mailbox you set up: host, port, username, folder and TLS, the sender name and address, reply instructions and whether automatic replies are allowed. A mailbox has a mode, and it decides everything else: support turns every message into a ticket with a quotable reference and acknowledges the sender; ingestion reads whatever arrives into the agent’s knowledge and never replies to anyone. Passwords are stored encrypted and never sent back.

# 1. Claim the domain and get the DNS records to add
$ curl "https://app.avarole.com/assistant/agents/AGENT_ID/email/domain?domain=yourbusiness.com" \
  -H "X-API-Key: sk_YourGeneratedKey..."

# -> { "records": [ { "type": "TXT", "host": "_amazonses...", ... },
#                   { "type": "MX",  "host": "yourbusiness.com", ... },
#                   { "type": "CNAME", ... } ],
#      "status": { "verified": false, "dkim": false, "receiving": false } }

# 2. Configure the mailbox
$ curl -X PUT https://app.avarole.com/assistant/agents/AGENT_ID/email \
  -H "X-API-Key: sk_YourGeneratedKey..." \
  -H "Content-Type: application/json" \
  -d '{"ses_domain":"yourbusiness.com",
       "from_address":"support@yourbusiness.com",
       "mailbox_mode":"support",
       "auto_reply":false,
       "send_acknowledgement":true}'

# 3. Anything still waiting on DNS, across every agent
$ curl https://app.avarole.com/email/pending-domains \
  -H "X-API-Key: sk_YourGeneratedKey..."

A domain belongs to the first account that claims it, and no other account can configure it afterwards: SES verifies identities per AWS account, so without that rule a verified domain would be usable by anyone who named it. The address must be on the domain you own. Re-calling /assistant/agents/{id}/email/domain is how you poll: it re-reads SES and finishes the setup the moment the records go live.

• GET/assistant/agents/{agent_id}/emailRead mailbox settings
• PUT/assistant/agents/{agent_id}/emailSave mailbox settings
• POST/assistant/agents/{agent_id}/email/testTest the mailbox
• POST/assistant/agents/{agent_id}/email/pollCheck for new mail
• DELETE/assistant/agents/{agent_id}/emailDisconnect the mailbox
• GET/email/threadsReview email threads

Endpoint groups in the app reference

The API & SDK tab in the Avarole app is the live source for every endpoint, parameter and access rule. This is the same list, grouped as in the app. Access varies by endpoint: the reference marks each one as API key or session, dashboard session only, or public.