Overview
Voiceflow’s Airtable integration reads and changes records in an authorized base. Use it to retrieve approved business information, record a confirmed support request or update the intended existing record. Start with the built-in actions; they do not need an API tool or separately copied Airtable token.
- Connect Airtable and verify the intended base/table.
- Find records with bounded field/filter choices or a known record ID.
- Record a request and retain the returned Airtable record ID.
- Change an existing record, preserving its identity and checking the saved effect.
Runtime actions query Airtable when called. Importing content into Voiceflow Knowledge is a separate data-source workflow; this account connection alone does not establish ingestion or refresh.
Connecting Airtable
Authorize the intended project account and prepare controlled actions.
Use a project you can edit and a provider account approved for the selected data. OAuth authorizes the connected account; it does not authenticate the customer chatting with the agent. Connections belong to the project, so changing environmentAlias does not independently isolate a provider account. Use a dedicated test project when testing a different account.
Authorize and discover actions
Studio
Authorize the account
In Agent studio, select a dedicated test project. Open More → Integrations → Airtable → Connect, complete browser authorization and return to the intended account. Grant the target base; have the base owner confirm read access and the record-write access needed by the chosen actions.
Add the first read
Open Agent → Global tools → + → Airtable and select List records. Set its Trigger to the approved lookup job and provide the fixed resource inputs. Keep protected customer identity supplied by your authenticated application.
Test the intended data
Use the action’s Run panel with explicit test values and compare the current result with the target base/file. Then run a conversation that needs the result. A Connected badge does not prove data access.
Code
Browser OAuth is required here too. Open Agent studio, select the project matching PROJECT_ID, then More → Integrations → Airtable → Connect. Authorize the intended account and return before running the commands. The generic integration-connect API does not replace OAuth.
Set VF_TOKEN, PROJECT_ID and ENVIRONMENT for a project/test Environment you can access. Use a Voiceflow bearer credential with integration-read/execute permission and agent/tool/compile permission when attaching an action. Keep it on your backend. Discover the actual catalog before execution:
The schema supplies each toolName, inputs and integrationToolID when already added. A stored credential flag does not verify provider acceptance. Standalone execution uses the selected Environment’s saved Draft and the project’s Draft integration slot, with fallback to its Published slot.
Use actions in a customer conversation
For a read, attach the catalog action to Global tools or its owning Playbook and set Trigger to the concrete lookup. Use only the current returned data; no matches should ask for an appropriate next step without claiming that the customer has no account.
For writes involving customer text or a protected record, have the application developer validate the confirmed values and authorize identity on the backend. The input builders reject brace-shaped tokens and validate the example fields. JSON quoting and backslashes do not escape native variable/Secret binding. A Trigger is selection guidance, not an enforced confirmation or authorization gate.
In More → Variables, create these variables with empty defaults before binding them:
For another action, create each additional provided input variable before use and define its exact expected saved fields. The backend supplies the confirmed values; the Workflow owns result/readback/outcome variables. The developer supplies those values on every trusted interaction, sets approval to yes only for that server-recorded confirmed request, and clears it on other turns. Keep runtime credentials/session keys server-side and discard browser identity, state and variable overrides.
Build a Workflow with this sequence:
- Clear
data_action_idand setdata_action_outcometonot_runusing Set at entry. - Add a Condition requiring
data_write_approvedisyes. Its Else path returns to confirmation without executing the action. - On the approved path, clear
data_write_approvedbefore the write, then use an Integration step with every input provided from the corresponding confirmed variable or approved resource value. - Capture the current action’s ID/range using the paths below. Follow it with a Condition checking
data_action_idis not empty, then the saved-field/readback check for that capability. Integration steps have no separate Failure path. - Attach this Workflow to the agent for the customer job and keep the raw write action off Global/Playbook tools. Add both
data_action_outcomeanddata_action_idas actual variable references in the agent’s instructions. Onlydata_action_outcomeisverifiedplus the current result may produce a success answer; an ID retained after failed readback is insufficient.
Test a request with missing details, a confirmed request and a rejected action. Inspect the actual selected Workflow, provided inputs, current result and provider record; only the confirmed, verified action may be acknowledged.
Studio
Use the native Workflows, Set, Condition and Integration controls above. Create each provided variable before selecting it in an input’s Default value. Ask the developer to supply the validated values and recorded approval; a model-generated yes does not meet that prerequisite.
Code
For Code, create variables with POST /v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT and body {"name":"data_write_approved","defaultValue":null,"color":"#515A63"}; repeat for the result and each provided input. Use the same bearer header. Add the selected catalog action with POST /v1/stable/integration/airtable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT and body {"toolName":"airtable_create_records"}, retaining integrationToolID.
Download the guarded Workflow builder and airtable-workflow.config.json into the same directory. Add the readback action airtable_get_record through the same catalog-tool API. In the configuration file, replace every RETURNED_... value with its returned resource ID and replace the example base/file with the owner’s resource. The source comments and keys identify the required approval, result, outcome and readback variable IDs; keep their names as created above. The expected values for all five fields and prepared array must be populated by your backend before the approved turn. Run:
Create workflow.json with the API below. The example compares all five submitted fields with the backend’s expected values; a current ID/range alone cannot pass verification. To configure another action, change its selected tool ID, exact inputs, capture path and complete readback checks; do not reuse append/create semantics for a different write. It produces the reset → approval → action → result-check graph above. Create that graph using POST /v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT with the bearer header. Attach its returned workflow.id using POST /v2/stable/tool with body {"type":"workflow","workflowID":"RETURNED_WORKFLOW_ID","target":{"global":true},"description":"Run the confirmed data request and acknowledge only its current verified result."} and the same project/Environment query.
Expose the Workflow outcome in the caller’s instructions before compiling. Read the current text with GET /v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&includeInstructions=true and the same bearer header. Preserve agent.instructions; null starts with empty text, while an absent field requires another successful read. Append the following rule as actual variable references, then PATCH only instructions through /v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT with the same bearer header. includeInstructions belongs only on the GET:
Replace the preservation marker with the actual existing text using a JSON serializer; do not erase the agent’s other instructions or routing. Resolve unresolvedReferences after the PATCH. A Workflow tool returns its component name, so a static Trigger or attachment description does not expose these outcome values. Test a successful write followed by a failed readback: the new ID must not override unverified.
Resolve unresolvedReferences from earlier resource creation/attachment and instruction updates, then compile with PUT /v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID. Compile returns message and durationMs; it has no unresolved-reference field. Retain the agent’s existing tools and test the actual conversation through the trusted application. For a read-only direct attachment, use type integration, its returned integrationToolID, a target and inputVariables keyed by schema names; each input contains integrationToolVariableName, required and defaultValue. The tool contract owns the full lookup schema. Standalone execution alone does not attach, compile or publish anything.
Native Capture response starts inside the action’s data, using the paths below without a data or output prefix. Standalone responses add output.data. Clear retained results before a new attempt: failed actions or missing fields can leave old values unchanged.
Reconnect or stop account access
Change the connection deliberately without changing saved records.
In More → Integrations, inspect the intended connection before choosing reconnect/disconnect. Repeat browser OAuth and a controlled action after an account change. Review Published and Draft consumers before revoking access; stopping authorization does not delete records, spreadsheet rows or imported Knowledge. Do not disconnect automatically to address a schema or field error.
Finding records
Read the intended fields from the approved base and table.
Use the base ID and exact table ID/name supplied by the owner. Field names and value meaning come from that table’s schema; a display name, row position or email is not an Airtable record ID. For private customer records, the application must authenticate and authorize the customer-to-record mapping before supplying the ID or query.
Invocation: Attach the lookup when the customer asks for permitted product/service information or their authorized request. The owner supplies the base/table and field scope; the application supplies protected identity. Do not let the model choose an arbitrary base or record.
Current result: Use the current matching record and approved fields; no match or failure must not reuse an earlier record. Test two distinct customers and a missing mapping through the actual application conversation.
List accepts fields, filterByFormula, sort, view, maxRecords and pageSize. Use maxRecords up to 100 to bound this connector’s result; a small page size alone is not a total limit. The implementation gathers pages up to the selected limit. This recipe leaves offset unset and uses the single-word field reference RequestKey without braces. Airtable permits this syntax; brace-shaped references can be interpreted by Voiceflow’s input binder. The Airtable filtering contract defines formulas/views; they are data selection, not customer authentication.
List records
Studio
Choose List records
For a read, use Agent → Global tools → + → Airtable → List records. For a write, use the guarded Workflow from the connection section and select List records in its Integration step. Keep raw write tools off the agent’s other tool lists.
Provide the exact inputs
Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.
Check the current outcome
Inspect records, reject ambiguous identity matches and use only the approved fields. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.
Code
Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:
Require success: true, error: null and truncated: false, then inspect records, reject ambiguous identity matches and use only the approved fields. A transport-level 200 alone does not establish success.
Conversation test: Ask “What is happening with my request?” and verify the exact authorized RequestKey, current status and answer. Repeat with no matching record.
Get record
Studio
Choose Get record
For a read, use Agent → Global tools → + → Airtable → Get record. For a write, use the guarded Workflow from the connection section and select Get record in its Integration step. Keep raw write tools off the agent’s other tool lists.
Provide the exact inputs
Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.
Check the current outcome
Compare record.id with the authorized record ID and read only its permitted fields. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.
Code
Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:
Require success: true, error: null and truncated: false, then compare record.id with the authorized record ID and read only its permitted fields. A transport-level 200 alone does not establish success.
Conversation test: Ask about a known request through the authenticated application; a foreign or missing mapping must not retrieve another customer’s record.
Recording support requests
Save confirmed fields once and retain a stable request-to-record mapping.
Prepare an example Requests table with RequestKey, Name, Email, Topic and Status. The owner maps these to their real schema. The connector’s record fields accept strings, numbers and booleans; use exact field names and values of the correct type. This recipe does not use automatic field conversion or nested linked-record/attachment values.
The illustrative confirmed request uses these values; replace them with the customer’s reviewed details. The backend prepares the full array and its expected readback values from the same validated request.
Invocation: Attach the guarded request Workflow when the customer confirms that they want the team to record their request. The customer supplies their request details; the backend validates confirmation and supplies the stable RequestKey plus serialized records through supportRequest in the input builders.
Current result: Require a current records[0].id, compare the saved fields and retain that Airtable ID against the same RequestKey. On failure, explain that saving is unverified; after a timeout, look up the stable RequestKey before retrying. Create is not an idempotent upsert and can produce duplicates.
Create records
Studio
Choose Create records
For a read, use Agent → Global tools → + → Airtable → Create records. For a write, use the guarded Workflow from the connection section and select Create records in its Integration step. Keep raw write tools off the agent’s other tool lists.
Provide the exact inputs
Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.
Check the current outcome
Capture records[0].id, open that same record and compare RequestKey, Name, Email, Topic and Status. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.
Code
Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:
Require success: true, error: null and truncated: false, then capture records[0].id, open that same record and compare RequestKey, Name, Email, Topic and Status. A transport-level 200 alone does not establish success.
Conversation test: Start “Please record my account-access problem.” Collect missing details, confirm once and inspect one correctly saved record. A rejected or unconfirmed action must not produce a saved-request acknowledgement.
Keep each create/update batch at 10 records or fewer, following Airtable’s record contract. For a customer request, use one record. A created row records work; it does not send an email or prove that a teammate has acted on it.
Changing existing records
Update or remove the authorized record and verify its actual effect.
Invocation: Use a dedicated guarded Workflow when the customer requests a permitted change to an existing request. The backend supplies the authorized Airtable record ID and confirmed new values; the customer/model must not choose arbitrary record IDs.
Current result: Use the current update/deletion result for that ID and inspect the provider record. Re-read after an update before acknowledging the saved status; a timeout is an uncertain outcome, not proof that no change happened.
Only supply fields you intend to change in records[].fields; omitted fields are not a request to clear the entire record. Validate the table’s status vocabulary before calling recordChange in the input builders.
Update records
Studio
Choose Update records
For a read, use Agent → Global tools → + → Airtable → Update records. For a write, use the guarded Workflow from the connection section and select Update records in its Integration step. Keep raw write tools off the agent’s other tool lists.
Provide the exact inputs
Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.
Check the current outcome
Compare records[0].id with the authorized ID, then use Get record to check the saved Status. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.
Code
Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:
Require success: true, error: null and truncated: false, then compare records[0].id with the authorized ID, then use Get record to check the saved Status. A transport-level 200 alone does not establish success.
Conversation test: Request an allowed status change for the signed-in customer, confirm it and inspect the same record before the agent says it changed. Repeat with a rejected field value.
Delete records
Studio
Choose Delete records
For a read, use Agent → Global tools → + → Airtable → Delete records. For a write, use the guarded Workflow from the connection section and select Delete records in its Integration step. Keep raw write tools off the agent’s other tool lists.
Provide the exact inputs
Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.
Check the current outcome
Inspect the matching ID under recordIDs and confirm the record is absent in Airtable. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.
Code
Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:
Require success: true, error: null and truncated: false, then inspect the matching ID under recordIDs and confirm the record is absent in Airtable. A transport-level 200 alone does not establish success.
Conversation test: Use a disposable, authorized request in the test base. Confirm deletion, inspect the result and verify the same record is absent; an unconfirmed request must take the no-write path.
Deletion accepts 1–10 record IDs and removes those records. Keep it off an ordinary support agent unless deletion is an approved customer job with its own enforced authorization/confirmation. Revoking the integration cannot undo deletion.
Resolve rejected fields or uncertain writes
Check schema, access and the saved record before choosing a retry.
- Unavailable base/table: confirm the OAuth account’s granted bases and the exact identifiers. The adapter performs a read while validating access even for a write.
- Rejected field/value: compare exact names and scalar types with the table schema; do not rely on type conversion to repair invalid input.
- No match: inspect the authorized mapping, view and formula without broadening access to other customers.
- Timeout/rate limit: reconcile the existing record or RequestKey and respect provider retry information. Repeating a create can duplicate it.
Continue with the Data & storage Guides.