Installation
Set the VOKER_API_KEY environment variable to your API key before using the SDK. You can find your key in the Voker dashboard under settings.
Quick start
Replace your existing LLM provider import with the Voker-wrapped version. No other code changes are required.
import { OpenAI } from 'openai';
import { OpenAI } from '@voker/voker/ai/provider-openai';
const client = new OpenAI();
await client.chat.completions.create({
vokerAgent: 'customer-support-agent', // required
vokerSession: 'user-session-1', // required
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello, world!' }],
});
vokerAgent parameter identifies which agent handled the request. The vokerSession parameter ties the call to a specific session. Both are required for Voker to associate the event with the correct agent and session in your dashboard.
For provider-specific setup guides, see OpenAI, Anthropic, Gemini, and AI SDK.
Typescript SDK Reference
VokerClient
The Voker Client provides a way to create an update Agents, Agent Versions, People and Events programmatically.
Requests are made in the background as to not add latency to your application. This is used by the SDKs but can also be used directly if you want more control over when requests are sent. Instantiate once and reuse throughout your application.
Class VokerClient
| Field | Type | Description |
|---|
events | VokerClient_Events | Access events related endpoints. |
people | VokerClient_People | Access people related endpoints. |
agents | VokerClient_Agents | Access agents related endpoints. |
agentVersions | VokerClient_AgentVersions | Access agent versions related endpoints. |
start() - Initializes the background worker. Call this once before making any other requests.
close() - Waits for all pending background requests to complete and shuts down the worker. Call this before your process exits to avoid dropped events.
Class VokerClient_Agents
create(payload: CreateAgentPayload) - Creates an agent with the given name. If the agent already exists, the call is a no-op.
Class VokerClient_AgentVersions
create(agentName: string, payload: CreateAgentVersionPayload) - Creates a new version under the specified agent.
Class VokerClient_Events
create(payload: ClientCreateEventPayload) - Enqueues an event for background delivery. vokerSession and eventName are required; agent, version, and person association fields are optional.
Class VokerClient_People
create(payload: CreatePersonPayload) - Creates a person record. If the person already exists, the call is a no-op.
update(personId: string, payload: UpdatePersonPayload) - Merges the provided properties into an existing person record.
ApiClient
The API Client provides a way to make requests to the Voker API directly. This is used under the hood by the Voker Client, but can also be used directly if you want more control over how requests are made.
Fetching Agents, Agent Versions, and People is a common use cases for using the API Client directly.
Class ApiClient
| Field | Type | Description |
|---|
events | ApiClient_Events | Create events directly via the API. |
people | ApiClient_People | Get, create, and update person records. |
fingerprints | ApiClient_Fingerprints | Create anonymous fingerprint identifiers. |
agents | ApiClient_Agents | Create and fetch agent records. |
agentVersions | ApiClient_AgentVersions | Create and fetch agent version records. |
ApiClient_Agents
create(payload: CreateAgentPayload) -> Agent - Creates and returns a new agent.
get(agentName: string) -> Agent - Returns the agent with the given name.
Class ApiClient_AgentVersions
create(agentName: string, payload: CreateAgentVersionPayload) -> AgentVersion - Creates and returns a new version under the given agent.
get(agentName: string, agentVersionName: string) -> AgentVersion - Returns the specified agent version.
Class ApiClient_Events
create(payload: CreateEventPayload) - Creates an event directly via the API.
Class ApiClient_Fingerprints
create() -> Fingerprint - Generates and returns a new anonymous fingerprint identifier.
Class ApiClient_People
get(personId: string) -> Person - Returns the person with the given ID.
create(payload: CreatePersonPayload) -> Person - Creates and returns a new person.
update(personId: string, payload: UpdatePersonPayload) -> Person - Merges properties into an existing person and returns the updated record.
Types
These TypeScript types are used as parameters and return values throughout the SDK.
CreateAgentPayload
| Field | Type | Description |
|---|
agentName | string | Unique identifier name for the agent. |
description | string | null | undefined | Optional human-readable description. |
CreateAgentVersionPayload
| Field | Type | Description |
|---|
agentVersionName | string | Unique name for the version within the agent. |
description | string | null | undefined | Optional description. |
ClientCreateEventPayload
| Field | Type | Required | Description |
|---|
vokerSession | string | Yes | Session identifier to associate this event with. |
eventName | string | Yes | Name of the event being recorded. |
properties | Record<string, any> | Yes | Arbitrary key-value metadata for the event. |
vokerAgent | string | undefined | No | Agent name to associate this event with. |
vokerAgentVersion | string | undefined | No | Agent version name to associate this event with. |
vokerPerson | string | undefined | No | Person ID to associate this event with. |
CreatePersonPayload
| Field | Type | Description |
|---|
personId | string | Your application’s identifier for this person. |
properties | Record<string, any> | undefined | Optional key-value metadata. |
UpdatePersonPayload
| Field | Type | Description |
|---|
properties | Record<string, any> | Properties to merge into the person record. |
Agent
Represents an AI agent registered in Voker.
| Field | Type | Description |
|---|
agentName | string | Unique identifier name for the agent. |
description | string | null | Optional human-readable description. |
agentNumber | number | Auto-assigned numeric identifier. |
createdAt | Date | Timestamp when the agent was created. |
deprecatedAt | Date | null | Timestamp when the agent was deprecated, if ever. |
AgentVersion
Represents a specific version of an agent.
| Field | Type | Description |
|---|
agentVersionName | string | Unique name for this version within the agent. |
description | string | null | Optional description. |
agentVersionNumber | number | Auto-assigned numeric identifier. |
createdAt | Date | Timestamp when the version was created. |
deprecatedAt | Date | null | Timestamp when the version was deprecated, if ever. |
Fingerprint
An anonymous identifier used to track activity without a known person ID.
| Field | Type | Description |
|---|
fingerprintId | string | Unique fingerprint value. |
Person
Represents a user or entity tracked in Voker.
| Field | Type | Description |
|---|
personId | string | Your application’s identifier for this person. |
properties | Record<string, any> | null | Arbitrary key-value metadata. |
createdAt | Date | Timestamp when the person was first created. |
