HR Self-Service Widget

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 recipe

If your team needs the capabilities described above and you'd 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.

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 recipes Suggest a change

Overview

When to reach for this recipe

Architecture

1. Connect The Portal Widget To Studio

2. Expose HR Actions As Client Tools

3. Start The HR Conversation

Result

Related recipes

Expense Upload & Approval Widget

Mobile Peer Embedded In The App

Website Product Advisor Widget

Customer Support Bot