Connect Unipile to AI Agents: Automate outreach and LinkedIn search

You want to connect Unipile to an AI agent so your system can autonomously search LinkedIn, qualify leads, send multi-channel outreach, and manage email campaigns. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build a custom integration from scratch.

Giving a Large Language Model (LLM) read and write access to a multi-channel messaging platform like Unipile is an engineering challenge. You either spend months writing the integration code, managing stateful authentication flows, and normalizing API schemas, or you use a managed infrastructure layer to handle the boilerplate. If your team uses ChatGPT, check out our guide on connecting Unipile to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Unipile 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 Unipile, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex outreach workflows. For a broader look at this design pattern, read our guide on Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck.

The Engineering Reality of the Unipile API

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 an @tool decorator. In production against complex messaging and recruiting systems, this approach collapses.

Unipile unifies LinkedIn, WhatsApp, Email, and Instagram into a single API. While that is incredibly powerful, it introduces severe architectural constraints. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

The Checkpoint Authentication Trap

Unlike standard SaaS applications that rely on a simple OAuth 2.0 flow, Unipile connects to platforms that aggressively combat automation. Linking a LinkedIn or WhatsApp account is not a single API call. It is a stateful machine.

You initiate an intent. The provider responds with a challenge. You must then solve a checkpoint - which might be entering a 2FA code sent via SMS, or scanning a QR code with a mobile device. If your AI agent assumes authentication is a simple bearer token exchange, it will fail immediately. Your system must be designed to either handle account linking outside of the agent's context, or explicitly provide the agent with checkpoint-solving tools (create_a_unipile_auth_checkpoint) so it can prompt the user for the required verification code mid-execution.

Binary Payload Traps

Standard LLMs are trained to consume and output JSON. The Unipile API frequently returns raw binary data for specific endpoints.

If your agent calls get_single_unipile_chat_picture_by_id or unipile_talent_pool_applicants_get_resume, the API does not return a JSON object with a URL. It returns the raw binary file itself. If you pass this binary stream directly back to a text-based LLM, the context window will shatter. Your tool layer must intercept binary responses, stream them to a bucket, and return a signed URL to the LLM instead of raw bytes.

Provider-Specific Feature Drift

Because Unipile aggregates multiple platforms, the capabilities of a single endpoint change based on the underlying provider.

For example, if your agent tries to add a reaction to a post using create_a_unipile_post_reaction, the allowed enum values shift entirely based on the channel. LinkedIn requires specific strings like linkedin_like or linkedin_celebrate. Instagram requires a different format. If the LLM invents an emoji unicode that the specific provider does not support, the call fails. You need a strict tool schema that enforces provider-specific validation before the request leaves your infrastructure.

Why a Unified Tool Layer Matters for Agent Safety

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

Direct API tools (one tool per raw Unipile endpoint) look convenient, but they push all the provider quirks mentioned above into the LLM's context. Every quirk is a hallucination waiting to happen.

Truto sits between your agent and Unipile. Every integration on Truto is a comprehensive JSON object representing the underlying product's API. Truto maps these APIs into a REST-based CRUD concept called Resources.

We provide a set of tools for your LLM frameworks by offering descriptions and schemas for all the Methods defined on these Resources. By calling the GET /integrated-account/<id>/tools endpoint, Truto returns Proxy APIs with strict JSON schemas. The agent never sees the underlying vendor complexity.

This gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM chooses from stable function names. Invalid arguments are rejected by the schema before they hit Unipile, so a broken tool call fails fast.
2. Customizable prompts. Truto allows you to edit the tool descriptions directly in our UI. If the LLM keeps messing up a search query parameter, you can edit the description in Truto, and the updated prompt instructions sync to your agent in real-time.

Fetching Unipile Tools via Truto

To make Unipile actionable for an LLM, you need to extract its capabilities into standard OpenAI tool schemas.

Instead of writing these schemas by hand, you connect a Unipile account in the Truto interface, grab the Integrated Account ID, and call the Tools endpoint.

import { TrutoToolManager } from "@trutohq/langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
 
// 1. Initialize the tool manager with your Truto credentials and the linked Unipile account ID
const toolManager = new TrutoToolManager({
  apiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "unipile_account_xyz789"
});
 
// 2. Fetch all available Unipile tools
const unipileTools = await toolManager.getTools();
 
// 3. Bind the tools directly to your LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
}).bindTools(unipileTools);
 
// The LLM is now aware of all Unipile capabilities and their exact JSON schemas.

Unipile Hero Tools for AI Agents

When building an autonomous outreach agent, you don't need all 100+ Unipile endpoints. You need high-leverage primitives. Here are the core hero tools exposed via Truto that enable complex messaging and recruiting workflows.

1. list_all_unipile_search_search_people

This tool allows the agent to execute LinkedIn people searches using keywords, locations, and network filters. It is the foundation of any automated sourcing pipeline.

Usage Note: The agent must be instructed to handle pagination if the search criteria is broad. Ensure the prompt explicitly tells the agent to extract the id from the results, as this identifier is required for subsequent connection requests.

"Find software engineers located in San Francisco who have experience with Node.js. Return their profile URLs and extract their internal IDs so we can send connection requests."

2. create_a_unipile_users_relation_request

This tool allows the agent to send a connection request to a specific user, optionally including a personalized message.

Usage Note: LinkedIn enforces strict daily limits on connection requests. The agent must provide the user_id and the account_id. Requests sent to an existing connection will fail, so the agent should verify relation status first if possible.

"Using the user ID you found in the previous search, send a connection request to them. Include a short, professional message mentioning our open backend engineering role."

3. create_a_unipile_chats_send

This tool is used to initiate a new 1-to-1 or group chat by sending the first message. It is the primary tool for initiating direct outreach once a connection is established.

Usage Note: Use this tool only for new conversations. If a chat already exists with the target user, the agent should be instructed to use create_a_unipile_messages_send instead.

"Start a new chat with the candidate we just connected with. Send them a brief message introducing our engineering team and asking for a 15-minute introductory call."

4. unipile_posts_list_comments

Social selling and recruiting often require engaging with a prospect's content. This tool retrieves all comments on a specific post, allowing the agent to read the room before engaging.

Usage Note: The agent needs the post_id to use this tool. You will typically chain this after using a post-search tool. It returns author details, text, and attachment metadata.

"Read the comments on the recent post about API architecture published by the prospect. Summarize the general sentiment and identify if the author has replied to any questions."

5. list_all_unipile_salesnav_search_companies

For account-based marketing (ABM) and B2B sales workflows, this tool leverages LinkedIn Sales Navigator filters to find target companies based on headcount, industry, and location.

Usage Note: This endpoint requires the underlying Unipile account to have an active Sales Navigator seat. If it does not, the API will reject the call.

"Search for B2B SaaS companies in the FinTech sector with a headcount between 50 and 200 employees located in New York. Return the top 10 companies."

6. create_a_unipile_emails_send

Unipile isn't just for LinkedIn. This tool allows the agent to send emails directly from the linked account's mailbox, enabling multi-channel sequencing.

Usage Note: To track open rates and clicks, the agent must generate and pass an html body payload rather than just plaintext. Attachments must be base64 encoded.

"Draft and send a follow-up email to the prospect. Format the email body using HTML, and ensure the tone is casual but professional. Reference our previous LinkedIn message."

For the complete inventory of Unipile tools, including inbox management, calendar syncing, and Recruiter-specific endpoints, visit the Unipile integration page.

Workflows in Action

When you provide an LLM with these tools, you transform it from a chatbot into an autonomous worker. Here is how specific personas use these tools in real-world environments.

The Autonomous SDR

A sales development representative (SDR) agent is responsible for identifying accounts, finding key stakeholders, and executing initial outreach across multiple channels.

"We need to target mid-market logistics companies. Find 5 companies fitting this profile, identify their VP of Supply Chain, send a LinkedIn connection request, and follow up via email if we have their contact data."

Step-by-Step Execution:

1. The agent calls list_all_unipile_salesnav_search_companies with industry filters set to logistics and appropriate headcount parameters.
2. For the returned companies, it calls list_all_unipile_search_search_people targeting the job title "VP of Supply Chain".
3. The agent calls create_a_unipile_users_relation_request to send a connection request to the identified VPs.
4. If an email address is available on the profile, the agent drafts a message and calls create_a_unipile_emails_send to dispatch an introductory email.

Result: The user gets a fully sourced pipeline with multi-channel touches initiated autonomously, logging all activities without manual intervention.

The Technical Sourcing Recruiter

A recruiting agent is tasked with finding passive engineering talent, analyzing their profiles, and initiating conversations based on specific skill requirements.

"Find 3 senior machine learning engineers based in London who have recently posted about RAG architectures. Send them a direct message asking if they are open to a quick chat about a new AI startup."

Step-by-Step Execution:

1. The agent calls list_all_unipile_search_search_posts (a related search tool) to find recent posts mentioning "RAG" and "machine learning".
2. It extracts the author IDs and calls get_single_unipile_user_by_id to verify their location and job title.
3. The agent calls create_a_unipile_chats_send to initiate a direct message with the qualified engineers, dynamically referencing their recent post in the outreach copy.

Result: The recruiter bypasses the manual process of scrolling feeds and sending cold InMails, letting the agent handle the top-of-funnel sourcing and personalization.

Building Multi-Step Workflows

To execute these complex scenarios, your agent framework needs a stable execution loop. The agent must evaluate the prompt, decide which tool to call, parse the Unipile response, and determine the next action.

This pattern works across any modern framework, including LangGraph, CrewAI, or the Vercel AI SDK.

sequenceDiagram
    participant User
    participant Agent as Agent (LangGraph/CrewAI)
    participant Truto as Truto Tool Manager
    participant Upstream as Upstream API (Unipile)

    User->>Agent: "Find engineers and send connection requests"
    Agent->>Agent: Determine required tool<br>(Search People)
    Agent->>Truto: Call list_all_unipile_search_search_people
    Truto->>Upstream: Proxy GET /search/people
    Upstream-->>Truto: Return JSON profiles
    Truto-->>Agent: Return schema-validated data
    Agent->>Agent: Extract user IDs
    Agent->>Truto: Call create_a_unipile_users_relation_request
    Truto->>Upstream: Proxy POST /relations
    Upstream-->>Truto: Confirm request sent
    Truto-->>Agent: Return success status
    Agent-->>User: "I have sourced 5 engineers and sent requests."

The Reality of API Rate Limits

When your agent is running in a loop, it is incredibly easy to trigger rate limits on the upstream provider. LinkedIn and other messaging platforms enforce strict velocity controls to prevent spam.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. If Unipile or the underlying provider returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to your agent.

However, Truto normalizes the upstream rate limit information into standardized IETF headers:

• ratelimit-limit: The total requests allowed in the window.
• ratelimit-remaining: The number of requests remaining.
• ratelimit-reset: The time at which the limit resets.

Your agent's tool-execution logic must intercept 429s, read the ratelimit-reset header, and halt the agent loop until the window clears.

// Example: Custom tool executor wrapping Truto calls
async function executeToolWithBackoff(toolCall, args) {
  try {
    return await toolCall(args);
  } catch (error) {
    if (error.status === 429) {
      // Read the normalized headers provided by Truto
      const resetTime = error.headers.get('ratelimit-reset');
      const delayMs = new Date(resetTime).getTime() - Date.now();
      
      console.warn(`Rate limit hit. Pausing agent for ${delayMs}ms`);
      await new Promise(resolve => setTimeout(resolve, delayMs));
      
      // Retry after backoff
      return await toolCall(args);
    }
    throw error;
  }
}

By handling the normalized headers, you prevent your agent from crash-looping and burning tokens on failed retries.

Moving from Script to System

Connecting Unipile to an AI agent allows you to automate the most tedious parts of B2B outreach, recruiting, and social selling. But doing it safely requires isolating the LLM from the chaos of multi-provider APIs, binary payloads, and checkpoint authentication.

By using Truto's /tools endpoint, you give your agent a unified, schema-validated interface. The model stops hallucinating query parameters, and your engineering team stops writing point-to-point integration code for every messaging channel.