Configuration

arcy.js has one imperative entry point, arcy.init(token), identical in every framework and in both distribution channels (npm and the HTML snippet). There is no provider component and no config file. What the agent does, what it's trained on, what it says, and which flows it runs are all configured in the dashboard, not in code. Code sets only the handful of options below that have to be known before the dashboard can be reached: telemetry consent, locale, and whether the panel opens on load.

What Chat and Flows do

The agent has two capabilities, both delivered through the same chat surface:

There is no separate mode to pick and no overlay painted on your page: the widget is a chat bar and a chat surface, nothing else. See Flows for how an operator authors one.

init(token, options?)

init(token: string, options?: ArcyOptions): Promise<void>

Mounts ARCY for one environment. token is that environment's public Token (arcy_pk_...), copied from Settings > Installation. Calling init() a second time on the same page is ignored with a console warning; calling it with no token does the same.

options accepts exactly four keys. Passing anything else logs a console warning and is ignored, on purpose: a behavioral option belongs in the dashboard, not in code.

interface ArcyOptions {
  telemetry?: boolean
  locale?: string
  defaultOpen?: boolean
  contentLocale?: string
}

• telemetry: your own consent signal for behavioral telemetry, if your product gates that behind a cookie banner. A banner's accept/decline logic is code you own; arcy.js does not render one itself.
• locale: a two-letter code ("en" or "tr") setting the language the agent replies in by default. Separate from contentLocale below: this is the reply-language default, not which translated dashboard content is served.
• defaultOpen: true opens the chat panel immediately on load, false forces it closed. Leaving it unset falls back to the operator's dashboard setting for first-ever visits only; it never reopens automatically on a returning visit.
• contentLocale: a region-qualified code ("en-US" or "tr-TR") setting which locale's translated content is served, for when you already know the visitor's region before they've signed in. See Localization for how this interacts with the locale_code attribute.

import arcy from "arcy.js"

arcy.init("arcy_pk_...", { locale: "tr", contentLocale: "tr-TR" })

init() never throws. A missing or invalid token, a malformed options object, or a network failure during bootstrap all degrade to a console warning; your page keeps running either way.

identify(userId, attributes?, options?)

identify(userId: string, attributes?: Attributes, options?: IdentifyOptions): Promise<void>

Tells ARCY who the current user is and what you know about them. attributes is a flat object; each key must be declared under Agent > Attributes before ARCY will store it, and each value must be a string, number, boolean, null, or an array of strings. Anything else is dropped with a console warning naming the key.

arcy.identify("user_123", {
  name: "Jordan Lee",
  email: "jordan@example.com",
  plan_value: 249,
  plan_cycle: "monthly",
})

options.userHash carries the identity-verification signature computed on your own server. See Enforce identity verification for the recipe.

identifyAnonymous(attributes?)

identifyAnonymous(attributes?: Attributes): Promise<void>

For pages with no signed-in user. Mints (or reuses) an id stored in localStorage, so a returning anonymous visitor is recognized across sessions. Anonymous usage draws on the same credit meter as identified usage; see the anonymous caps under Settings > Limits.

updateUser(attributes?)

updateUser(attributes?: Attributes): Promise<void>

Merges new attributes into the current identity without changing who it is. Inherits the identity-verification state of the identify() call that came before it, so it takes no userHash of its own. Calling it before any identify() or identifyAnonymous() call is a no-op: there's no profile yet to update, so nothing is sent.

reset()

reset(): void

Clears the current identity and the anonymous id. Wire this to your logout action. It's the one moment there's real evidence the human at the keyboard may be changing, so ARCY starts a fresh anonymous id rather than risk merging two people's activity into one funnel.

on(event, handler)

on(event: "ready" | "open" | "close", handler: () => void): () => void

Subscribes to a widget lifecycle event and returns an unsubscribe function. ready fires once init() has fully configured the session; open/close fire when the chat panel's visibility changes. on() is callable before init().

open() / close()

open(): void
close(): void

Opens or closes the chat panel programmatically. Both are local, synchronous, and never throw.

Everything else lives in the dashboard

There is no code-level option for the agent's persona, which Sources it draws on, which flows it can run, credit limits, or locale translations. All of it is under the app's dashboard sections: Agent for Flows, Train, Persona, Origins, Attributes, and Localization; Settings for Installation, Environments, Identity verification, and Limits.

See also

• Sources: attaching documents and links so Chat can answer from them
• Quickstart: the full install walkthrough