@egain/ai-agent-sdk API Reference - v0.3.2 / HookContract

Interface: HookContract

Bidirectional contract between the SDK and a platform connector script.

Read-only getters return live state (not stale snapshots) because the implementation closes over the AiAgent instance.

Table of contents

Properties

• getTranscript
• getInitParams
• getQueryParams
• getAgentDetails
• getMsalAccessToken
• getAccessToken
• getDeploymentInfo
• getPlatformType
• getEnvironment
• getUserId
• getUserContext
• getConversationId
• getAuthScopes
• getTenantId
• getSelectedPortal
• getCallerInfo
• addToTranscript
• setCallerInfo
• setPlatformAuthenticated
• setPlatformToken
• setConversationId
• setUserContext
• setUserFilterTags
• subscribeToAgentWidgetActions
• onUserMessage
• onSourceClick
• onIntentConfirm

Properties

getTranscript

• getTranscript: () => CallTranscriptEntry[]

Returns the current call transcript entries (telephony conversation, not AI chat).

Type declaration

▸ (): CallTranscriptEntry[]

Returns

CallTranscriptEntry[]

Defined in

core/platform/HookContract.ts:49

---

getInitParams

• getInitParams: () => Record<string, string>

Returns a shallow copy of the initialization parameters.

Type declaration

▸ (): Record<string, string>

Returns

Record<string, string>

Defined in

core/platform/HookContract.ts:52

---

getQueryParams

• getQueryParams: () => Record<string, string>

Legacy alias for HookContract.getInitParams. Existing platform connectors (e.g. Genesys) may still call this name.

Type declaration

▸ (): Record<string, string>

Returns

Record<string, string>

Defined in

core/platform/HookContract.ts:58

---

getAgentDetails

• getAgentDetails: () => any

Returns the agent details object.

Type declaration

▸ (): any

Returns

any

Defined in

core/platform/HookContract.ts:61

---

getMsalAccessToken

• getMsalAccessToken: () => null | string

Returns the current MSAL/auth access token (cached; sync, cc-widget parity).

Type declaration

▸ (): null | string

Returns

null | string

Defined in

core/platform/HookContract.ts:64

---

getAccessToken

• getAccessToken: () => Promise<null | string>

Returns a fresh access token, refreshing if the current one is expired. Prefer this over getMsalAccessToken when making API calls that require a guaranteed valid token.

Type declaration

▸ (): Promise<null | string>

Returns

Promise<null | string>

Defined in

core/platform/HookContract.ts:70

---

getDeploymentInfo

• getDeploymentInfo: () => any

Returns the deployment info object.

Type declaration

▸ (): any

Returns

any

Defined in

core/platform/HookContract.ts:73

---

getPlatformType

• getPlatformType: () => null | string

Returns the platform type string (e.g. "genesys").

Type declaration

▸ (): null | string

Returns

null | string

Defined in

core/platform/HookContract.ts:76

---

getEnvironment

• getEnvironment: () => string

Returns the deployment environment from initParams.env (e.g. dev, qa, non-prod, prod, or legacy stage, eustage, euprod, devrf).

Type declaration

▸ (): string

Returns

string

Defined in

core/platform/HookContract.ts:82

---

getUserId

• getUserId: () => null | string

Returns the authenticated user/customer details id, or null if not yet fetched.

Type declaration

▸ (): null | string

Returns

null | string

Defined in

core/platform/HookContract.ts:85

---

getUserContext

• getUserContext: () => null | Record<string, unknown>

Returns the user context object.

Type declaration

▸ (): null | Record<string, unknown>

Returns

null | Record<string, unknown>

Defined in

core/platform/HookContract.ts:88

---

getConversationId

• getConversationId: () => null | string

Returns the conversation ID set by the connector.

Type declaration

▸ (): null | string

Returns

null | string

Defined in

core/platform/HookContract.ts:91

---

getAuthScopes

• getAuthScopes: () => string[]

Returns the OAuth scopes for the auth flow. Host-supplied scopes are used exactly as given: a host PKCE config's scopes (authenticated agents) first, else initParams.scopes (comma-separated). Otherwise the SDK-managed list: the connector's addCustomAuthScopes result if it ran, else the defaults for the agent's user type (including core.customermgr.read for customer), with the agent's extraScopes (from agent details) appended last, deduplicated.

Type declaration

▸ (): string[]

Returns

string[]

Defined in

core/platform/HookContract.ts:101

---

getTenantId

• getTenantId: () => null | string

Returns the tenant ID from deployment info.

Type declaration

▸ (): null | string

Returns

null | string

Defined in

core/platform/HookContract.ts:104

---

getSelectedPortal

• getSelectedPortal: () => null | Portal

Returns the currently selected portal, or null before selection.

Type declaration

▸ (): null | Portal

Returns

null | Portal

Defined in

core/platform/HookContract.ts:107

---

getCallerInfo

• getCallerInfo: () => null | CallerInfo

Returns the caller info set by the connector.

Type declaration

▸ (): null | CallerInfo

Returns

null | CallerInfo

Defined in

core/platform/HookContract.ts:110

---

addToTranscript

• addToTranscript: (entry: { sender: string ; content: string ; timestamp?: Date }) => void

Add an entry to the call transcript (telephony conversation, not AI chat).

Type declaration

▸ (entry): void

Parameters

Name	Type
entry	Object
entry.sender	string
entry.content	string
entry.timestamp?	Date

Returns

void

Defined in

core/platform/HookContract.ts:115

---

setCallerInfo

• setCallerInfo: (callerInfo: CallerInfo) => void

Set caller information (e.g. from CTI integration).

Type declaration

▸ (callerInfo): void

Parameters

Name	Type
callerInfo	CallerInfo

Returns

void

Defined in

core/platform/HookContract.ts:118

---

setPlatformAuthenticated

• setPlatformAuthenticated: (value: boolean) => void

Mark the platform as authenticated.

Type declaration

▸ (value): void

Parameters

Name	Type
value	boolean

Returns

void

Defined in

core/platform/HookContract.ts:121

---

setPlatformToken

• setPlatformToken: (token: string) => void

Store a secondary platform-specific token.

Type declaration

▸ (token): void

Parameters

Name	Type
token	string

Returns

void

Defined in

core/platform/HookContract.ts:124

---

setConversationId

• setConversationId: (id: string) => void

Set the conversation/interaction ID.

Type declaration

▸ (id): void

Parameters

Name	Type
id	string

Returns

void

Defined in

core/platform/HookContract.ts:127

---

setUserContext

• setUserContext: (userContext: Record<string, unknown>) => void

Append to the user context (merge, not overwrite).

Type declaration

▸ (userContext): void

Parameters

Name	Type
userContext	Record<string, unknown>

Returns

void

Defined in

core/platform/HookContract.ts:130

---

setUserFilterTags

• setUserFilterTags: (filterTags: Record<string, string[]>) => void

Set filter tags for portal content filtering. Merges user_filter_tags into userContext and stored agent context (does not replace either object).

Type declaration

▸ (filterTags): void

Parameters

Name	Type
filterTags	Record<string, string[]>

Returns

void

Defined in

core/platform/HookContract.ts:133

---

subscribeToAgentWidgetActions

• subscribeToAgentWidgetActions: (callback: (action: string, data: unknown) => void) => () => void

Subscribe to agent widget actions. Returns an unsubscribe function.

Type declaration

▸ (callback): () => void

Parameters

Name	Type
callback	(action: string, data: unknown) => void

Returns

fn

▸ (): void

Returns

void

Defined in

core/platform/HookContract.ts:138

---

onUserMessage

• onUserMessage: (message: string) => void

Forward a user message through the SDK's send pipeline.

Type declaration

▸ (message): void

Parameters

Name	Type
message	string

Returns

void

Defined in

core/platform/HookContract.ts:143

---

onSourceClick

• onSourceClick: (source: { [key: string]: unknown; id: string ; title: string ; url?: string }) => void

Handle a source click from the connector.

Type declaration

▸ (source): void

Parameters

Name	Type
source	Object
source.id	string
source.title	string
source.url?	string

Returns

void

Defined in

core/platform/HookContract.ts:146

---

onIntentConfirm

• onIntentConfirm: (intent: { [key: string]: unknown; id: string ; intent: string ; confidence: number }) => void

Handle an intent confirmation from the connector.

Type declaration

▸ (intent): void

Parameters

Name	Type
intent	Object
intent.id	string
intent.intent	string
intent.confidence	number

Returns

void

Defined in

core/platform/HookContract.ts:149