Connect Trustpilot to AI Agents: Sync Catalog Data & Invitations

You want to connect Trustpilot to an AI agent so your system can autonomously triage negative reviews, sync product catalogs, trigger review invitations, and extract customer sentiment from specific order IDs. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build, maintain, and secure a custom Trustpilot connector from scratch.

Giving a Large Language Model (LLM) read and write access to your Trustpilot instance is an engineering headache. You either spend weeks dealing with Trustpilot's distinct public/private API boundaries, managing API keys, and handling strict pagination rules, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Trustpilot to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Trustpilot to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Trustpilot, bind them natively to an LLM using LangChain (or frameworks like LangGraph, CrewAI, or the Vercel AI SDK), and execute complex reputation management workflows. For a broader look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a single line of integration code, you must decide what layer your agent talks to. This architectural choice determines how resilient your production system will be.

Direct API tools - mapping one tool directly to one raw Trustpilot endpoint - look convenient in a quick prototype. But they force the LLM to memorize the quirks of the vendor's API. The model has to remember that it needs to resolve a domain to a Business Unit ID before doing anything else, that customer emails only appear in private review endpoints, and that product review invitations require pre-existing catalog SKUs. Every one of those required logical jumps is a hallucination waiting to happen.

A unified tool layer abstracts these mechanics behind predictable schemas. Your agent sees deterministic functions with strict JSON schemas. This gives you three concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only chooses from defined function schemas. Invalid arguments are rejected before they hit the upstream API, meaning a broken tool call fails fast.
2. Normalized authentication. Your agent framework never touches a raw Trustpilot API key or handles OAuth token refreshes.
3. Framework agnosticism. Truto's /tools endpoint serves standard JSON schemas that comply with OpenAI's function calling spec, meaning they can be consumed by any modern agent framework - NOT just Model Context Protocol (MCP) servers.

The Engineering Reality of the Trustpilot API

Giving an LLM access to external data sounds simple until you hit the engineering realities of a legacy B2B platform. Trustpilot's API introduces several specific integration challenges that will break a naive agent implementation.

The Business Unit ID Dependency

In Trustpilot's architecture, virtually all data belongs to a Business Unit (BU). Your agent cannot simply ask the API for "my latest reviews" or "create an invitation." Almost every operational endpoint requires a business_unit_id parameter.

This presents a severe challenge for autonomous agents. If a user prompts the agent with "Reply to the latest 1-star reviews for acme.com," the agent must first realize it needs to resolve the domain acme.com into a 24-character alphanumeric Business Unit ID, and then pass that ID into the subsequent review fetching endpoints. If you do not provide explicit tool descriptions mapping this relationship, the LLM will hallucinate a BU ID or fail the request entirely.

Strict Segregation of Public vs. Private Data

Trustpilot strictly segregates public profile data from private operational data. There is a public endpoint for listing reviews (/v1/business-units/{businessUnitId}/reviews) and a private endpoint (/v1/private/business-units/{businessUnitId}/reviews).

If you instruct an agent to "find the review written by john.doe@example.com and reply with their order status," the agent must know to use the private endpoint. The public endpoint redacts PII, meaning customer emails and reference order IDs will be missing from the payload. Providing both tools to the agent requires careful prompting to ensure the model selects the private tool when PII or order IDs are required.

Disjointed Service vs. Product Review Pipelines

Trustpilot treats Service Reviews (reviews of the company) and Product Reviews (reviews of specific SKUs) as completely different domains.

If you want an agent to trigger a product review invitation, the underlying product must already exist in Trustpilot's catalog. The agent cannot just send an email address and a product name; it must execute a trustpilot_catalog_products_batch_upsert to ensure the SKU exists, wait for success, and then trigger the trustpilot_invitations_create_email referencing that specific SKU. This multi-step state management requires precise tool descriptions.

Trustpilot Hero Tools for AI Agents

To build highly capable agents, you do not need to expose Trustpilot's entire 100+ endpoint surface area to the LLM. You only need to expose high-leverage operations. Here are the hero tools you should register.

1. trustpilot_business_units_find

This is the prerequisite tool for almost all agent workflows. It allows the agent to search for a Trustpilot business unit by its domain name and return the id required for subsequent API calls.

Contextual usage: Force the agent to call this tool whenever a user asks to interact with a specific domain's reviews, unless the BU ID is already injected into the system prompt.

"Find the Business Unit ID for 'example.com' so we can fetch their recent private reviews."

2. trustpilot_business_units_list_private_reviews

This tool retrieves reviews for a business unit, specifically including private details such as the customer's email address and their reference/order ID.

Contextual usage: Provide this tool when the agent needs to cross-reference Trustpilot reviews with internal CRM or helpdesk data. The agent can use the returned order ID to query Salesforce or Zendesk before drafting a response.

"Fetch the last 50 private reviews for our business unit. Find any 1-star reviews and extract the order IDs so I can look them up in our database."

3. create_a_trustpilot_review_reply

This tool allows the agent to post a public reply to a specific service review on behalf of the business.

Contextual usage: Use this in an autonomous reputation management loop. The agent reads the review, analyzes the sentiment, queries internal tools for context, and then uses this tool to submit the final response. It requires the review_id.

"Draft a professional, empathetic reply to review ID 5f8a9b2c and publish it immediately."

4. trustpilot_catalog_products_batch_upsert

This tool allows the agent to create, update, or delete Trustpilot catalog products (and nested variants) in a single request.

Contextual usage: Before an agent can send out product review invitations, it must ensure the SKUs exist in Trustpilot. This tool handles the catalog synchronization step.

"Take these three new SKUs from our Shopify inventory export and upsert them into the Trustpilot product catalog."

5. trustpilot_invitations_create_email

This tool generates and sends an email invitation to a consumer, prompting them to leave a service and/or product review.

Contextual usage: Trigger this tool at the end of a fulfillment workflow. The agent requires the business_unit_id, consumer email, consumer name, reference number, and a template ID.

"Send a Trustpilot product review invitation to jane.smith@example.com for order #99281, referencing SKU 'PROD-A'."

6. trustpilot_product_reviews_list_summaries

This tool retrieves aggregated star ratings, distribution, and review counts for specific SKUs within a business unit.

Contextual usage: Use this tool when generating internal analytics reports or when the agent needs to evaluate which products are underperforming based on customer sentiment.

"Get the review summaries for SKUs 'PROD-A' and 'PROD-B' and tell me which one has a lower average star rating."

To see the full inventory of Trustpilot tools - including conversation threads, tags, and consumer profile endpoints - along with their exact JSON schemas, visit the Trustpilot integration page.

Workflows in Action

Understanding individual tools is helpful, but seeing how an LLM chains them together is where agent architecture gets real. Here are two concrete, multi-step workflows.

Scenario 1: Autonomous Triage and Context-Aware Replies

Customer support teams waste hours cross-referencing negative Trustpilot reviews against internal CRM records to figure out what went wrong. You can build an agent that does this triage automatically.

"Check our Trustpilot account (acme.com) for any new 1-star reviews. If you find one, get the order ID, check its status in our internal system, and draft a reply apologizing for the specific issue."

1. trustpilot_business_units_find: The agent searches for "acme.com" to retrieve the business_unit_id.
2. trustpilot_business_units_list_private_reviews: The agent queries the private endpoint, passing the ID and filtering for 1-star reviews. It receives the payload containing the text and the customer's reference order ID.
3. Internal CRM Tool: The agent calls a separate custom tool (e.g., get_salesforce_order) using the extracted order ID. It discovers the order was delayed by a logistics partner.
4. create_a_trustpilot_review_reply: The agent uses the context to call the reply tool, submitting: "Hi John, we are so sorry order #123 was delayed in transit by our shipping provider. We have refunded your shipping costs..."

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto API
    participant Trustpilot as Trustpilot API
    participant CRM as Internal CRM

    Agent->>Truto: Call trustpilot_business_units_find
    Truto->>Trustpilot: GET /v1/business-units/find
    Trustpilot-->>Truto: 200 OK (id: 5a1b2c...)
    Truto-->>Agent: Return businessUnitId

    Agent->>Truto: Call trustpilot_business_units_list_private_reviews
    Truto->>Trustpilot: GET /v1/private/business-units/{id}/reviews
    Trustpilot-->>Truto: 200 OK (includes order #123)
    Truto-->>Agent: Return private review payload

    Agent->>CRM: Lookup order #123
    CRM-->>Agent: Status: Delayed

    Agent->>Truto: Call create_a_trustpilot_review_reply
    Truto->>Trustpilot: POST /v1/private/reviews/{review_id}/reply
    Trustpilot-->>Truto: 204 No Content
    Truto-->>Agent: Success

Scenario 2: Just-in-Time Catalog Sync and Invitations

Marketing teams want to trigger review invitations immediately after a product is delivered. If the product is new, the SKU might not exist in Trustpilot yet. The agent must handle the catalog sync dynamically.

"Order #889 for SKU 'NEW-WIDGET-01' was just delivered to bob@example.com. Ensure the product exists in Trustpilot, then send him a review invitation."

1. trustpilot_catalog_products_batch_upsert: The agent receives the trigger. It first calls the upsert tool, passing the BU ID and the products array containing { "sku": "NEW-WIDGET-01", "title": "New Widget", "productUrl": "..." }.
2. trustpilot_invitations_create_email: Once the upsert returns successfully, the agent calls the invitation tool, passing Bob's email, the reference number (#889), and the newly synced SKU. The user receives a seamless product review request.

Building Multi-Step Workflows

To build these workflows in code, you need an orchestration layer. Truto provides a set of tools for your LLM frameworks by offering a description and schema for all the proxy API methods defined on an integration.

By calling Truto's /integrated-account/:id/tools endpoint, you fetch JSON definitions that you can immediately bind to your agent.

Here is how you do it using TypeScript and LangChain via the truto-langchainjs-toolset.

1. Initialize the Tool Manager

You need to initialize the TrutoToolManager with your Truto environment details and the specific integrated account ID for your Trustpilot connection.

import { TrutoToolManager } from 'truto-langchainjs-toolset';
import { ChatOpenAI } from '@langchain/openai';
 
// Initialize the Tool Manager
const toolManager = new TrutoToolManager({
  trutoUrl: 'https://api.truto.one',
  token: process.env.TRUTO_API_KEY,
  integratedAccountId: process.env.TRUSTPILOT_INTEGRATED_ACCOUNT_ID
});

2. Fetch Tools and Bind to the LLM

Instead of manually writing JSON schemas for Trustpilot's 100+ endpoints, you fetch them dynamically. You can filter the tools to only include the ones your agent needs - for example, filtering to only read methods if you want a read-only agent.

// Fetch all tools available for this Trustpilot account
const tools = await toolManager.getTools();
 
// Initialize your LLM
const llm = new ChatOpenAI({
  modelName: 'gpt-4o',
  temperature: 0,
});
 
// Bind the tools to the model natively
const llmWithTools = llm.bindTools(tools);

3. Executing the Agent Loop

When the agent decides to invoke a Trustpilot tool, you execute standard function calling logic.

One critical engineering reality to handle here is Rate Limiting. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Trustpilot API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your agent execution loop is responsible for checking these headers, parsing ratelimit-reset, and implementing backoff logic.

import { HumanMessage } from '@langchain/core/messages';
 
async function runAgent(prompt: string) {
  const messages = [new HumanMessage(prompt)];
  
  while (true) {
    const response = await llmWithTools.invoke(messages);
    messages.push(response);
 
    if (!response.tool_calls || response.tool_calls.length === 0) {
      // The agent has finished its task and returned a natural language response
      console.log("Agent finished:", response.content);
      break;
    }
 
    for (const toolCall of response.tool_calls) {
      try {
        // Find the tool by name
        const tool = tools.find(t => t.name === toolCall.name);
        if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
        
        // Execute the tool against the Truto unified API layer
        const toolResult = await tool.invoke(toolCall.args);
        
        messages.push({
          role: 'tool',
          name: toolCall.name,
          tool_call_id: toolCall.id,
          content: JSON.stringify(toolResult)
        });
 
      } catch (error: any) {
        // Handle normalized 429 Rate Limits passed through by Truto
        if (error.status === 429) {
          const resetTime = error.headers['ratelimit-reset'];
          const waitTimeMs = (parseInt(resetTime, 10) * 1000) - Date.now();
          
          console.warn(`Rate limit hit. Agent sleeping for ${waitTimeMs}ms`);
          // Implementation of sleep/backoff goes here before retrying
        }
 
        // Pass errors back into context so the LLM knows the tool failed
        messages.push({
          role: 'tool',
          name: toolCall.name,
          tool_call_id: toolCall.id,
          content: `Error executing tool: ${error.message}`
        });
      }
    }
  }
}
 
// Run the triage workflow
await runAgent("Find our Business Unit ID for 'acme.com', get the latest private reviews, and draft a reply to any 1-star reviews.");

Moving Fast Without Breaking Trust

Building an AI agent is a straightforward exercise in prompting and state management. Giving that agent reliable access to external systems like Trustpilot is where projects stall. If you decide to build a custom connector, you own the entire API lifecycle. You must write the JSON schemas for the LLM, handle the OAuth token lifecycle, normalize pagination, and manually format the payloads for nested product catalogs.

By leveraging a unified tool layer and a schema-driven approach, you remove the integration bottleneck entirely. Your engineering team can focus on improving the model's reasoning capabilities, while the infrastructure layer handles the operational reality of interacting with third-party APIs.