# Airtable

Airtable ticketing integration

## Overview

The Airtable integration provides two-way ticket synchronization between Risotto and an Airtable base, for teams who run their helpdesk on Airtable instead of a traditional ITSM tool. When a ticket is created in Risotto, a matching record is created in your Airtable table — and comments, assignee changes, and resolutions made in Airtable sync back to Risotto and Slack.

> **Note:** Airtable uses **two-way sync** via a webhook Risotto registers on your base.
> Risotto creates the record with the ticket's title, then keeps its
> conversation log, status, requester, assignee, priority, and attachments up to
> date. From Airtable, Risotto picks up new comments in the conversation log,
> assignee changes, and a change of **Status** to the option you map to
> **Resolved**, which resolves the ticket. Other status changes and attachments
> added in Airtable don't sync back.

## Prerequisites

> **Warning:** This integration requires an **Airtable Enterprise** personal access token.
> Risotto needs to resolve people by email to populate the Requestor and
> Assignee fields when they are Airtable **User** fields, and that lookup
> requires Enterprise-level API access — a standard Business-tier token isn't
> sufficient.

Before connecting, make sure you have:

1. **An Airtable Enterprise personal access token** with access to the target base and at least these scopes: `data.records:read`, `data.records:write`, `schema.bases:read`, and `webhook:manage`
2. **Your Base ID** — found in the Airtable API documentation for your base, or in the base URL
3. **A table** in that base with these fields:
   - a single select field for the status, with an option for resolved tickets
   - a text field for the title
   - a text or User field each for the requester and the assignee
   - a long text or rich text field for the conversation log
   - an attachment field

## Configuration

When connecting Airtable in Risotto, you'll provide:

| Field                            | Required | Description                                                                                                                         |
| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Personal Access Token**        | Yes      | Your Airtable Enterprise token                                                                                                      |
| **Airtable Base ID**             | Yes      | The base containing your ticket table                                                                                               |
| **Airtable Table ID**            | Yes      | The ID of the table Risotto should sync tickets into                                                                                |
| **Page Interface ID (Optional)** | No       | Point the **Open in Airtable** link at an interface page instead of the raw data table                                              |
| **Fields Mapping**               | Yes      | Map Risotto's **Status**, **Title**, **Requestor**, **Assignee**, **Conversation**, and **Attachments** to fields in your table     |
| **Resolved**                     | Yes      | The status option Risotto sets when a ticket is resolved or closed. Setting a record to this option in Airtable resolves the ticket |
| **Open**                         | No       | The status option Risotto sets when a ticket is open, in progress, or awaiting support                                              |
| **Waiting for Approval**         | No       | The status option Risotto sets while a ticket awaits approval                                                                       |
| **Chat URL**                     | No       | A URL field that gets a link to the request's chat thread                                                                           |
| **Priority**                     | No       | A single select field for the ticket's priority, with the option to use for each of **Urgent**, **High**, **Medium**, and **Low**   |
| **Default Assignee**             | No       | An email for a User-type Assignee field when the ticket is assigned to a bot instead of a person                                    |
| **Custom Field**                 | No       | Set a constant value on a text field for every ticket Risotto creates (e.g. a `Queue` field)                                        |
| **Comment Divider**              | Yes      | The divider Risotto adds between comments in the conversation log                                                                   |

> **Tip:** By default, the "Open in Airtable" link opens the base's data layer. If your
> team works from an Airtable **Interface**, set a **Page Interface ID** so the
> link opens the right view instead.

## Setup Process

### Step 1: Configure a Department

You need permission to change the department's settings: an Org Admin, a Manager, or a Supervisor of the department.

1. **Open your department**

   In your Risotto dashboard, go to **Settings**. Under **Departments**, click a
   department, then click **Ticket Sync**.

2. **Add Airtable ticket sync**

   Click **Add ticket sync** and select **Airtable**. **Add ticket sync** shows
   only while the department has no ticket sync: a department syncs with one
   ticketing system.

   *Product example: The Add Ticket Sync for IT dialog, listing the ticketing integrations, with Airtable ringed.*

3. **Enter your connection details**

   In the **Configure Airtable for \<department>** dialog, enter the
   **Personal Access Token**, **Airtable Base ID**, and **Airtable Table ID**,
   and optionally a **Page Interface ID**. Then click **Load table schema**.

   *Product example: The Configure Airtable for IT dialog, with the token, base ID and table ID filled in, and Load table schema.*

   Once the schema loads, the token, base, and table fields become read-only.

4. **Map your fields**

   Under **Fields Mapping**, map **Status**, **Title**, **Requestor**,
   **Assignee**, **Conversation**, and **Attachments** to fields in your
   table. Each list shows only the fields of a type it accepts. After you pick
   the **Status** field, choose its option for **Resolved**, and optionally for
   **Open** and **Waiting for Approval**. Optionally, map **Chat URL**,
   **Priority** (with an option for each priority), a **Default Assignee**, and
   a **Custom Field** with its value.

   Fields are stored by ID, so renaming a field in Airtable later won't break
   the sync. Status and priority options are stored by name: if you rename one
   in Airtable, choose it again here.

5. **Save**

   Enter a **Comment Divider** and click **Save**. **Save** turns on once every
   required field is filled in.

   *Product example: The Configure Airtable for IT dialog scrolled to its Fields Mapping, with each Risotto field mapped to a field of the IT Requests table, and Save.*

   Make sure **External ticket sync enabled** is on for the department. To
   change the mapping later, open the **Connected** menu on the **Airtable**
   card and click **Configure...**.

### Step 2: Test the Integration

Create a test ticket through Risotto and confirm a matching record appears in Airtable with the right fields populated. Then set the record's status to the option you mapped to **Resolved** and confirm the Risotto ticket resolves.

## Comments and internal notes

When someone adds a comment to the conversation log in Airtable, Risotto adds it to the Risotto ticket and, if the ticket has one, to the ticket's thread in your agent channel. Risotto also posts it to the requester's Slack thread, unless the comment is an internal note.

A comment is an internal note when one of these is true:

- The comment's author line contains `(Internal)`. The author line is the line with the author's email address and the date, for example `ivan@example.com (Internal) 9/22/2026 5:11pm`. Lines above the author line, such as a status line, are ignored.
- The text after the author line starts with 🔒 (or `:lock:`).

Risotto stores an internal note as an internal comment on the ticket. The requester does not see it.

## Attachments

Screenshots and files shared in Slack upload to the record's attachment field in Airtable automatically.

## Troubleshooting

### 422 errors when creating or updating a ticket

This usually means the Requestor or Assignee email doesn't match a user in
your Airtable base's Enterprise directory — Airtable can't put an unrecognized
email into a User field. Confirm the person exists as an Airtable user, or
adjust the default assignee.

If your Requestor or Assignee field is a **single collaborator** field, the
person also has to be a collaborator on the base itself. When Airtable rejects
a record for this reason, your Risotto admins receive a notification that names
the user and field (for example, *Cannot resolve the user … for field
Requestor*) instead of a generic 422 error. To fix it, add the user as a
collaborator on the base, or map the field to a plain text field instead.

### Connection rejected or webhook registration fails

Confirm the personal access token has the `webhook:manage` scope and access to
the base. If Airtable refuses the token when Risotto registers the webhook,
your Risotto admins receive an **Airtable connection needs to be reconnected**
notification. Also confirm the token is an **Enterprise** token, not a
Business-tier token — the Requestor/Assignee User field lookup requires
Enterprise API access.

### Comments intermittently not syncing

Airtable's API occasionally returns temporary server errors during high load.
Risotto retries automatically; if a comment is still missing after a few
minutes, check the ticket for a sync error and try again.

### Open in Airtable link goes to the wrong view

Set a **Page Interface ID** in the department's Airtable ticket sync settings
so the link points at your Interface layout instead of the base's data table.

## Best Practices

1. **Use a dedicated Enterprise token**: Generate the personal access token from a service account, not a personal one
2. **Set a default assignee for bot assignments**: If your Assignee field is a User field, set a **Default Assignee** so tickets assigned to a bot still get an Airtable user
3. **Test with a small table first**: Verify field mapping and the sync direction before rolling out to your full base

## Related Integrations

- [Ticketing Integrations Overview](https://www.tryrisotto.com/docs/integrations/ticketing/overview)
- [Jira Integration](https://www.tryrisotto.com/docs/integrations/ticketing/jira)

Source: https://www.tryrisotto.com/docs/integrations/ticketing/airtable
