Use case

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.

• Stack Client SDK
• Pattern Chat · Widget
• Read ~6 min

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.

When to reach for this use case

If your team needs the capabilities described above and you would rather build on proven primitives than wire one from scratch — this is the shape to start from.

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

---

Products used

This pattern is built on one Cognipeer product.

@cognipeer/sdk

Client SDK

Connect apps to Cognipeer Studio peers, conversations, and client-side tool execution.

The peer itself is authored and maintained in Cognipeer Studio — the SDK only connects your product to it.

Related use cases

Chat · Widget

Expense Upload & Approval Widget

Let employees upload receipts, extract fields, and submit expense requests through a Studio-powered finance widget embedded in your product.

Chat · Mobile

Mobile Peer Embedded In The App

Run a Studio peer directly inside a mobile app so it can answer users and trigger native app actions such as screen navigation, camera capture, and task execution.

Chat · Widget

Website Product Advisor Widget

Embed a Studio peer into a public website to qualify visitors, answer pricing questions, and trigger product actions without building a separate bot backend.

Chat · Support

Customer Support Bot

Deploy conversational AI with streaming responses, human-in-the-loop escalation, guardrails, and tool transparency.

See every pattern on the use case index, or browse all Cognipeer libraries.