HR Self-Service Widget

Embed a Studio-powered HR assistant into an employee portal for policy Q&A, leave requests, onboarding help, and document routing.

Client SDK

Overview

A modern HR assistant is usually not a standalone chatbot anymore. Teams want a small widget inside the employee portal that understands company policies, opens HR workflows, and works with the employee context already present in the app.

This pattern fits Cognipeer Client SDK well: Studio owns the peer and conversation behavior, while your product keeps the UI shell, user session, and business actions.

Architecture

Client SDK connects your portal to a Studio peer by using a PAT and a hook ID. The widget can read the current peer, channel, and user context, then start conversations without exposing Studio internals to employees.

Use client tools when the peer needs to trigger real actions such as opening a leave request modal, checking leave balance, or creating an HR helpdesk case in your product.

1. Connect The Portal Widget To Studio

Initialize the SDK once inside your portal shell and inspect the peer attached to the widget channel.

import { CognipeerClient } from '@cognipeer/sdk';

const client = new CognipeerClient({
  token: process.env.NEXT_PUBLIC_COGNIPEER_PAT!,
  hookId: process.env.NEXT_PUBLIC_HR_WIDGET_HOOK_ID!,
  apiUrl: 'https://api.cognipeer.com/v1',
});

const [peer, user, channel] = await Promise.all([
  client.peers.get(),
  client.users.get(),
  client.channels.get(),
]);

console.log(peer.name, user.displayName, channel.hookId);

2. Expose HR Actions As Client Tools

Let the peer answer questions and also trigger native HR actions in your portal when needed.

const hrTools = [
  {
    type: 'function',
    function: {
      name: 'getLeaveBalance',
      description: 'Return remaining annual leave balance for the signed-in employee',
      parameters: {
        type: 'object',
        properties: {},
      },
    },
    implementation: async () => {
      const response = await fetch('/api/hr/leave-balance');
      return JSON.stringify(await response.json());
    },
  },
  {
    type: 'function',
    function: {
      name: 'openLeaveRequestForm',
      description: 'Open the leave request flow inside the employee portal',
      parameters: {
        type: 'object',
        properties: {
          startDate: { type: 'string' },
          endDate: { type: 'string' },
        },
        required: ['startDate', 'endDate'],
      },
    },
    implementation: async ({ startDate, endDate }) => {
      openLeaveModal({ startDate, endDate });
      return 'Leave request modal opened';
    },
  },
];

3. Start The HR Conversation

The employee sees a compact widget, but the peer can still reason over the request and choose when to call your client tools.

const response = await client.conversations.create({
  messages: [
    {
      role: 'user',
      content: 'How many leave days do I have left, and can you open a vacation request for next Thursday and Friday?',
    },
  ],
  clientTools: hrTools,
});

console.log(response.content);
console.log(response.conversationId);

Result

You get an HR widget that:

- Answers policy and onboarding questions in context - Uses existing employee identity from your portal - Triggers leave and HR workflows through client tools - Keeps Studio logic behind the peer instead of duplicating it in the frontend

All Use Cases