This guide describes how and why to use the Google Sheets API to add and manage smart chips in your spreadsheets.

## What is a smart chip?

With smart chips, you can bring rich, interactive data from other Google Workspace applications directly into Sheets. Smart chips provide users with quick access to information and actions, transforming a cell link into a dynamic object. To learn more, see [Insert smart chips in your Google Sheets](https://support.google.com/docs/answer/12319513).

## Add a smart chip

Chips are represented as chip runs, which are part of [CellData](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/cells#CellData), so you can insert a chip using the existing [`spreadsheets.batchUpdate`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/batchUpdate) method by supplying an [`UpdateCellsRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#UpdateCellsRequest) or [`AppendCellsRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#AppendCellsRequest).

The request must include the `chipRuns` field. A chip run describes a chip's properties and where it is located within the cell's text.

When writing `chipRuns`, you must also provide a `userEnteredValue` that contains placeholder characters (`@`) for each chip you intend to add. Each run in the `chipRuns` array will correspond to one of the placeholders. Non-chipped runs can be omitted on write.

The following example shows how to write a file chip, a people chip, and plain text into a single cell, A1.
\* {JSON}

            {
              "updateCells": {
                "rows": [
                  {
                    "values": [
                      {
                        "userEnteredValue": {
                          "stringValue": "@ is the owner of @."
                        },
                        "chipRuns": [
                          {
                            "chip": {
                              "personProperties": {
                                "email": "johndoe@gmail.com",
                                "displayFormat": "DEFAULT"
                              }
                            }
                          },
                          {
                            "startIndex": 18,
                            "chip": {
                              "richLinkProperties": {
                                "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                              }
                            }
                          }
                        ]
                      }
                    ]
                  }
                ],
                "fields": "userEnteredValue,chipRuns",
                "range": {
                  "startRowIndex": 0,
                  "startColumnIndex": 0
                }
              }
            }

### Configure chip properties

A chip object can have one of the following property types:

#### personProperties

Use this to create a person chip.

- `email`: (Required) The email address of the person to link.
- `displayFormat`: (Optional) The preferred display format for the person's name. Can be one of the following:
  - `DEFAULT`: Standard "First Name Last Name" format.
  - `LAST_NAME_COMMA_FIRST_NAME`: "Last Name, First Name" format.
  - `EMAIL`: The person's email address.

#### richLinkProperties

Use this to create a rich link chip. While the API can read links to various Google services (like YouTube or Calendar), only links to Google Drive files can be written as chips.

- `uri`: (Required) The URI of the resource. For writing, this must be a Google Drive file link. URIs cannot exceed 2000 bytes.

> [!NOTE]
> **Note:** Writing Drive file chips requires your application to be authorized with at least one of the `drive.file`, `drive.readonly`, or `drive` OAuth scopes.

## Read a smart chip

To read a smart chip's data, use the [`spreadsheets.get`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get) method and include `sheets.data.rowData.values(chipRuns)` in the fields parameter.

The `chipRuns` array in the response will contain objects for all subsections of the cell's text.

- Chipped runs: These sections will have a populated `chip` object containing either `personProperties` or `richLinkProperties`.
- Non-chipped runs: Plain text sections will also have a run object, but its `chip` field will be empty.

To get the display text of a chip, add `formattedValue` as a field.

## Update a smart chip

To update or replace a smart chip, you have to overwrite the cell's contents. Use the same [`UpdateCellsRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#UpdateCellsRequest) or [`AppendCellsRequest`](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request#AppendCellsRequest) as you would for adding a chip, providing a new `userEnteredValue` and `chipRun`. This will replace the existing chip in the cell.

> [!IMPORTANT]
> **Important:** Writing a new `userEnteredValue` to a cell will erase all previous `chipRuns` from that cell. You must supply a new set of runs to persist or modify the chips.

## Use smart chips with other Sheets features

[Tables](https://developers.google.com/workspace/sheets/api/guides/tables): Smart chips can be used as a table column type to track project owners (People chip), or related documents (File chip).

[Filters](https://developers.google.com/workspace/sheets/api/guides/filters): You can filter ranges based on the text value of the smart chips within them.