Retell AI Dynamic Variables Lookup with Google Sheets - n8n Workflow

Retell AI developers seeking to personalize voice agent interactions.
Users needing robust n8n templates for real-time data lookups.
Automation specialists looking to integrate external databases (like Google Sheets) into live APIs.
Anyone building voice applications who requires a reliable, serverless data fetching solution using n8n.

When designing sophisticated conversational AI agents using Retell, context is key. This n8n workflow solves the critical challenge of providing instant, personalized context to the voice agent when a call is received. Instead of handling all logic within Retell, this powerful n8n automation acts as a middleware layer. It intercepts Retell’s inbound call webhook, performs a fast lookup in a designated Google Sheet database using the caller's phone number, and then formats the retrieved information as 'dynamic variables'. By leveraging this n8n node configuration, the Retell agent can immediately utilize variables like first_name or email within its prompts, delivering a seamless and highly personalized conversational experience. This specific n8n workflow demonstrates how easy it is to manage real-time data integration using standard n8n templates.

This automation is initiated by a custom n8n trigger and executes a rapid sequence of actions:

1. Inbound Call Trigger: The n8n workflow starts when the Webhook n8n node receives a POST request from Retell's Inbound Webhook Call feature. This n8n trigger is configured with a specific path (retell-dynamic-variables) and even includes IP whitelisting for enhanced security, ensuring only Retell’s specific IP can initiate the flow.


2. Data Extraction and Lookup: The workflow automatically extracts the caller's phone number (fromnumber) from the webhook payload. This number is passed immediately to the Google Sheets n8n node.


3. Google Sheets Retrieval: The Google Sheets n8n node queries the user database (e.g., Retell sample UserDB). It uses the extracted phone number as the lookup value, matching it against a dedicated 'Phone Number' column in the sheet. This step retrieves the corresponding user row, which includes data like name, email, and custom variables.


4. Dynamic Variable Response: The final Respond to Webhook n8n node takes the data retrieved from Google Sheets and structures it into the exact JSON format that Retell expects for populating dynamic variables. The n8n node maps the sheet columns (e.g., First Name, E-Mail) to the Retell dynamic variables (e.g., firstname, email). This real-time response enables the Retell agent to utilize this personalized information instantly, completing the entire n8n workflow cycle efficiently.

To deploy and utilize this powerful n8n template, follow these steps:

1. Import the n8n Workflow: Copy the provided JSON data and import it directly into your n8n instance using the 'New' menu -> 'Import from JSON' option.


2. Google Sheets Setup: You must create or duplicate the necessary Google Sheet database. Ensure your sheet contains a column named 'Phone Number' and that all numbers are correctly formatted (e.g., starting with '+', no spaces). You must update the Get user in DB by Phone Number n8n node to reference your specific Spreadsheet ID and Sheet Name.


3. Credential Configuration: Provide valid credentials for the Google Sheets n8n node. This typically involves using Google OAuth2 credentials that grant n8n read access to your spreadsheet.


4. Webhook Activation: Activate the Webhook n8n trigger node. Once active, copy the generated Webhook URL (e.g., https://your-instance.app.n8n.cloud/webhook/retell-dynamic-variables).


5. Retell Configuration: Log into your Retell account. Navigate to your Phone Numbers settings, enable 'Add an inbound webhook', and paste the copied n8n Webhook URL. Ensure the connection is configured to use POST method.


6. Variable Mapping: Review the Respond to Webhook n8n node. If your Google Sheet column headers or Retell dynamic variable names differ from the defaults (First Name, E-Mail), you must update the mapping expressions in this n8n node to ensure correct data transfer.

Webhook (n8n trigger):
Function: Serves as the starting n8n trigger, listening for inbound call notifications from Retell AI.
Key Configuration: Configured to accept POST requests on the path /retell-dynamic-variables. Crucially includes an IP Whitelist setting to secure the endpoint specifically for Retell's communication.
Google Sheets (Get user in DB by Phone Number):
Function: Performs a real-time data lookup in a Google Sheets database to retrieve user details based on the caller ID.
Key Configuration: Uses the Read operation and Filter option. The lookup value dynamically pulls the phone number from the inbound webhook payload using the expression ={{ $json.body.callinbound.fromnumber }}.
Respond to Webhook:
Function: Constructs the final JSON response, sending the requested dynamic variables back to the Retell platform, allowing the AI agent to personalize the conversation immediately.
* Key Configuration: Set to respond with json. The response body is a complex expression that maps the retrieved Google Sheets columns (e.g., {{ $json['First Name'] }}) directly into Retell's expected dynamic variable structure (callinbound.dynamicvariables). This is the final step in the n8n workflow.