Skip to main content

​
Overview

Agents are users with access to the helpdesk system who can respond to and manage tickets. The Agents API provides functionality for inviting and managing helpdesk agents.

​
Agent DocType Fields

The HD Agent DocType contains the following fields:
​
name
string
Unique identifier for the agent (typically the user email)
​
user
Link
required
Link to the User doctype
​
agent_name
string
required
Display name of the agent
​
user_image
Attach Image
Profile image for the agent
​
is_active
boolean
default:"true"
Whether the agent is currently active

​
Send Invites

Sends invitations to new agents by creating user accounts and HD Agent records.
This endpoint is defined in helpdesk/api/agent.py:6 and is restricted to agents only via the @agent_only decorator
@frappe.whitelist()
@agent_only
def sent_invites(emails: list[str], send_welcome_mail_to_user: bool = True):
    """Send invites to new agents
    
    Creates User records if they don't exist and creates HD Agent records.
    Optionally sends welcome emails to new users.
    """
​
emails
array
required
Array of email addresses to invite as agents
​
send_welcome_mail_to_user
boolean
default:"true"
Whether to send welcome emails to newly created users

​
Behavior

For each email address:
  1. Checks if a User record exists
  2. If not, creates a new User with:
    • Email as the identifier
    • First name extracted from email (part before @)
  3. Sends welcome email if send_welcome_mail_to_user is true
  4. Creates an HD Agent record with:
    • User link
    • Agent name (from user’s full name)
    • User image (from user profile)

​
Example Request

import frappe

# Invite multiple agents
frappe.call(
    "helpdesk.api.agent.sent_invites",
    emails=["[email protected]", "[email protected]"],
    send_welcome_mail_to_user=True
)

​
Response

Returns None on success. Creates the following records:
  • User documents (if they don’t exist)
  • HD Agent documents

​
Permissions

This endpoint requires the caller to be an agent (enforced by @agent_only decorator).

​
Get Agent Details

Retrieve agent information using standard Frappe APIs. 
import frappe

# Get single agent
agent = frappe.get_doc("HD Agent", "[email protected]")

print(f"Agent: {agent.agent_name}")
print(f"Active: {agent.is_active}")

​
List All Agents

Query all agents with filters: 
import frappe

# Get all active agents
active_agents = frappe.get_list(
    "HD Agent",
    filters={"is_active": 1},
    fields=["name", "agent_name", "user_image"],
    order_by="agent_name asc"
)

for agent in active_agents:
    print(f"{agent.agent_name} ({agent.name})")

​
Update Agent Status

import frappe

# Deactivate an agent
frappe.db.set_value(
    "HD Agent",
    "[email protected]",
    "is_active",
    0
)

​
Agent Assignment

Agents are assigned to tickets using the Assignment feature. See the Tickets API for assignment operations.

​
Agent Groups (Teams)

Agents can be organized into teams using the HD Team DocType. Teams are referenced in:
  • Ticket assignments (agent_group field)
  • Assignment rules
  • Saved reply permissions
import frappe

# Get agents in a specific team
team = frappe.get_doc("HD Team", "Support Team")

# Team members are stored in a child table
for member in team.team_members:
    print(f"Agent: {member.agent}")

​
Agent Permissions

Agents have specific role permissions:
  • Agent Role: Can create, read, update tickets and related records
  • Agent Manager Role: Has additional permissions for managing teams and settings
  • System Manager: Full administrative access

​
Example: Complete Agent Onboarding

import frappe

# 1. Invite new agent
frappe.call(
    "helpdesk.api.agent.sent_invites",
    emails=["[email protected]"],
    send_welcome_mail_to_user=True
)

# 2. Add agent to a team
team = frappe.get_doc("HD Team", "Technical Support")
team.append("team_members", {
    "agent": "[email protected]"
})
team.save()

# 3. Assign agent to their first ticket
ticket = frappe.get_doc("HD Ticket", "12345")
ticket.assign_agent("[email protected]")

​
Check if User is Agent

Use the utility function from helpdesk.utils: 
from helpdesk.utils import is_agent

if is_agent():
    # Current user is an agent
    print("Access granted")
else:
    print("Access denied")

​
Standard Frappe API Methods

Since HD Agent is a standard DocType, all Frappe document APIs are available:
  • frappe.get_doc("HD Agent", agent_id) - Get single agent
  • frappe.get_list("HD Agent", filters={...}) - Query agents
  • frappe.db.exists("HD Agent", agent_id) - Check if agent exists
  • frappe.delete_doc("HD Agent", agent_id) - Remove agent

Build docs developers (and LLMs) love

Get started for freeTalk to us