Home Controlled Flows | Connect your backoffice
💾

Controlled Flows | Connect your backoffice

The real-time communication agent that connects ClaudIA with your backoffice and much more
Winderlly
Ian Kraskoff
By Winderlly and 5 others
• 13 articles

Turn Your Google Sheets into a Web Service in 5 Minutes!

Replace all UPPERCASE texts with your actual values YOUR_SHEET_ID • YOUR_SHEET_NAME • YOUR_KEY_NAME (e.g., id, phone, cpf…) 1. Overview - Web App exposes your Google Sheets spreadsheet as an HTTP endpoint (GET or POST). - In-memory cache uses an index in a Map for responses in milliseconds. - Key search query by YOUR_KEY_NAME (e.g., id=123) using index + quick fallback. - Rebuild & Incremental You control when to rebuild the index (manual or trigger every 1 min). 2. Script-based (anonymized) /** * Web App – Spreadsheet API * Replace ALL UPPERCASE placeholders with your real data! */ /* ⚙️ CONFIGURATION */ const SHEET_ID = 'YOUR_SHEET_ID'; const SHEET_NAME = 'YOUR_SHEET_NAME'; /* 🗺️ Map only the columns you want to expose (A=1, B=2, …) */ const COL = { key : 1, // YOUR_KEY_NAME (search key) field01 : 2, field02 : 3, field03 : 4 }; const NUM_COLS = Object.keys(COL).length; const TTL_CACHE_MS = 15 * 60 * 1000; // 15 min const CHUNK_ROWS = 8000; // read in blocks /* 🛢️ Cache */ let cache = { map:new Map(), last:0, building:false }; /* 🌐 ENDPOINTS */ function doGet(e){ return handle(e); } function doPost(e){ if (e.postData && e.postData.type === 'application/json') Object.assign(e.parameter, JSON.parse(e.postData.contents||'{}')); return handle(e); } /* 🧠 MAIN LOGIC */ function handle(e){ const id = (e.parameter['YOUR_KEY_NAME'] || '').trim(); if (!id) return out({found:false,error:`Missing 'YOUR_KEY_NAME' parameter`}); try{ if (Date.now() - cache.last > TTL_CACHE_MS) buildIndex(); const hit = cache.map.get(id); if (hit) return out({found:true, ...hit}); const obj = searchSheet(id); return out(obj ? {found:true, ...obj} : {found:false}); }catch(err){ return out({found:false,error:err.toString()}); } } /* 🔍 Direct search (fallback) */ function searchSheet(id){ const sh = SpreadsheetApp.openById(SHEET_ID).getSheetByName(SHEET_NAME); const rng = sh.getRange(1, COL.key, sh.getLastRow(), 1) .createTextFinder(id).matchEntireCell(true).findNext(); if (!rng) return null; const vals = sh.getRange(rng.getRow(), 1, 1, NUM_COLS).getValues()[0]; const obj = rowToObj(vals); cache.map.set(id, obj); // save to cache return obj; } /* 🔄 Build or refresh the full index */ function buildIndex(){ if (cache.building) return; cache.building = true; try{ const sh = SpreadsheetApp.openById(SHEET_ID).getSheetByName(SHEET_NAME); const rows = sh.getLastRow() - 1; const map = new Map(); for (let i=2;i<=rows+1;i+=CHUNK_ROWS){ const end = Math.min(i+CHUNK_ROWS-1,rows+1); sh.getRange(i,1,end-i+1,NUM_COLS).getValues().forEach(r=>{ const id = (r[COL.key-1]||'').toString().trim(); if (id) map.set(id, rowToObj(r)); }); } cache = { map, last:Date.now(), building:false }; }finally{ cache.building=false; } } /* 🧩 Helpers */ function rowToObj(r){ const o={}; for (const k in COL) o[k]=r[COL[k]-1]; return o; } const out = o=>ContentService.createTextOutput(JSON.stringify(o)) .setMimeType(ContentService.MimeType.JSON); /* ⏰ Create incremental trigger (every 1 min) */ function createIncrementalTrigger(){ ScriptApp.newTrigger('buildIndex') .timeBased().everyMinutes(1).create(); } 3. Essential Step-by-Step A. Configure & paste the script 1. Open script.google.com → New Project. 2. Paste the above template. 3. Replace ALL placeholders YOUR_…. B. Build the first index manually 1. In the editor → Run buildIndex() once. 2. This loads all rows into memory (faster for the first request). 💡 Quick tip If you prefer, just call the API with &rebuild=true right after deployment – same effect. C. Create the incremental trigger 1. Once the initial index is built, select the function createIncrementalTrigger from the dropdown menu. 2. Click Run → authorize. 3. A 1-minute trigger will keep the cache synchronized effortlessly. D. Publish and generate the URL 1. Deploy → New deployment → Web app. 2. Execute as: Me • Who has access: Anyone (or anyone with the link). 3. Deploy → Authorize → Copy URL. https://script.google.com/macros/s/YOUR_DEPLOY_ID/exec 4. Quick Tests 5. Common Problems & Solutions 🔒 Quick Security - Web App runs with your credentials → clients only see JSON. - To limit access, change to Only myself and require a token / API Key. Done! 1. Build the first index (buildIndex or rebuild=true). 2. Create the incremental trigger. 3. Publish and use! Any questions, contact us. 😉

Last updated on Aug 22, 2025

Flow Testing in Controlled Flow via API

Controlled Flow's API allows for automatic initiation and continuation of conversations using created flows through HTTP calls. This functionality is ideal for performing automated tests, validating interactions, and ensuring that the flows are working as expected. This guide presents the complete process for using the API. Overview of Integration Communication with Controlled Flow occurs in two main steps: 1. Starting the conversation: creates a new chat session. 2. Continuing the conversation: sends messages within the created session. These calls are made through HTTP endpoints, using an authentication token and the ID of the flow created in Controlled Flow. Step-by-Step Integration 1. Obtain the Flow ID Each flow created in Controlled Flow has a unique identifier (ID) that is used to start the session via API. This ID can be copied directly from the flow's edit URL or the publication screen. 2. Start a New Chat Session Endpoint: POST https://eddieeyes.us-east-1.prd.cloudhumans.io/api/v1/typebots/FLOW_ID/startChat Required Headers: - Content-Type: application/json - Authorization: Bearer {{apiToken}} Expected Response: { "sessionId": "abc123xyz"} This sessionId is essential for the next steps. 3. Send Messages to Continue the Chat Endpoint: POST https://eddieeyes.us-east-1.prd.cloudhumans.io/api/v1/sessions/{{sessionId}}/continueChat Headers: - Content-Type: application/json - Authorization: Bearer {{apiToken}} Body: { "message": "user's message"} Response: a JSON object with the next interaction generated by Controlled Flow based on the flow's logic. How to Generate a Token To authenticate calls via API, you need an API Token. Follow the steps below to generate one: 1. Click on Settings and Members in the upper right corner of the screen. 2. In the side menu, select My Account. 3. In the API tokens section, click on Create to generate a new token. Best Practices for Using the API Storing and Reusing the sessionId Keep the sessionId generated for each conversation. It is necessary to maintain continuity in the interaction with the same context. Testing Before Final Integration Use tools like Postman or Insomnia to validate the endpoints, headers, body, and responses. This helps avoid errors in the production environment. Error Monitoring Failures in calls (such as invalid data, incorrect endpoints, or timeouts) appear on the HUB with error signaling. Use this information for quick diagnosis.

Last updated on Jun 24, 2026

How to Create a Workflow in Controlled Flow Accessing Information in Google Sheets

https://www.loom.com/share/23e057bb1692482c89e9b56e05a49ff0 What is this feature? This integration allows you to connect Controlled Flow to a Google Sheets spreadsheet and create automated workflows based on the data contained within — such as checking order status, balance amounts, schedules, among others. It is especially useful when you update the spreadsheet frequently, whether manually or via automation (e.g., system data dumps). Usage Example Let's use a spreadsheet with two columns: - id: order code - status: current situation (e.g., "in progress", "delivered", "late") Step 1 – Create a new Controlled Flow workflow Create a new flow in Controlled Flow and set the entry point with a text input, so the client can provide the order number. Give the variable a descriptive name, such as order_status. Step 2 – Connect Google Sheets In the Integrations tab, select “Sheets”. - If your account is not yet connected, ask the Cloud Humans team to provide the service email to share your spreadsheet. - Choose the spreadsheet, the correct sheet, and the header row (usually 1). - Use the Get data operation. - Apply a filter, for example "id column" == {{order_status}} Step 3 – Extract desired information Choose the status column as output and store it in a new variable (e.g., response_status). Step 4 – Return a response to the customer Use a text block to format the reply message. Example: “Your order has the following status: {{response_status}}.” To test, just click on View. You can test by entering, for example, ID “234567” and verifying if the response matches the data in the spreadsheet. Step 5 – Set forwarding rules to N2 Use conditional blocks to automatically redirect: - If response_status is “late”, send the conversation to N2 (human support). - Otherwise, continue with standard support. Step 6 – End or transfer support At the end of the flow, use the “Return to Cloud” block and set: - “None” → just ends the flow with the response to the customer - “N2” → indicates that Cláudia should transfer to a human agent Step 7 – Publish and test with real tickets After finishing, click Publish. Only then will the flow be available for real tests with Cláudia, including in the Hub / Playground. Conclusion With this flow: - You automate data retrieval in Google Sheets. - Avoid manual responses and errors. - Scale only when necessary (e.g., delays). - Can be adapted for other uses such as CPF query, scheduling, eligibility, etc.

Last updated on Jun 24, 2026

How the ClaudIA and Controlled Flow Interaction Works

Interaction: Client <=> ClaudIA <=> Controlled Flow Detailed Explanation of the Flow Client sends a message: The client initiates contact by sending a message to ClaudIA. The message can be a simple query, an inquiry about the status of an order, or a more specific question that requires an automated flow. ClaudIA interprets the message Upon receiving the message, ClaudIA, powered by a GPT model, begins processing the content. The model performs a deep linguistic analysis to understand the client's intent, the context of the message, and identify important entities. ClaudIA checks the type of content With the message processed, ClaudIA checks what type of response is necessary: - Content N1: If the message is simple and direct, ClaudIA automatically responds with an answer from the knowledge base. - Content N2: If the question is more complex or requires human assistance, ClaudIA transfers the conversation to the N2 team. - Interactive Content: If the issue involves a more complex inquiry (e.g., checking order status, information via API, or integration with Google Sheets), ClaudIA activates the Controlled Flow. Controlled Flow (Interactive Content) When the content is interactive, ClaudIA triggers the Controlled Flow. This flow may include: - Queries (API, Google Sheets, LLM prompt, tree flows, JavaScript, etc.): The Controlled Flow performs the queries defined in the flow, such as checking the status of an order or retrieving specific data. - Response Generation: The response generated by the Controlled Flow is then sent to the client. Flow Finalization After executing the Controlled Flow, the service can proceed in different ways: - Return to ClaudIA: If the flow was set to return to ClaudIA, she continues the service. "End Flow [N1]". - Escalated to N2: If configured, the conversation is escalated to the N2 team for more in-depth assistance "Forward to Human [N2]".

Last updated on Jun 24, 2026

Troubleshooting and Other Tips

Potential Issues When Using Controlled Flow "Inputs" 1. Buttons Currently, the "Buttons" input does not work in ClaudIA. While tests are successful in the Controlled Flow workspace, this feature is not supported by ClaudIA. In this case, we recommend using a Bubble - Text indicating, in a numbered format, the response options available to the user, followed by a Logic - Condition: 2. Placeholder The "Placeholder" field within "Input" cards allows the Controlled Flow to automatically capture data that the customer has already sent in chat to ClaudIA, without needing to ask again. To do this, simply fill in this field with a description of what data is being collected. When filled, it acts as a prompt for automatic search in the ticket. For example, if you write "User's Email," the Controlled Flow will automatically identify an email in the ticket and assign it to the defined variable. Consequently, the response in the interactive section is not triggered, avoiding duplicate requests for information. Variable Collection 1. Default Variables These are variables that ClaudIA automatically sends to Controlled Flows. All are in string format. Some may be empty (if the information isn't available in the conversation), while others always have a value. - helpdeskId Ticket identifier in your help desk. Used to locate a specific ticket. - cloudChatId Unique code for the conversation in CloudChat. Always present, as it identifies the conversation. - activeIntent Detected intent (topic) in the current conversation. If no intent is identified, the value will be DEFAULT. - channelType Origin channel of the conversation. Possible values: EMAIL WHATSAPP SMS CHAT FORM FACEBOOK INSTAGRAM NO_TYPE_PROVIDED - language (can be null) Detected language of the conversation. Possible values: pt-BR en es fr de it ja ko zh ru ar hi nl sv da fi pl tr - createdAt Date and time when the conversation started. - frustrationScore Customer frustration level, automatically calculated by ClaudIA. 0 indicates no frustration, higher values indicate greater dissatisfaction, based on project settings. - abKey (can be null) Key used in A/B testing. Not all conversations are tested, so it may not exist. - lastUserMessages Last messages sent by the customer since the last agent response. - messages Complete conversation history in text format, structured as: USER: message AGENT: message No additional integration is required for the Controlled Flow to use this information. Simply create a "Condition" card, as shown below: 2. Variable Extractor By default, Controlled Flows are designed to request all necessary information from the customer (such as order number, email, etc.) to fulfill a request. However, this information is often already provided earlier in the conversation. This can cause the Controlled Flow to ask redundant questions, leading to a poor user experience. We developed a variable extractor capable of analyzing the conversation history, collecting the required data, and sending it to the Controlled Flow at activation, thus eliminating the need to ask customers again. Features: - The extractor dynamically checks the Controlled Flow to identify which variables need to be collected. - Extraction is performed by GPT, using a prompt defined within ClaudIA's code. - Collected data can be reviewed in the Hub audit. Configurations: The setup is done within the Controlled Flow. For a variable to be extracted, the following conditions must be met: - There must be an input block with the placeholder filled out, describing the variable (e.g., Order number in the format IN-XXXXXX). - The variable must be preceded by an is set conditional, which checks if it has a value or not. This allows control over the flow depending on whether the variable has already been filled by the extractor. Controlled Flow Activation by ClaudIA 1. How a Controlled Flow Is Triggered A Controlled Flow is triggered by ClaudIA through the "section used" feature, detailed in this article. Step-by-step: 1. User sends a message; 2. ClaudIA analyzes the "responses" of available sections; 3. ClaudIA activates the Controlled Flow for the section with the most appropriate "response" to the customer's message; 4. If ClaudIA selects two Controlled Flow sections, the one with the highest score will be triggered. 2. How to Hide the Interactive Section's "Response" To omit the "response," The Controlled Flow needs access to the first variable collected in the flow. For example, if the "response" contains the text "What is your order number?", ClaudIA will suppress this question if the user has already provided the order number. For this mechanism to work, you must fill in the "Placeholder" field in the variable collection card.

Last updated on Jun 24, 2026

How to Identify and Avoid Failures in Controlled Flows and Requests

To ensure efficient and smooth service, it is essential to understand the main modes of failure that can occur in Controlled Flow's flows and the communication between Controlled Flow and ClaudIA. Identifying and mitigating these failures enhances the customer experience and prevents unwanted interruptions. Timeout and Request Cancellation Communication between ClaudIA and Controlled Flow needs to be quick and efficient to ensure smooth customer service. However, there is a time limit for executing each request within Controlled Flow. If this time is exceeded, the request is automatically canceled, interrupting the flow and preventing the customer from receiving an adequate response. How Does Timeout Work? - When ClaudIA calls a flow from Controlled Flow, the execution of actions within the flow must occur within a time limit of 45 seconds. - This limit exists to ensure that the conversation happens in real time, without noticeable delays for the customer. - If a request takes longer than this period, Controlled Flow cannot complete the action, resulting in the cancellation of the operation and no response for ClaudIA. Main Causes of Timeout and Request Cancellation APIs with High Response Time - When a Controlled Flow makes a call to an external API, the response time can be very long, exceeding the allowed limit. - Some APIs are not optimized for quick queries and may take time to process and return data. - If the API does not respond within 45 seconds, the request will be automatically canceled, harming the user experience. 🔹 How to Avoid: Use APIs that have a fast response time (ideally less than 2-3 seconds). Prioritize asynchronous APIs or those with cached responses to avoid delays. If you need a slow API, consider breaking the request into smaller parts or using intermediate solutions (such as storing temporary data). Retrieval Failure - This can happen due to configuration errors, recent changes in the flow, or failures in data indexing. - To mitigate this issue, it is essential to regularly review and test the contents attached to the flow. Internal Execution Error in Controlled Flow - Controlled Flow may experience internal failures that prevent the correct execution of the flow. - This can occur due to incorrect configurations, poorly structured blocks, or improper use of logical conditions (IF/ELSE). - To minimize this risk, it is recommended to test each flow before publication and review error logs in the Hub if it occurs. Error in Integration Execution - External integrations (such as API calls, Google Sheets) may return error messages or fail completely. - When this happens, Controlled Flow may follow an incorrect path or not respond to the customer. - To mitigate this issue, configure appropriate error handling, such as: - Returning an explanatory message to the customer. - Escalating service to a human agent (N2). 5. Incorrect Execution Flow - In flows that use LLMs (Language Models like GPT) to define the execution route, there may be failures in choosing the next step. - This occurs when the model's interpretation leads to an unexpected path or when the conditions within the flow are not well defined. - To avoid this type of error: - Define clear and well-structured prompts. - Configure conditional responses for different scenarios. - Test variations of the flow to ensure predictability. Total Failure of Controlled Flow - In extreme cases, Controlled Flow may fail completely, preventing the flow from continuing. - To prevent the customer from getting stuck in the conversation, there is a safety feature that automatically escalates the conversation to N2. - This scalability ensures that, even in a scenario of overall failure, customer service is not interrupted.

Last updated on Jun 24, 2026

Monitoring and Continuous Improvement of Flows in Controlled Flows

To ensure that the flows operate correctly, it is essential to monitor the processes of ClaudIA and Controlled Flows. We have a platform called HUB, where all interactions that have gone through ClaudIA are recorded. In the HUB, it is possible to view the services, track flows called by Controlled Flows, and identify opportunities for improvement, ensuring increasingly efficient and well-monitored service. Overview of the HUB: Main screen displaying the conversation history of ClaudIA The HUB functions as a central dashboard that allows auditing, analyzing, and improving customer service. It offers a detailed view of the conversation flow, helping to identify potential bottlenecks and facilitating actions for continuous optimization. Flow Tracking in HUB: Example of a conversation indicating the start of the flow in Controlled Flows and the return signal to ClaudIA at the end of the interaction. HUB Features ✔ Complete record of conversations: All messages exchanged between clients and ClaudIA are stored for analysis and auditing. ✔ Monitoring of Controlled Flows: Whenever ClaudIA triggers a flow from Controlled Flows, the HUB displays a signal with the flow name and the messages exchanged within it, allowing for tracking the customer journey. ✔ Indication of flow end: When a flow is completed, there is a return signal to ClaudIA, allowing understanding of when the service returned to the AI. ✔ Audits for continuous improvement: The HUB allows for strategic adjustments, such as refining N1 and N2 content, creating interactive flows, and identifying failure points that impact customer experience. ✔ Monitoring of errors in Controlled Flow requests: If there is any failure in API calls or integrations within Controlled Flows, the HUB allows for the identification of these failures, enabling quick corrections to avoid impact on service. A high-level block with a log is displayed at the moment of failure to facilitate problem identification. Example of log in Hub: indication of failure in a Controlled Flow request The Hub is an essential tool to ensure efficiency, transparency, and constant evolution of service, providing a strategic view of the interaction between ClaudIA, Controlled Flows, and customers. The following features are available for analysis and optimization: Identification of Controlled Flow Call Moment - In the Hub, it is possible to visualize exactly when a Controlled Flow was called within a conversation. - The start and end of the flow are recorded, allowing for clear tracking of what happened during execution. Suggested Process for Testing and Improving Controlled Flows To ensure the quality and continuous evolution of the flows created in Controlled Flows, it is essential to follow a structured process of testing and improvements. Since Controlled Flows does not have a native version control, best practices include backups, isolated testing, and validation before publication. Building and Modularization - Whenever possible, break complex flows into smaller, reusable parts. - Use calls between flows to facilitate maintenance and avoid rework. - Ensure that all conditions (if/else) are correctly filled to avoid incorrect decisions. Testing Before Publication - Before publishing any changes, duplicate the flow and conduct tests in an isolated environment. - Run complete simulations, checking decision logic, messages sent, and configured integrations. - Validate response times by observing the interval between the client's message and ClaudIA's response in the HUB. This helps identify potential slowdowns in requests, even without an exact detail of the duration. Avoid requests that may exceed the 45-second timeout. Backup and Change Control - As there is no native versioning system, download a copy of the flow before any modification. - Publish only after all changes are validated to avoid unexpected failures. - If a downgrade is necessary, use the saved version to quickly restore the previous flow. Monitoring and Continuous Improvement - Monitor the execution of flows in the HUB, checking which were called and if there were any failures or unexpected deviations. - Analyze logs and error messages to identify optimization points. - If recurring failures occur, adjust the decision conditions and alternative flows to ensure smoother service. This structured process minimizes errors, optimizes Controlled Flows performance, and improves the customer experience, ensuring that each flow works as effectively as possible.

Last updated on Jun 24, 2026

How to open a side conversation in Zendesk via Controlled Flow

What is a side conversation in Zendesk? It is a feature that allows you to open a new communication channel within an existing ticket, usually used to involve other teams or departments. Step-by-step guide to set up in Controlled Flow 1. Add an HTTP Request block At the end of the branch in the flow where you want to open the side conversation, add a block of type "HTTP Request". 2. Configure the method - Method: POST 3. Configure the URL https://youraccount.zendesk.com/api/v2/tickets/{{helpdeskId}}/side_conversations - Replace youraccount.zendesk.com with your Zendesk URL. - Replace {{helpdeskId}} with the variable for the ticket ID (it can be collected from the flow by ClaudIA) 4. Headers Add the following headers: { "Authorization": "Bearer YOUR_TOKEN_HERE", "Content-Type": "application/json" } Replace YOUR_TOKEN_HERE with your Zendesk API token (converted to base64). 5. Body (request body) Use the following content in JSON format: { "message": { "subject": "Title", "body": "body", "to": [ { "support_group_id": GROUP_ID } ] } } - Title: title of the conversation. - body: message to be sent. - GROUP_ID: ID of the support group that will receive the conversation. You can use Controlled Flow variables like {{name}}, {{message}}, etc., to personalize. Example with Controlled Flow variables: { "message": { "subject": "New request from {{name}}", "body": "Customer {{name}} has made a new request with the following details: {{details}}", "to": [ { "support_group_id": 123456 } ] } } Where to add it? Add this HTTP block in the branch of the flow where you want the side conversation to be created in Zendesk. Example flow with opening of side conversation using Zendesk API

Last updated on Jun 24, 2026

Collaborative Editing on Controlled Flows

🔄 How does collaborative editing work on Controlled Flows? Controlled Flows use a queue system to manage multiple users within the same flow. - Only one user at a time can edit (Editor mode) - Others remain in Read-Only mode, watching in real-time. When the current editor leaves or is removed due to inactivity, the next user in line automatically takes over editing. 👥 Who can edit a flow? The order is determined by arrival: 1. The first user who opens the flow becomes the Editor 2. The others automatically join the waiting queue 3. When the current editor leaves, the next in line gains editing control 🖥️ What are the access modes? - Edit Mode → you can drag blocks, change settings, and publish changes normally - Read-Only Mode → you can view and even test the flow, but cannot edit 🔎 How do I know which mode I am in? The interface displays clear indicators: - Edit Mode → shows a sidebar with available blocks and the Publish: button: - - Read-Only Mode → displays a "READ-ONLY" warning at the top: - - The connected users icon (👥) shows how many people are accessing the flow; hovering over it reveals: - The current Editor (bold) - The other users in view-only mode - - ⏳ What happens if I become inactive? To prevent locks: - Controlled Flows monitor your activity - If you are ~10 minutes inactive, you lose your editing position - The next user in the queue takes over as Editor 🔄 How do I pass the turn to another user? To release editing: 1. Save your changes 2. Exit the flow 3. The next user in line automatically gains editing access 📑 Can I duplicate a flow to edit separately? Yes. If you don't want to wait in line to test a change, you can click Duplicate and create your own editable copy. 💾 Are my changes lost when someone else takes over? Only if you are inactive after 10 minutes and haven't published your changes.

Last updated on Jun 24, 2026