arcy.js

Embed an ARCY AI agent in any web app. The agent talks to your users, learns what they are trying to do, and acts on their behalf.

No framework required. arcy.js is plain JavaScript that runs on any page, and it ships its own TypeScript types.

BETA. The API below is frozen, but the product around it is still moving. Report anything broken at arcyai.com.

Install

npm install arcy.js

Also works with pnpm add arcy.js, bun add arcy.js, and yarn add arcy.js.

There is no separate types package. Types are bundled, so @types/arcy.js does not exist and you do not need it.

Use it

Two calls, once, where your app starts. init() connects your environment. identify() says who the current user is.

import arcy from "arcy.js"

arcy.init("YOUR_ENVIRONMENT_TOKEN")

arcy.identify(user.id, {
  user_first_name: user.firstName,
  user_email: user.email,
  user_signed_up_at: user.createdAt,
})

Your environment token, with the real value already filled in, is in the dashboard under Settings > Installation.

arcy.js runs in the browser only. In Next.js, React Router, Nuxt, or any framework that renders on the server, keep both calls inside a client component or a mount effect.

Without a bundler

Paste two script tags before </body>. Nothing to install.

<script src="https://cdn.arcyai.com/arcy.loader.js"></script>
<script>
  arcy.init("YOUR_ENVIRONMENT_TOKEN")
  arcy.identify("USER_ID", {
    user_first_name: "USER_FIRST_NAME",
    user_email: "USER_EMAIL",
  })
</script>

API

| Method | What it does | | --- | --- | | init(token, options?) | Starts ARCY with your environment token. | | identify(userId, attributes?, options?) | Names the signed-in user and sends their attributes. | | identifyAnonymous(attributes?) | Same, for a user who has not signed in. | | updateUser(attributes?) | Sends new attribute values for the current user. | | reset() | Clears the session. Call it on sign-out. | | open() / close() | Opens or closes the chat panel. | | on(event, handler) | Listens for "ready", "open", or "close". Returns an unsubscribe function. | | VERSION | The version of arcy.js on the page. |

Nothing here throws, and no promise it returns rejects. A failure resolves and reports through a console warning, so ARCY can never take your page down.

Attribute values may be a string, number, boolean, string array, or null. Passing null clears the key.

Options for init()

| Option | What it does | | --- | --- | | telemetry | Consent signal for behavioral telemetry. Wire this to your cookie banner. | | locale | The reply language of the agent, as a two-letter code ("en", "tr"). | | contentLocale | The user's content locale, region qualified ("en-US", "tr-TR"). | | defaultOpen | Opens the panel on arrival. |

Everything else ARCY does is configured in the dashboard, not in code. There is no config file, no build step, and nothing to redeploy when you change a setting.

Identity verification

Pass a userHash to prove the user is who your app says they are:

arcy.identify(user.id, attributes, { userHash })

userHash is HMAC-SHA256(environment secret, userId), computed on your server. Never compute it in the browser.

Docs

Full setup guides per framework, auth provider snippets, and troubleshooting: docs.arcyai.com

License

MIT