Personio Chatbot: How to Build and Integrate an AI HR Assistant

If your HR team uses Personio and spends hours answering the same questions about leave balances, onboarding checklists, and expense policies, a chatbot can cut that workload significantly. This guide covers every approach, from Personio's built-in AI features to building a custom chatbot on their API.

What Personio Offers Out of the Box

Personio is Europe's leading HR platform for small and mid-sized companies, serving 14,000+ customers across 70+ countries. It covers the full employee lifecycle: recruiting, onboarding, attendance, payroll, performance, and offboarding.

On the chatbot side, Personio ships two native AI features:

Personio Conversations is an HR helpdesk module with a built-in AI chatbot. HR teams create knowledge base articles (leave policies, benefits guides, onboarding steps), and the chatbot automatically answers employee questions 24/7 by pulling from that knowledge base. When the chatbot cannot resolve a query, it routes the ticket to the right HR specialist.

Personio Assistant (launched Q4 2025) focuses on organizational insights. It answers analytical questions for managers and HR leads: workforce trends, headcount changes, and team performance patterns.

Both integrate with Slack and Microsoft Teams, so employees can submit requests without leaving their daily tools.

Personio Conversations vs Custom Chatbot: When to Use Which

| Factor | Personio Conversations | Custom Chatbot (API) | |---|---|---| | Setup time | Hours (knowledge base articles) | Days to weeks (dev work) | | Maintenance | HR team manages articles | Engineering maintains code | | Data access | Knowledge base only | Full Personio data (employees, absences, attendance) | | Customization | Limited to Personio's UI/UX | Full control over behavior and responses | | Channel support | Slack, Teams, Personio portal | Any channel you build for | | Cost | Included in Personio plan | API access + hosting + LLM costs | | Best for | FAQ deflection, policy questions | Complex workflows, cross-system queries |

Architecture of a Custom Personio Chatbot

If you need more than knowledge base Q&A, you will build a chatbot that talks to Personio's REST API. Here is the typical architecture:

The chatbot sits between your messaging platform and Personio's API. When an employee asks "How many vacation days do I have left?", the chatbot:

1. Receives the message from Slack or Teams
2. Classifies intent (leave balance query)
3. Calls the Personio API to fetch the employee's absence data
4. Formats the response and sends it back

Authenticating with the Personio API

Personio uses OAuth-style client credentials. You request a JWT token with your client_id and client_secret, then use that token for all subsequent API calls.

import requests

PERSONIO_CLIENT_ID = "your_client_id"
PERSONIO_CLIENT_SECRET = "your_client_secret"

def get_personio_token():
    response = requests.post(
        "https://api.personio.de/v1/auth",
        json={
            "client_id": PERSONIO_CLIENT_ID,
            "client_secret": PERSONIO_CLIENT_SECRET,
        },
    )
    response.raise_for_status()
    return response.json()["data"]["token"]

token = get_personio_token()
headers = {"Authorization": f"Bearer {token}"}

Tokens are valid for a limited time. Cache the token and refresh it when you get a 401.

Key API Endpoints for Chatbot Use Cases

The Personio API (v1 and v2) exposes endpoints that map directly to common chatbot interactions:

| Endpoint | Method | Chatbot Use Case | |---|---|---| | /v1/company/employees | GET | Look up employee details, org chart | | /v1/company/employees/{id} | GET | Fetch specific employee profile | | /v1/company/time-offs | GET | Check leave balances, upcoming absences | | /v1/company/time-offs | POST | Submit absence requests via chat | | /v2/company/attendances | GET | Retrieve attendance records | | /v2/company/attendances | POST | Clock in/out via chat | | /v1/company/documents | GET | Fetch payslips, contracts |

Fetching Leave Balances (Practical Example)

Here is a working example that fetches an employee's remaining vacation days:

def get_leave_balance(employee_id: int, token: str) -> dict:
    """Fetch absence entitlements for an employee."""
    response = requests.get(
        "https://api.personio.de/v1/company/time-offs",
        headers={"Authorization": f"Bearer {token}"},
        params={
            "employees[]": employee_id,
            "start_date": "2026-01-01",
            "end_date": "2026-12-31",
        },
    )
    response.raise_for_status()
    absences = response.json()["data"]

    total_taken = sum(
        a["attributes"]["days_count"] for a in absences
        if a["attributes"]["status"] == "approved"
    )
    return {
        "employee_id": employee_id,
        "days_taken": total_taken,
        "absences": len(absences),
    }

Pair this with an LLM to turn the raw data into a natural language response: "You have taken 8 vacation days so far this year, with 22 remaining."

Connecting to Slack or Microsoft Teams

Most Personio chatbots live inside Slack or Teams, since that is where employees already work. The integration pattern is the same for both:

1. Register a bot in your Slack workspace (Slack API) or Azure AD (Teams Bot Framework)
2. Listen for messages via webhooks or the Events API
3. Parse intent using an LLM or simple keyword matching
4. Call the Personio API with the relevant endpoint
5. Reply with a formatted message (Slack Block Kit or Teams Adaptive Cards)

For Slack specifically, you can use the slack_bolt Python library:

from slack_bolt import App

app = App(token="xoxb-your-token", signing_secret="your-secret")

@app.message("leave balance")
def handle_leave_balance(message, say):
    # Map Slack user to Personio employee ID
    employee_id = lookup_employee(message["user"])
    balance = get_leave_balance(employee_id, get_personio_token())
    say(f"You have taken {balance['days_taken']} days so far this year.")

app.start(port=3000)

Third-Party Platforms with Personio Connectors

If building from scratch is too much for your team, several platforms offer pre-built Personio integrations:

These tools lower the barrier if you do not have dedicated backend engineers, but they trade off customization for speed.

Common Pitfalls

• Ignoring API rate limits. Personio enforces rate limits on their API. If your chatbot serves 500+ employees, cache responses (employee profiles change rarely) and batch requests where possible. Hitting the limit means degraded service for everyone.

• Skipping employee identity mapping. Your chatbot needs to map a Slack user ID to a Personio employee ID. If you skip this step, you end up asking the employee to type their employee number every time, which kills adoption. Build a one-time linking flow during onboarding.

• Storing HR data in chat logs. Personio data includes salaries, personal addresses, and contract details. If your chatbot fetches sensitive fields, make sure you are not logging them in Slack's channel history. Use ephemeral messages for anything private.

• Building before checking Personio Conversations. The built-in feature handles 70-80% of FAQ deflection use cases. If your entire need is "employees ask policy questions," you do not need a custom chatbot at all.

• Forgetting the v1 deprecation timeline. The v1 Attendance and Projects endpoints sunset on July 31, 2026. Code that works today will break if you do not migrate to v2.

Implementation Checklist

Here is a minimal checklist for getting a Personio chatbot from zero to production:

1. Decide scope: FAQ deflection only (use Personio Conversations) or live data queries (build custom)
2. Get API credentials from Personio admin panel (Settings > Integrations > API credentials)
3. Build the auth flow (client credentials to JWT token)
4. Map your messaging platform users to Personio employee IDs
5. Implement 2-3 high-value intents first (leave balance, absence request, attendance check)
6. Add fallback routing to a human HR specialist for anything the bot cannot handle
7. Test with a pilot group before company-wide rollout
8. Monitor API usage and cache aggressively

Wrapping Up

A Personio chatbot can take your HR team from answering the same five questions 200 times a month to focusing on work that actually needs a human. Start with Personio Conversations for knowledge base Q&A, and build a custom API integration only when you need live data access. The API is well-documented, the auth flow is straightforward, and the common endpoints map cleanly to what employees actually ask about.

Fazm is an open source macOS AI agent that automates desktop workflows. Open source on GitHub.