Chat widget — install and customize

What you get

The chat widget is a floating launcher in the corner of your site that opens a panel with up to four tabs:

• Home — greeting, recent updates row, quick-reply options.
• Messages — AI-powered conversation backed by your help center.
• Help — browse your help articles by flow.
• Changelog — recent releases from your project.

Conversation history is persisted in the visitor's browser by default so they can resume a thread on return.

Install

Drop a script tag in your page (anywhere — in the head or just before the closing body tag works fine) pointing at https://cdn.appgram.dev/chat.min.js. The only required attribute is data-project-id. Recommended attributes:

src="https://cdn.appgram.dev/chat.min.js"
data-project-id="YOUR_PROJECT_ID"
data-org-slug="YOUR_ORG_SLUG"
data-project-slug="YOUR_PROJECT_SLUG"

The org slug and project slug are optional but unlock the Help and Changelog tabs — without them, those tabs show a "not configured" hint.

Common customization

Every option below can be set as a data attribute on the script tag or as a key on window.appgramChatSettings. Defaults are listed in parentheses.

• data-project-id / projectId — Required. Your project's UUID.
• data-org-slug / orgSlug — needed for the Help and Changelog tabs.
• data-project-slug / projectSlug — needed for the Help and Changelog tabs.
• data-agent-name / agentName (default "Help") — displayed name in greetings and the avatar fallback.
• data-greeting / greeting (default "Hello") — first line of the home greeting.
• data-subtitle / subtitle (default "How can I help you today?") — second line of the home greeting.
• data-logo-url / logoUrl — avatar image URL. Falls back to the initial of agentName.
• data-accent-color / accentColor (default brand blue) — drives launcher, accents, user bubble.
• data-theme / theme (default "auto") — light, dark, or auto.
• data-position / position (default "bottom-right") — also bottom-left, top-right, top-left.
• data-font-size / fontSize (default "base") — sm, base, lg, or any CSS size.
• data-default-tab / defaultTab (default "home") — which tab is open when the panel first appears.
• data-article-base-url / articleBaseUrl — when set, help article clicks navigate to {base}/{slug}.
• data-support-url / supportUrl — the "Contact Support" CTA navigates here.
• data-ephemeral / ephemeral (default false) — true disables localStorage thread persistence.
• data-auto-fetch-style / autoFetchStyle (default true) — pulls the active widget style from your dashboard.
• data-options / options — pipe-separated quick replies: "Get a demo|Pricing".
• data-team-avatars / teamAvatars — comma-separated avatar URLs for the Home hero.

Typewriter reply animation

Agent replies stream into the bubble with a blinking caret — on by default. Tune or disable via:

• data-typewriter / typewriter (default true) — set to "false" to render replies instantly.
• data-typewriter-chunk-size / typewriterChunkSize (default 2) — characters revealed per tick. Higher = faster.
• data-typewriter-interval-ms / typewriterIntervalMs (default 24) — milliseconds between ticks. Lower = faster.

While the cursor runs, sources and the "Need more help?" support card are deferred — they appear once typing lands, so nothing pops in over half-typed text.

Handling clicks programmatically

When a visitor taps a help article, a release card, a source citation, or the "Contact Support" CTA, the widget either navigates the host page (if you set data-article-base-url / data-support-url) or stays inert and emits an event. Subscribe with AppGramChat.on(event, callback):

AppGramChat.on('article:click', ({ slug, article }) => {
  router.push(`/help/${slug}`)
})

AppGramChat.on('release:click', (release) => {
  router.push(`/changelog/${release.slug}`)
})

AppGramChat.on('support:click', () => {
  openSupportModal()
})

Other emitted events: open, close, tab:change, message:sent, message:received, source:click, conversation:start, conversation:reset. on() returns an unsubscribe function.

Note: if you set data-article-base-url the auto-navigation fires and your listener runs, but window.location.href reloads the page so your listener can't override it. Use one or the other — host-page nav for static / multi-page sites, listeners for SPAs.

Programmatic API

• AppGramChat.open() — open the panel.
• AppGramChat.close() — close the panel.
• AppGramChat.toggle() — toggle open/closed.
• AppGramChat.on(event, cb) — subscribe to an event. Returns an unsubscribe function.
• AppGramChat.off(event, cb) — remove a listener.
• AppGramChat.reset() — drop the current conversation and start a fresh one.
• AppGramChat.destroy() — tear down the launcher, panel, and listeners.

Live styling from your dashboard

Customizations made in the AppGram dashboard (theme, colors, fonts, background, hero copy) are fetched at init time and applied on top of your inline settings. Inline settings always win — useful for staged rollouts or A/B tests where you don't want the dashboard to live-override the embed. To opt out entirely, set data-auto-fetch-style="false".