Connect Tidio to AI Agents: Train Lyro AI & Sync Knowledge Bases

You want to connect Tidio to an AI agent so your internal systems can autonomously update knowledge bases, train Lyro AI, triage incoming chat tickets, and manage customer records based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to code custom endpoints, handle pagination loops, or maintain complex API wrappers.

Giving a Large Language Model (LLM) read and write access to your Tidio workspace is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the quirks of conversational APIs, or you use a managed infrastructure layer that handles the boilerplate for you. If your team operates strictly within pre-built chat interfaces, check out our guide on connecting Tidio to ChatGPT, or if you are leaning into Anthropic's ecosystem for support ops, read our guide on connecting Tidio to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Tidio, bind them natively to an LLM using your framework of choice (LangChain, LangGraph, CrewAI, or Vercel AI SDK), and execute complex customer support workflows. For a deeper look at the architecture behind this approach and why standard APIs fail in agentic loops, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Tidio Connectors

Building AI agents is easy. Connecting them to external SaaS APIs safely is hard. Giving an LLM access to external data sounds simple in a prototype - you write a Node.js function that makes a fetch request and wrap it in a tool decorator. In production, this approach collapses, especially with an ecosystem as highly specific as Tidio.

If you decide to build the Tidio integration yourself, you own the entire API lifecycle. Tidio's conversational and AI-focused API introduces several highly specific integration challenges that break standard LLM assumptions.

The Asynchronous Lyro Trap

Tidio provides specific endpoints to interact with their native AI agent, Lyro. When you call the Lyro answer ticket endpoint, you are asking Tidio's internal model to process ticket data and return a response. Tidio documents that this specific operation can take up to 40 seconds.

Standard LLM frameworks usually operate on 10 to 15-second timeout defaults. If you hand-code this connection without understanding this latency, your agent will drop the connection, assume the tool failed, and either hallucinate a response or enter an infinite retry loop while Tidio is still processing the first request in the background. Your integration layer must account for extremely long-polling read operations without blocking the rest of your agent's execution thread.

Split Message Envelopes

When an LLM needs to understand a customer's problem, it needs the conversation history. However, Tidio's API splits the ticket envelope from the actual message content. If you call the endpoint to list tickets, you receive metadata - status, priority, and assigned operator - but zero messages.

To get the actual chat history, the agent must know to first query the list, extract the specific id, and then make a secondary call to fetch the single ticket by ID. If you expose raw REST endpoints to the LLM, the model frequently hallucinates that the list endpoint accepts a include_messages=true query parameter because that is how Stripe or HubSpot might design an API. It fails. The agent needs strictly defined, single-purpose tools with absolute clarity on what data is returned.

Strict All-or-Nothing Batch Schemas

Tidio offers bulk creation and update endpoints for contacts and products, allowing up to 100 records per request. The constraint is that these are strict all-or-nothing transactions. If your agent attempts to sync 100 contacts and one of them is missing the required distinct_id or has a malformed email format, Tidio rejects the entire batch with a 400 Bad Request.

LLMs are notoriously bad at strictly adhering to schema constraints across large JSON arrays. If you simply hand the raw bulk endpoint to the model, it will fail repeatedly on minor formatting errors, burning through your token limits on useless retries.

Architecting the Tool Layer: Proxy APIs and JSON Schemas

To solve these challenges safely, you must place a deterministic abstraction layer between your LLM and the raw Tidio API.

Every integration on Truto operates as a comprehensive JSON object representing how the underlying product's API behaves - essentially a swagger file built specifically for integrations. Truto defines Resources that map to the endpoints on Tidio's API, enabling us to map the API into a REST-based CRUD API.

Every Resource has Methods defined on them - standard operations like List, Get, Create, Update, and custom operations like "Reply to Ticket". These Methods operate as Proxy APIs where Truto handles all the underlying authentication and query parameter processing.

When solving problems agentically, these Proxy APIs are the perfect unit of work. Truto calls the /integrated-account/:id/tools endpoint to return all of these Proxy APIs with their exact descriptions and schemas, creating stable, highly specific Tools that LLM frameworks can consume natively.

Tidio Hero Tools for AI Agents

Rather than dumping 50 raw endpoints into your agent's context window - which guarantees hallucination and context exhaustion - Truto exposes specific, purpose-built tools. Here are the highest-leverage tools available for Tidio automation.

Ask Lyro AI to Answer Ticket

Tool Name: tidio_lyro_answer_ticket

This tool allows your custom agent to hand off specific interactions to Tidio's native Lyro AI. It submits the ticket data and asks Lyro to generate an answer based on Tidio's internal knowledge base. Because this can take up to 40 seconds, the tool abstracts the polling complexity. Note that it currently only works for the first message in a ticket.

"Review ticket #9823. Pass the initial customer inquiry to Lyro AI to see how the native knowledge base would respond. If the Lyro response indicates the issue requires human escalation, tag the ticket as priority."

Scrape Website for Lyro Data Source

Tool Name: tidio_lyro_data_sources_scrape_website

Training a support bot requires constant knowledge base updates. This tool allows your agent to submit a website URL to be scraped and immediately ingested as a knowledge data source for the Tidio Lyro AI Agent. This is critical for workflows where your agent detects documentation updates and triggers a sync in Tidio.

"I just published a new pricing page at https://example.com/pricing. Submit this URL to Tidio so Lyro AI can scrape it and update its knowledge source regarding our new tiers."

Fetch Full Ticket Details

Tool Name: get_single_tidio_ticket_by_id

Because the list endpoint does not contain chat history, this tool is mandatory for context gathering. It returns the ticket metadata along with the complete array of messages, allowing your agent to read the entire back-and-forth conversation before taking action.

"Retrieve the full conversation history for ticket #14992. Summarize the user's frustration and determine if the support operator provided the correct refund link."

Reply to a Tidio Ticket

Tool Name: tidio_tickets_reply

This is the primary write tool for customer interaction. It adds a reply message to an existing Tidio ticket. The schema strictly enforces the author_type and content fields, ensuring your agent correctly attributes the message as coming from an operator rather than spoofing a customer response.

"Draft a polite response to ticket #11200 apologizing for the downtime. Use the tidio_tickets_reply tool to post this message directly to the customer as an operator."

Bulk Update Tidio Contacts

Tool Name: tidio_contacts_bulk_update

When your agent needs to synchronize user states from your database (like newsletter opt-outs or plan changes) into Tidio, it uses this tool. It processes up to 100 contacts in a single batch request using an all-or-nothing strategy, updating properties like email_consent and custom fields.

"Take this list of 45 users who just downgraded their accounts. Use the bulk update tool to modify their custom properties in Tidio to reflect their new 'free_tier' status."

List All Department UUIDs

Tool Name: list_all_tidio_departments

When routing tickets, Tidio requires a specific UUID for the assigned_department_id. Your agent cannot guess these IDs by name. This read-only tool fetches the master list of departments, giving the LLM the exact UUIDs it needs before it attempts to update or reassign a ticket.

"Fetch the list of all Tidio departments. Find the UUID for the 'Billing Escalations' team, then reassign ticket #8833 to that specific department ID."

To view the complete inventory of available tools, required arguments, and exact JSON schemas for this integration, visit the Tidio integration page.

Workflows in Action

When you combine these tools, your agent transitions from a basic chatbot to an autonomous revenue and support operations engine. Here is what that looks like in practice.

Workflow 1: The Autonomous Knowledge Base Sync

When your marketing or engineering team ships new documentation, your support AI needs to know immediately. You can instruct your agent to sync documentation states directly to Lyro.

"We just deployed new documentation for our API rate limits at /docs/rate-limits. Update the Tidio Lyro AI data sources so the bot stops giving customers outdated information."

Execution Steps:

1. list_all_tidio_lyro_data_sources: The agent checks the existing data sources to see if a rate limit source already exists.
2. tidio_lyro_data_sources_upsert_website: The agent decides to upsert the URL. It passes the URL, the raw Markdown content of the new docs, and the title. Tidio updates the existing node or creates a new one, returning the ID.

Result: Lyro is instantly trained on the new documentation without a human logging into the Tidio dashboard to trigger a manual scrape.

Workflow 2: Intelligent Ticket Triage and Handoff

Instead of making human operators read every ticket to decide who should handle it, an agent can read the queue, analyze sentiment, and route requests.

"Look at the 5 most recent open tickets. If any of them mention 'refund' or 'cancel', assign them to the Retention department and add an internal note summarizing the account state."

Execution Steps:

1. list_all_tidio_tickets: The agent fetches the latest open tickets to get their IDs.
2. get_single_tidio_ticket_by_id: The agent loops through the IDs, fetching the full message arrays to analyze the text for cancellation intent.
3. list_all_tidio_departments: The agent identifies two tickets requiring escalation and fetches the department UUID for 'Retention'.
4. update_a_tidio_ticket_by_id: The agent updates both tickets, passing the specific UUID into the assigned_department_id field.

Result: The retention team logs in to find their queue perfectly populated with high-risk churn tickets, avoiding delays in the general triage bucket.

Building Multi-Step Workflows

To implement this in your codebase, you need to pull the tools dynamically from Truto and hand them to your LLM. Because Truto standardizes the schemas, this works seamlessly across LangChain, Vercel AI SDK, or custom pipelines.

Here is how you fetch the tools and execute an agent loop using the truto-langchainjs-toolset.

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
// 1. Initialize the LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
});
 
// 2. Fetch Tidio tools from Truto for a specific account
const trutoManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "tidio_account_88392",
});
 
// Optionally filter to just custom or read methods if you want a read-only agent
const tools = await trutoManager.getTools(); 
 
// 3. Create the prompt instruction
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a support operations agent. You manage Tidio tickets and Lyro knowledge bases. Always fetch full ticket details before replying."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);
 
// 4. Bind the tools and create the executor
const agent = createToolCallingAgent({
  llm,
  tools,
  prompt,
});
 
const agentExecutor = new AgentExecutor({
  agent,
  tools,
});
 
// 5. Execute the workflow
const result = await agentExecutor.invoke({
  input: "Find ticket #4492. Read the history and reply telling them we are looking into the database outage."
});
 
console.log(result.output);

Handling Rate Limits and Error States

When your agent is looping through dozens of tickets or scraping multiple data sources, you will inevitably hit Tidio's API rate limits.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When an upstream API like Tidio returns an HTTP 429 (Too Many Requests), Truto passes that exact error back to the caller.

However, Truto does the heavy lifting of normalizing the wildly different upstream rate limit information into standardized headers per the IETF specification. Regardless of how Tidio formats its limits, you will receive:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

The caller (your agent framework) is fully responsible for reading these headers and executing the retry or backoff logic.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto Proxy
    participant Tidio as Tidio API

    Agent->>Truto: Call get_single_tidio_ticket_by_id
    Truto->>Tidio: GET /v1/tickets/4492
    Tidio-->>Truto: 429 Too Many Requests<br>(Vendor specific headers)
    Truto-->>Agent: 429 Too Many Requests<br>(Standard IETF headers)
    Note over Agent: Agent reads ratelimit-reset<br>Pauses execution for N seconds
    Agent->>Truto: Retry get_single_tidio_ticket_by_id
    Truto->>Tidio: GET /v1/tickets/4492
    Tidio-->>Truto: 200 OK
    Truto-->>Agent: Ticket Data

By pushing the 429 down to the caller with normalized headers, your system retains total control over its execution state. You don't have hidden queues holding requests hostage, and your agent can intelligently decide to pause execution or alert a human that the API quota is exhausted.

Moving Beyond Point-to-Point Connectors

Building a custom Tidio integration for an AI agent is a trap. You start by writing a simple fetch request for ticket replies. Next, you have to parse Tidio's specific pagination logic. Then, you have to write error handlers for their bulk creation endpoints. Finally, you have to figure out how to maintain this connector when Tidio updates their Lyro API schemas.

By using Truto's /tools endpoint, you offload the entirety of the API lifecycle. Your LLM receives clean, standardized JSON schemas that update automatically when resources change. You get the flexibility to execute complex customer support workflows across any LLM framework, safely and predictably.