Connect Wiwink to AI Agents: Handle Forms, Leads & Customer Data

You want to connect Wiwink to AI agents so your system can independently handle lead forms, route field installers, manage digital signatures, and sync customer data directly from a chat interface or background worker. If your team uses ChatGPT, check out our guide on connecting Wiwink to ChatGPT, or if you are building in the Anthropic ecosystem, read our guide on connecting Wiwink to Claude. For engineering teams building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

Giving a Large Language Model (LLM) read and write access to your Wiwink instance is a significant engineering challenge. You either spend weeks building, hosting, and maintaining custom API wrappers, or you use a managed infrastructure layer that handles the boilerplate for you. This guide breaks down exactly how to fetch AI-ready tools for Wiwink using Truto's /tools endpoint, bind them natively to an LLM using frameworks like LangChain, LangGraph, or the Vercel AI SDK, and execute complex operations securely. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Wiwink Connectors

Building AI agents is straightforward. Connecting them to external SaaS APIs safely is hard. A custom integration layer is essentially a translation service that converts an LLM's tool calls into standard REST API requests. While modern models are excellent at generating JSON payloads, implementing those payloads against vendor APIs is highly error-prone.

If you decide to build a custom integration for Wiwink, you own the entire API lifecycle. You must write and maintain massive JSON schemas for every endpoint you want the LLM to access. You also have to handle specific API quirks that break naive agent implementations.

The Sideloading Array Syntax

Wiwink relies heavily on sideloading to reduce API round-trips. When you query a country, you can request its related states. When you query a work order, you can request its assigned installers. However, Wiwink expects this sideloading request to be formatted as an array parameter in the query string, specifically using the with [] syntax.

LLMs consistently fail at this. When instructed to "include states", an LLM will typically generate a nested JSON object or pass a generic include=states query parameter. If you hand-code your tools, you must write complex pre-processing logic to intercept the LLM's JSON output and convert it into the specific ?with []=states&with []=installers URL-encoded format Wiwink requires. Truto handles this translation natively at the proxy level.

Strict Entity Hierarchies

Wiwink enforces a rigid separation between different lifecycle stages of a relationship. A Form cannot exist in a vacuum - it must be explicitly linked to an existing contact_id. A Proposal cannot be generated without a customer_id. An AI agent must understand this relational hierarchy.

If a user asks an agent to "Create a new proposal for Acme Corp", the agent cannot simply hit a /proposals endpoint. It must first query the customers endpoint to find Acme Corp's customer_id, and then inject that ID into the proposal payload. Truto's tool descriptions automatically provide the necessary relational context to the LLM, instructing it on exactly which prerequisite tools to call.

The Signature State Machine

Digital signatures in Wiwink are not standard CRUD objects; they operate on a strict state machine. You cannot simply "create and send" a signature in one API call. The sequence is rigid:

1. Create the signature shell.
2. Create and attach a signer using the signature's ID.
3. Upload the physical document.
4. Trigger the send event.

If an LLM attempts to trigger a send event before the document is uploaded, the Wiwink API will reject it. Furthermore, you cannot delete a signature arbitrarily - you can only cancel a signature, and only if it has been sent but not yet completed. Teaching an LLM this specific state machine through generic prompts is nearly impossible. Truto exposes these distinct actions as isolated, well-described tools, mapping the state machine constraints directly into the tool schemas.

Hero Tools for Wiwink Workflows

To build highly capable agents, you do not need to expose every single endpoint. You need to provide high-leverage tools that allow the agent to execute core business logic. Here are the hero tools you can provision for Wiwink.

List All Forms

This tool allows the agent to retrieve inbound lead forms and customer inquiries. It supports field-level filtering by contact, source, or office, making it critical for routing and triage workflows.

Contextual Usage Notes: Agents use this tool to monitor inbound pipelines. By combining this with the contacts tools, an agent can automatically enrich a newly submitted form with historical context before alerting a sales rep.

"Find all new forms submitted today from the 'Web Webinar' source and summarize the body of the requests."

Create a Customer

This tool transitions a contact into a formal customer record. It is the prerequisite step for generating proposals, issuing works, and managing billing profiles.

Contextual Usage Notes: The agent must provide a corporate_name. Because of Wiwink's hierarchy, agents will often use the output of this tool (the new id) as the input for subsequent tools like proposal generation.

"Convert the contact John Doe at Omni Consumer Products into a formal customer record in Wiwink."

Create a Proposal

This tool initiates the sales cycle by generating a formal proposal attached to a specific customer.

Contextual Usage Notes: This is a multi-step operation for the agent. It must first call this tool to generate the proposal shell (requiring customer_id), and then use the create_a_wiwink_proposal_product tool to add line items.

"Draft a new proposal for customer ID 8492. Once created, add a standard consulting retainer product to it for 5000."

List All Works

This tool exposes operational tasks and fulfillment jobs. It is heavily utilized by agents managing field service, installation dispatch, or project delivery.

Contextual Usage Notes: This tool showcases the power of sideloading. Agents can pass relationship tags to pull in assigned installers, customer details, and work statuses in a single efficient request.

"Pull up all active works assigned to the West Coast region, and make sure to include the assigned installer details for each job."

Create a Signature

This tool initiates the digital signature workflow for contracts, proposals, or compliance documents.

Contextual Usage Notes: The agent must understand that this tool only creates the empty signature envelope. It must immediately follow up with calls to add signers and upload the actual document before triggering the final send action.

"Start a new signature workflow for the MSA with Initech. The sender should be legal@ourcompany.com."

Create a Certification

This tool allows the agent to upload raw PDF documents for official certification and time-stamping within the Wiwink system.

Contextual Usage Notes: This tool handles binary data. The agent must format the payload correctly to pass the RAW_BODY content to the certification endpoint.

"Take this finalized PDF contract and submit it to the Wiwink certification endpoint for official stamping."

For a complete list of all available Wiwink tools, including product inventory management, installer assignment, and detailed parameter schemas, visit the Wiwink integration page.

Building Multi-Step Workflows

To make this functional, you need to connect your LLM framework to Truto's /tools endpoint. Truto provides proxy APIs that normalize authentication and pagination, acting as the first level of abstraction over the underlying Wiwink API.

By using an SDK like truto-langchainjs-toolset, you can dynamically fetch these proxy endpoints as fully typed tools and bind them to your agent.

Factual Note on Rate Limits

When your agent executes loops, it will eventually hit Wiwink's rate limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Wiwink API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to your caller.

However, Truto does normalize the upstream rate limit information into standardized HTTP headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) according to the IETF specification. The caller is entirely responsible for implementing retry and backoff logic. Your agent execution loop must catch the 429, read the ratelimit-reset header, pause execution, and retry the tool call.

Implementation Example (LangChain)

Here is how you initialize the tools, bind them to an Anthropic or OpenAI model, and implement a robust execution loop that respects rate limits.

import { ChatAnthropic } from "@langchain/anthropic";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function runWiwinkAgent() {
  // 1. Initialize the LLM
  const llm = new ChatAnthropic({
    modelName: "claude-3-5-sonnet-latest",
    temperature: 0,
  });
 
  // 2. Fetch tools from Truto's /tools endpoint for the specific Wiwink account
  const truto = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY
  });
  
  const tools = await truto.getTools(process.env.WIWINK_INTEGRATED_ACCOUNT_ID);
 
  // 3. Create the prompt instruction
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an operations agent connected to Wiwink. You must handle relational dependencies (e.g., look up a customer before creating a proposal). If a tool fails, analyze the error and adjust your parameters."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 4. Bind tools and create the agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });
 
  // 5. Execute with application-level rate limit handling
  const executeWithRetry = async (input: string, retries = 3) => {
    try {
      return await executor.invoke({ input });
    } catch (error: any) {
      if (error.status === 429 && retries > 0) {
        // Read Truto's normalized IETF headers
        const resetTime = error.headers['ratelimit-reset'];
        const waitMs = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : 2000;
        
        console.log(`Rate limited by Wiwink. Retrying in ${waitMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 1000)));
        return executeWithRetry(input, retries - 1);
      }
      throw error;
    }
  };
 
  const result = await executeWithRetry(
    "Find the customer 'Global Dynamics'. If they exist, create a new proposal for them."
  );
  console.log(result.output);
}

The Agent Execution Flow

When the agent receives a complex request, it doesn't just guess. It engages in a deterministic observation-and-action loop, using the schemas provided by Truto to navigate Wiwink's data model.

sequenceDiagram
    participant User as User Prompt
    participant Agent as LLM Agent
    participant Truto as Truto Proxy API
    participant Wiwink as Wiwink API
    
    User->>Agent: "Generate a contract for existing customer ID 104..."
    
    Note over Agent: Step 1: Create Signature Shell
    Agent->>Truto: Call create_a_wiwink_signature
    Truto->>Wiwink: Forward Request
    Wiwink-->>Truto: Returns signature_id (e.g., sig_881)
    Truto-->>Agent: JSON Response (sig_881)
    
    Note over Agent: Step 2: Add Signer
    Agent->>Truto: Call create_a_wiwink_signer(signature_id: sig_881)
    Truto->>Wiwink: Forward Request
    Wiwink-->>Truto: 200 OK
    Truto-->>Agent: JSON Response
    
    Note over Agent: Step 3: Trigger Send
    Agent->>Truto: Call create_a_wiwink_signature_send(signature_id: sig_881)
    Truto->>Wiwink: Forward Request
    Wiwink-->>Truto: 200 OK
    Truto-->>Agent: JSON Response
    
    Agent-->>User: "The contract has been configured and sent."

Workflows in Action

Exposing Wiwink endpoints to an agent moves your operations from reactive data-entry to proactive automation. Here is how specific personas use these capabilities in production.

1. The Sales Operations Triage

Sales operations teams spend hours manually converting inbound forms into qualified leads and assigning them to reps. An agent can automate this entirely.

"Review all forms submitted in the last 24 hours. For any form containing the word 'Enterprise' in the body, check if a contact already exists. If not, create a new contact, then upgrade them to a customer record."

Execution Steps:

1. The agent calls list_all_wiwink_forms with a date filter to retrieve recent submissions.
2. It parses the returned JSON, filtering for the keyword "Enterprise".
3. It extracts the email addresses and calls list_all_wiwink_contacts to check for existing records.
4. For missing records, it calls create_a_wiwink_contact.
5. It immediately passes the new contact IDs into create_a_wiwink_customer to formally register them in the CRM layer.

The Outcome: The sales team logs in to find their enterprise pipeline fully populated with structured customer records, bypassing the manual data entry phase completely.

2. Field Installation Dispatcher

Operations managers must constantly balance work orders with available field installers. An agent can monitor the system and handle assignments autonomously.

"Find all works currently marked with the 'Pending Assignment' status. Assign installer ID 402 to the first three works on the list."

Execution Steps:

1. The agent calls list_all_wiwink_works_statuses to find the internal ID for "Pending Assignment".
2. It calls list_all_wiwink_works, passing the status ID to filter the queue.
3. It loops through the first three results, extracting their id values.
4. It calls create_a_wiwink_work_installer three separate times, passing the work_id and the designated installer ID.

The Outcome: Field technicians receive their schedules instantly without a dispatcher needing to click through dozens of individual work order screens.

3. Contract Compliance & Enforcement

Legal and administrative teams need to ensure signatures are completed in a timely manner and cancel stalled agreements before terms change.

"Find any signatures that were sent more than 30 days ago but have not been completed. Cancel them immediately."

Execution Steps:

1. The agent calls list_all_wiwink_signatures, applying a filter for records where completed_at is null and sent_at is older than 30 days.
2. It processes the list of stale signatures.
3. It calls create_a_wiwink_signature_cancellation for each target ID, respecting Wiwink's strict state machine rules (only cancelling sent, incomplete signatures).

The Outcome: The company maintains tight control over outstanding legal liabilities, automatically revoking expired offers without human oversight.

Moving Beyond Brittle Wrappers

Building an AI agent that can reliably operate a platform like Wiwink requires more than writing a few fetch requests. You must account for strict entity hierarchies, complex array parameters for sideloading, and rigid state machines like the signature lifecycle.

By leveraging Truto's proxy architecture and the /tools endpoint, you offload the authentication, schema definition, and parameter normalization entirely. This allows your engineering team to focus on writing better agent logic and application-level retry mechanisms, rather than constantly patching broken API wrappers.