Connect Desk365 to AI Agents: Automate Tickets, Content & Time Logs

If your team uses ChatGPT, check out our guide on connecting Desk365 to ChatGPT. Alternatively, if you operate in the Anthropic ecosystem, we have a dedicated tutorial for connecting Desk365 to Claude.

Helpdesk operations require deep context. Customer support teams spend significant time cross-referencing ticket history, writing knowledge base (KB) articles, and logging time entries. Building AI agents to automate these tasks is highly effective, but only if you know how to safely give an AI agent access to third-party SaaS data and provide the agents with real-time read and write access to your underlying ticketing system.

This guide demonstrates how to connect Desk365 to AI agents using Truto's /tools endpoint and the Langchain SDK (truto-langchainjs-toolset). We will walk through fetching proxy tools, binding them to an LLM, structuring multi-step agent loops, and handling real-world API complexities. For broader context on this architectural approach, see our deep dive on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

The Engineering Reality of the Desk365 API

Before wiring an LLM directly into Desk365, it is important to understand the specific mechanical quirks of the vendor's API. LLMs assume logical REST boundaries. When APIs deviate from standard patterns, agents fail unless you have a standardized tool abstraction.

Here are three specific Desk365 API behaviors that commonly trip up integration builds:

1. Multipart Mixed Payloads for Attachments: Creating tickets or adding replies with attachments in Desk365 requires an unusual payload structure. You must send the file in the multipart body, but the actual metadata (the ticket_object, reply_object, or contact_object) must be stringified and passed in the query parameters. Truto handles the schema definition for this, but your agent needs to know exactly how to structure the parameters.
2. Strictly Bucketed Pagination Limits: Unlike APIs that accept arbitrary limit parameters (e.g., limit=25), Desk365 strictly enforces bucketed pagination. The ticket_count and time_entries_count parameters only accept exactly 30, 50, or 100. If an agent arbitrarily hallucinates limit=10, the API will throw an error.
3. Special Access Contract Endpoints: The Contracts API (list_all_desk_365_contracts, create_a_desk_365_contract, etc.) is documented as special access. It is not available by default on standard tenant configurations. You must contact help@desk365.io to unlock these routes. If an agent attempts to query them prematurely, it will face opaque authorization failures.

Desk365 Tool Inventory

Truto provides pre-configured AI tools that map directly to the Desk365 REST API endpoints. You can view the full integration schema on the Desk365 integration page.

Core Hero Tools

These tools form the backbone of most automated helpdesk agent workflows.

list_all_desk_365_tickets

Retrieves an array of tickets. Crucially, the agent must use the ticket_count parameter set to 30, 50, or 100. It supports documented Desk365 filters and include_* query parameters to fetch associated metadata in a single network call.

"Fetch the 30 most recent open tickets assigned to the network infrastructure team."

get_single_desk_365_ticket_by_id

Fetches complete details for a specific ticket. The resource ID required is the ticket_number.

"Get me the full details and current status of ticket #9042."

desk_365_ticket_replies_create_with_attachment

Appends a reply to an existing ticket while attaching a file. The agent must pass the ticket_number and the stringified reply_object as query parameters, and submit the file via a multipart body.

"Reply to ticket #411 saying 'Here is the requested log export' and attach the server_logs.csv file."

list_all_desk_365_ticket_conversations

Extracts the full thread of a ticket's history. This is vital for RAG workflows where an agent needs to read a long back-and-forth exchange before generating a summary or a KB article.

"Read the entire conversation history for ticket #881."

create_a_desk_365_time_entry

Logs agent time against a specific issue. Requires the ticket_number as a query parameter.

"Log 45 minutes of billable time against ticket #102 for debugging the SSO configuration."

create_a_desk_365_kb_article

Publishes a new article to the Desk365 Knowledge Base. Highly effective for agents designed to automatically generate documentation from resolved incident tickets.

"Create a new KB article titled 'Resetting 2FA Tokens' using the resolution steps we just discussed."

For the complete tool inventory and full schema details, visit the Desk365 integration page.

Building Multi-Step Workflows

Truto exposes an integrated account's available resources through the /integrated-account/<id>/tools endpoint. Our SDKs dynamically read this endpoint to register tool schemas into frameworks like LangChain, CrewAI, or the Vercel AI SDK.

Handling Rate Limits in Agent Loops

When deploying AI agents in production, autonomous loops can quickly burn through API rate limits. This follows our zero data retention and pass-through architecture philosophy; when Desk365 returns an HTTP 429, Truto passes that exact error back to the caller.

However, Truto normalizes upstream rate limit data into IETF standardized headers: ratelimit-limit, ratelimit-remaining, and ratelimit-reset. The caller is entirely responsible for implementing retry and backoff logic. If your agent framework ignores HTTP 429s, the loop will crash.

sequenceDiagram
    participant Agent as LLM Agent
    participant SDK as TrutoToolManager
    participant Truto as Truto API
    participant Desk365 as Desk365 API

    Agent->>SDK: Execute tool proxy request
    SDK->>Truto: Transformed tool call
    Truto->>Desk365: Underlying REST call
    Desk365-->>Truto: HTTP 429 (Rate Limited)
    Truto-->>SDK: HTTP 429 + ratelimit-* headers
    SDK-->>Agent: Throw API error
    Note over Agent: Agent catches 429, reads ratelimit-reset,<br>sleeps, and retries action.
    Agent->>SDK: Retry action

Code Implementation with LangChain

Here is how you fetch the tools, bind them to an OpenAI agent, and prepare your execution loop to handle standard rate limit errors.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runAgent() {
  // Initialize the LLM
  const llm = new ChatOpenAI({ model: "gpt-4o", temperature: 0 });
 
  // Initialize Truto SDK with your API Key and the user's Desk365 Connection ID
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    integratedAccountId: process.env.DESK365_ACCOUNT_ID,
  });
 
  // Dynamically fetch tools from the Truto API
  const tools = await toolManager.getTools();
  
  // Bind the Desk365 tools to the LLM
  const agentWithTools = llm.bindTools(tools);
 
  // Execute agent action
  try {
    const response = await agentWithTools.invoke([
      ["system", "You are an autonomous helpdesk assistant."],
      ["human", "List the latest 30 tickets and summarize their status."]
    ]);
    
    console.log(response.tool_calls);
  } catch (error) {
    if (error.response && error.response.status === 429) {
      // Read standardized headers passed through by Truto
      const resetTime = error.response.headers.get('ratelimit-reset');
      console.warn(`Rate limited. Caller must sleep until ${resetTime}`);
      // Implement your custom sleep/backoff logic here
    } else {
      throw error;
    }
  }
}

Workflows in Action

When AI agents have access to a full suite of read and write tools, they can transition from answering questions to executing complex, cross-domain workflows autonomously.

Scenario 1: Ticket Resolution & Time Logging

Agents can act as copilot assistants for L2 engineers, handling the administrative overhead of closing out a ticket and logging time.

"Check ticket #492. Reply to the customer saying the network bug is fixed and attach the patch-verification.log file. Once that is done, log 45 minutes of time against the ticket for the debugging process."

Agent Execution Path:

1. Calls get_single_desk_365_ticket_by_id (Passing ticket_number: 492) to verify the ticket exists and is currently open.
2. Calls desk_365_ticket_replies_create_with_attachment (Passing ticket_number: 492, supplying the stringified reply_object in query params, and appending the .log file in the multipart body).
3. Calls create_a_desk_365_time_entry (Passing ticket_number: 492, and supplying the time value mapped to 45 minutes).

Result: The user gets a confirmation that the customer has been notified with the correct file, and their timesheet reflects the 45-minute debugging session.

Scenario 2: Automated Knowledge Base Generation

Knowledge base decay is a massive problem for IT teams. Agents can automatically convert complex ticket resolutions into polished KB articles.

"Review the entire conversation history of ticket #805. Extract the root cause and the step-by-step resolution steps. Use that information to create a new KB article in the 'Troubleshooting' category named 'Database Timeout Fix'."

Agent Execution Path:

1. Calls list_all_desk_365_ticket_conversations (Passing ticket_number: 805) to pull the full back-and-forth thread.
2. Internal processing: The LLM analyzes the thread, identifies the core issue, and drafts structured documentation in markdown.
3. Calls get_single_desk_365_kb_category_by_id (Passing the resource ID: 'Troubleshooting') to fetch the necessary category mappings.
4. Calls create_a_desk_365_kb_article to publish the generated markdown draft into Desk365.

Result: The user is provided with a direct link to a freshly minted KB article, created solely from the context of a solved support ticket.

Building enterprise-grade AI agents requires flawless integration infrastructure. Learn how Truto's unified tools eliminate schema normalization and authentication boilerplate for your team. :::