Aimdoc AI SDKs

Aimdoc provides official SDKs for JavaScript/TypeScript and React so you can control chat behavior directly from your app.

Use these SDKs to:

• Identify signed-in users when your embedded agent is running in App Mode (Activate)
• Associate users with application accounts or tenants
• Open the chat programmatically
• Send messages into the conversation flow
• Attach host application context to the next user message

Official libraries

JavaScript / TypeScript SDK

Use @aimdoc/sdk to securely identify users and accounts, open chat, and send messages programmatically.

View package

React SDK

Use @aimdoc/sdk-react with AimdocProvider and useAimdoc for React applications.

View package

Install

Install the package that fits your stack:

# JavaScript / TypeScript
npm install @aimdoc/sdk

# React
npm install @aimdoc/sdk-react

Upgrade to the latest package for TypeScript support for structured account identity. The message protocol is additive, so older JavaScript runtimes can forward the new field, but older TypeScript definitions do not accept the account object.

JavaScript SDK

The JavaScript SDK exports a singleton aimdoc client:

import { aimdoc } from '@aimdoc/sdk'

aimdoc.identify({
  external_id: 'user_123',
  email: 'jane@company.com',
  first_name: 'Jane',
  last_name: 'Doe',
  company: 'Acme Inc', // Legacy contact-level company field
  account: {
    external_id: 'account_456',
    name: 'Acme Inc',
    domain: 'acme.com',
  },
  attributes: {
    plan: 'pro',
  },
  user_hash: accountAwareHashFromYourServer,
})

aimdoc.openChat({ agentId: 'your-agent-id' })
aimdoc.sendMessage('Can you show enterprise pricing?', { agentId: 'your-agent-id' })
aimdoc.setNextMessageContext(
  `The user is viewing the onboarding checklist.
They have already connected Salesforce and imported teammates.
They are currently on the "Invite teammates" step, with the invite modal open.
The last invite attempt failed because the email domain did not match their company domain.`,
  { agentId: 'your-agent-id' },
)

Available methods

• identify(user) — attach durable user, account, and profile identity for App Mode sessions.
• openChat(options?) — open the chat launcher/widget.
• sendMessage(message, options?) — send a message as the current visitor/user.
• setNextMessageContext(context, options?) — add host application context to the next user message only.

agentId is optional in openChat, sendMessage, and setNextMessageContext. Provide it when your page can target multiple agents.

Use identify for durable user and account identity. Use setNextMessageContext for transient app state that should help the agent answer the next message, such as where the user is in onboarding, what modal is open, which validation error just appeared, or what workflow step they are trying to complete. The context is added to the agent's prompt for one turn only, is not stored as a visible chat message, and is cleared after the next message payload is sent.

The first argument can be a string or any JSON-serializable value. Objects and arrays are serialized as formatted JSON before they are added to the agent prompt.

Identify users and accounts

The user external_id and email are required. To associate the user with one of your application accounts or tenants, include:

account: {
  external_id: 'account_456', // Required: your stable account or tenant ID
  name: 'Acme Inc',           // Optional
  domain: 'acme.com',         // Optional
}

account.name is the account name. The legacy top-level company field continues to update the contact's company field, but it does not name the account.

If account.domain is omitted, Aimdoc uses the contact's work-email domain when available. An external ID is enough to identify an account for users with personal email addresses. A non-empty supplied name updates the account; omitted or empty values do not clear existing data.

Aimdoc checks an explicitly supplied domain and external ID together. If they already belong to different account records, the account update is rejected rather than silently overwriting or merging records. A domain inferred from the user's work email is only a hint: if it conflicts with the external ID, Aimdoc keeps the external-ID association and discards the inferred domain.

Identity verification

Secure identify calls with a user_hash generated by your server. Never expose the signing secret in browser code.

Every identify call containing an account object requires an account-aware v2 signature. User-only calls require a signature after you enable organization-wide enforcement, and invalid signatures are always rejected.

See Identity Verification for signing-secret setup, the canonical user-only and account payloads, implementation examples, enforcement, and rotation.

React SDK

The React SDK gives you AimdocProvider and useAimdoc.

'use client'

import { AimdocProvider } from '@aimdoc/sdk-react'

export default function AppRoot() {
  return (
    <AimdocProvider agentId="your-agent-id">
      <App />
    </AimdocProvider>
  )
}

Inside child components, call the SDK through the hook:

'use client'

import { useAimdoc } from '@aimdoc/sdk-react'

export function OpenChatButton() {
  const { identify, openChat } = useAimdoc()

  const onClick = () => {
    identify({
      external_id: 'user_123',
      email: 'jane@company.com',
      account: {
        external_id: 'account_456',
        name: 'Acme Inc',
        domain: 'acme.com',
      },
      user_hash: accountAwareHashFromYourServer,
    })
    openChat()
  }

  return <button onClick={onClick}>Chat with sales</button>
}

AimdocProvider props

• agentId (required) — your Aimdoc agent ID.
• scriptUrl (optional) — custom script URL. Defaults to https://app.aimdoc.ai/embedded.bundle.js.

Next steps

• Deploy for script/widget setup details
• Identity Verification for signing and enforcement
• App Mode for in-product agent guidance
• API & Webhooks Overview for backend integrations
• Webhooks for event delivery patterns
• API Reference (Redoc)