Connect HeyReach to AI Agents: Scale LinkedIn Networking and Workflows

You want to connect HeyReach to an AI agent so your system can independently source leads, activate LinkedIn campaigns, handle conversational replies, and manage multi-account sender limits. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to write custom integration code from scratch.

Giving a Large Language Model (LLM) read and write access to your HeyReach instance is an engineering challenge. You either spend weeks reading API documentation, handling pagination, and maintaining custom connectors, or you use a managed infrastructure layer that provides agent-ready tools out of the box. If your team uses ChatGPT, check out our guide on connecting HeyReach to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting HeyReach 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 HeyReach, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex LinkedIn networking workflows. For a deeper 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 integration code for HeyReach, decide what layer your agent talks to. This choice determines the reliability of your production system.

Direct API tools - writing one Python function per raw HeyReach endpoint - look convenient in a local prototype. But in production, this pushes provider quirks directly into the LLM's context. The model has to remember exactly how HeyReach structures campaign sequences, how proxy countries are formatted, and that starting a campaign requires specific prerequisite state changes. Every raw API quirk is a hallucination waiting to happen.

Abstracting the HeyReach API behind a tool layer gives you concrete safety wins:

1. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit HeyReach, so a broken tool call fails fast instead of executing partial, unintended actions on a live LinkedIn account.
2. Normalized pagination. Agents struggle with cursors and offset logic. Truto handles the pagination under the hood, allowing the agent to simply call a list method and receive a clean array of leads or conversations.
3. Decoupled authentication. The agent never sees the HeyReach API keys. It uses a single Truto bearer token, drastically reducing the risk of credential leakage in agent logs or outputs.

The Engineering Reality of the HeyReach API

Giving an LLM access to external platforms is rarely as simple as wrapping a fetch request. HeyReach's API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code.

The Campaign State Machine

HeyReach campaigns are not a single-step creation process. They operate on a strict state machine. Standard LLMs are trained to expect that creating a resource makes it immediately active.

In HeyReach, creating a campaign via the API results in a DRAFT status. To activate it, the agent cannot simply update the status to ACTIVE. It must execute a specific sequence of API calls:

1. Create the campaign.
2. Update the sequence (a heavily nested JSON node tree representing the workflow path).
3. Assign at least one connected LinkedIn sender account.
4. Finally, call the specific campaign start endpoint.

If your agent attempts to start a campaign without a sequence or sender, the API will reject it. You must prompt your agent to understand this multi-step orchestration.

Asynchronous Enrichment Jobs

HeyReach provides powerful lead enrichment capabilities, but the API is asynchronous. When you submit a LinkedIn profile for email enrichment, you do not get the enriched data back in the response. You receive a jobId.

Agents are notoriously bad at asynchronous waiting. If you expose the raw API, the LLM will often hallucinate the enriched email address because it expects an immediate return. You must build your agent loop to accept the jobId, sleep or transition state, and explicitly poll the enrichment job status endpoint until it resolves.

Raw HTTP 429 Enforcement

When orchestrating high-volume LinkedIn actions, rate limits are inevitable. Truto does not retry, throttle, or apply backoff on rate limit errors.

When HeyReach returns an HTTP 429 Too Many Requests error, Truto passes that exact error to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. It is entirely up to your agent framework's execution loop to intercept this 429 response, read the ratelimit-reset header, pause execution, and retry. Do not assume the infrastructure will magically absorb these errors.

Fetching HeyReach Tools for Your Agent

Truto maps HeyReach API endpoints to standardized Resources and Methods. These methods - List, Get, Create, Update, Delete, and custom actions - are exposed as Proxy APIs. Truto automatically generates descriptions and JSON schemas for these proxy APIs and serves them via the /tools endpoint.

To fetch these tools, you need a Truto account and an integrated HeyReach account ID.

import { TrutoToolManager } from "@trutohq/langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
 
// Initialize the Tool Manager with your Truto credentials and HeyReach account ID
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY,
  integratedAccountId: "heyreach_account_12345",
});
 
// Fetch the HeyReach tools dynamically
const heyReachTools = await toolManager.getTools();
 
// Bind the tools to your LLM
const llm = new ChatOpenAI({ model: "gpt-4o" });
const agentWithTools = llm.bindTools(heyReachTools);

Because Truto dynamically generates these tools from the integration definition, any updates to the HeyReach API schema are instantly reflected in your agent without you needing to update hardcoded schemas.

HeyReach Hero Tools for AI Agents

Here are the highest-leverage tools you should equip your agent with to manage LinkedIn networking at scale.

Create a HeyReach Campaign

Creates a new HeyReach campaign in a DRAFT status. This is the required first step before an agent can assign sequences or sender accounts.

Contextual usage notes: The agent must understand that the campaign is not active after calling this. It must parse the returned campaignId and pass it to subsequent sequence and assignment tools.

"Initialize a new HeyReach campaign named 'Q3 Enterprise CTO Outreach'. Ensure you save the campaign ID for the next steps."

Update Campaign Sequence

Replaces the workflow sequence of a HeyReach campaign. This requires a specific node tree structure defining delays, conditions, and actions.

Contextual usage notes: The agent must construct a valid JSON tree where every path terminates with an END node. This tool only works on campaigns in DRAFT, SCHEDULED, or PAUSED states.

"Using the campaign ID from the previous step, update the sequence to view the profile, wait 1 day, send a connection request with the note 'Hi {first_name}', and terminate with an END node."

Add LinkedIn Sender Accounts

Assigns one or more connected LinkedIn accounts to act as senders for a specific HeyReach campaign.

Contextual usage notes: The agent should typically query list_all_hey_reach_linkedin_accounts first to find active sender IDs, then pass those IDs to this tool.

"Find all active LinkedIn sender accounts with valid Navigator status, and add them to campaign ID 98765."

Send a Conversation Message

Dispatches a message directly into an existing LinkedIn conversation (chatroom) tracked by HeyReach.

Contextual usage notes: The agent needs the account_id and the conversation id. This tool is critical for building autonomous inbox management agents that read incoming replies and draft context-aware responses.

"Send a reply to conversation ID 55443 on account ID 1122 saying: 'Thanks for getting back to me. How does next Tuesday at 10 AM sound?'"

Create an Enrichment Job

Submits a LinkedIn profile URL for asynchronous email enrichment.

Contextual usage notes: This tool returns a jobId. Your agent loop must explicitly pause and call get_single_hey_reach_enrichment_job_by_id to check the status until the data is returned.

"Submit the LinkedIn profile 'linkedin.com/in/johndoe' for enrichment. Remember the job ID and check back in 15 seconds for the result."

Search Leads by Profile

Fetches deep, real-time data on a specific lead by providing their LinkedIn profile URL.

Contextual usage notes: Returns extensive firmographic and profile data including headline, summary, education, and enriched emails if previously processed. Highly useful for context-gathering before an agent drafts a hyper-personalized message.

"Search HeyReach for the lead 'linkedin.com/in/janedoe' and summarize her current position, company, and about section to help me draft a relevant connection note."

To view the complete inventory of available HeyReach tools, their exact JSON schemas, and return types, visit the HeyReach integration page.

Building Multi-Step Workflows

Equipping your agent with tools is only half the battle. You must construct an execution loop capable of handling multi-step reasoning, tool failures, and strict rate limits.

Because Truto passes HTTP 429 errors back to the caller, a naive agent loop will crash when HeyReach throttles requests. You must intercept tool execution errors, read the standard ratelimit-reset header, and orchestrate a backoff strategy.

flowchart TD
    A["Agent receives prompt<br>and selects tool"] --> B["Execute tool via Truto"]
    B --> C{"HTTP Status?"}
    C -->|200 OK| D["Return JSON to Agent<br>Context"]
    C -->|429 Too Many Requests| E["Read ratelimit-reset<br>header"]
    E --> F["Sleep thread for<br>specified seconds"]
    F --> B
    C -->|400 Bad Request| G["Return error string<br>to Agent Context"]
    G --> H["Agent attempts to fix<br>JSON schema and retry"]

Here is how you structure a resilient tool-calling loop using a framework-agnostic approach:

async function executeAgentLoop(agent, tools, prompt) {
  let messages = [{ role: "user", content: prompt }];
  
  while (true) {
    // Agent predicts the next action
    const response = await agent.invoke(messages);
    messages.push(response);
 
    if (!response.tool_calls || response.tool_calls.length === 0) {
      // Agent is finished, return final output
      return response.content;
    }
 
    for (const call of response.tool_calls) {
      try {
        const tool = tools.find(t => t.name === call.name);
        const result = await tool.invoke(call.args);
        
        messages.push({ 
          role: "tool", 
          tool_call_id: call.id, 
          content: JSON.stringify(result) 
        });
 
      } catch (error) {
        // Handle standard Truto Rate Limit Headers
        if (error.status === 429) {
          const resetTime = error.headers['ratelimit-reset'];
          const sleepSeconds = Math.max(1, resetTime - Math.floor(Date.now() / 1000));
          
          console.log(`Rate limited by HeyReach. Sleeping for ${sleepSeconds}s`);
          await new Promise(resolve => setTimeout(resolve, sleepSeconds * 1000));
          
          // Push failure back to context so agent can retry
          messages.push({
            role: "tool",
            tool_call_id: call.id,
            content: "Error: Rate limited. Please retry the exact same tool call."
          });
        } else {
          // Return standard errors to the agent to self-correct (e.g. invalid JSON)
          messages.push({
            role: "tool",
            tool_call_id: call.id,
            content: `Execution failed: ${error.message}`
          });
        }
      }
    }
  }
}

This loop ensures that your agent can handle the realities of the HeyReach API without crashing, maintaining context across retries.

Workflows in Action

By leveraging the /tools endpoint, you can orchestrate complex LinkedIn operations that would normally require a human SDR or multiple brittle Zapier zaps.

1. Autonomous Lead Sourcing and Campaign Activation

Persona: Sales Development Representative (SDR) Agent

"Find 10 active companies in our target list, locate their CTOs on LinkedIn, enrich their emails, and build a new active HeyReach campaign using our standard 3-step sequence. Assign sender account ID 8899 to the campaign."

Agent Execution Steps:

1. create_a_hey_reach_campaign: The agent initializes a new campaign and stores the resulting campaignId.
2. hey_reach_campaigns_update_sequence: The agent builds the node tree representing the 3-step sequence and applies it to the campaign.
3. create_a_hey_reach_enrichment_job: The agent loops through the provided LinkedIn URLs, submitting them for enrichment and storing the jobIds.
4. get_single_hey_reach_enrichment_job_by_id: The agent polls the jobs until the enriched emails are returned.
5. create_a_hey_reach_campaign_lead: The agent pushes the enriched leads into the campaign.
6. hey_reach_campaigns_add_linkedin_accounts: The agent attaches sender ID 8899 to the campaign.
7. hey_reach_campaigns_start: The agent activates the campaign, transitioning it out of DRAFT.

Result: The user gets a fully active campaign populated with enriched leads and assigned senders, built entirely through conversational prompts.

2. Intelligent Inbox Management

Persona: Revenue Operations (RevOps) Agent

"Check all recent LinkedIn conversations across our sender accounts. If a lead replied with a positive sentiment asking for a meeting, mark the conversation as seen, draft a polite reply suggesting next week, and send it."

Agent Execution Steps:

1. list_all_hey_reach_linkedin_accounts: The agent fetches all active sender IDs in the workspace.
2. list_all_hey_reach_conversations: The agent iterates through the sender accounts, fetching recent unseen conversations.
3. LLM Internal Reasoning: The agent analyzes the lastMessageText of each conversation. It identifies one where the lead asks to chat.
4. hey_reach_conversations_set_seen: The agent marks that specific conversation as seen.
5. hey_reach_conversations_send_message: The agent dispatches a contextual response into the conversation thread.

Result: The system acts as an autonomous inbox manager, ensuring positive replies are handled instantly while ignoring or escalating negative responses.

Strategic Wrap-Up

Connecting AI agents to HeyReach doesn't require building a custom integration layer, normalizing pagination by hand, or writing defensive retry logic for every single endpoint.

By leveraging Truto's /tools endpoint, you provide your agents with clean, deterministic JSON schemas that map directly to HeyReach's underlying capabilities. Your engineering team can focus on improving the agent's reasoning loop and rate limit handling, while Truto manages the authentication lifecycle and schema generation.