> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview of the App SDK

> An overview of the functionality provided by the App SDK

export const MermaidDiagram = ({children, large = false, id}) => {
  if (large) {
    return <div className="flex justify-center w-full">
        <code className="language-mermaid w-full">
          {children}
        </code>
      </div>;
  }
  return <div className="mermaid-inline">
  <Tooltip tip="Click to enlarge">
    <a href={`/diagrams/${id}`}>
      <code className="language-mermaid">{children}</code>
    </a>
  </Tooltip>
</div>;
};

<Note>
  This only covers apps from the perspective of the App SDK, apps can also use the REST API
</Note>

**An app is a way to extend the existing functionality of Attio**,
typically by pulling data into Attio from a third party source, or of
extracting data out of Attio to use with some tool. Apps can provide custom
UI *directly inside of Attio's user interface* using custom React components.

Specifically you can add custom actions (buttons) to record pages inside Attio. When clicked you can trigger a server function, and/or display a modal to users with custom UI to complete a form or view information.

Let's look at an example.

Let's imagine a hypothetical service called **Acme Lead Checker** (ALC) that has
an API to receive potential leads, an AI agent initiates an SMS chat with the lead,
and then needs to update the lead's record in Attio about how interested the
person is in whatever product we are selling.

Our app needs:

* A button inside Attio that will call a server function
* A server function to actually send the data to ALC
* A webhook to receive the lead status back from ALC sometime in the future

<Note>
  App UI components cannot directly communicate with the outside world. They can only call custom
  app server functions, which *can* communicate with the outside world via
  [`fetch()`](../server/available-globals#server-only), and communicate with Attio's REST API via
  [`ATTIO_API_TOKEN`](../server/attio-api-token).
</Note>

## Sequence

The general sequence of how the app will work is:

### Installation

1. User clicks to install the app.
2. User is prompted to add a [connection](../server/connections) to Acme Lead Checker
3. User logs into Acme Lead Checker to complete the OAuth flow.
4. User is redirected back to Attio. The app is now installed.
5. The [`connection-added`](../server/events/connection-added) event handler the app
   registered is fired.
6. Event Handler calls [`createWebhookHandler()`](../server/webhooks/create-webhook-handler)
   to register a [webhook handler](../server/webhooks/update-webhook-handler).
7. Event Handler registers the new webhook with Acme Lead Checker.

<MermaidDiagram id="app-install-sequence">
  ```mermaid theme={"system"}
  sequenceDiagram
      actor User
      participant Attio UI
      participant ALC as Acme Lead Checker
      participant Event Handler
      participant Attio Server SDK

      User->>Attio UI: Clicks to install app
      Attio UI->>User: Prompts to add connection to ALC
      User->>ALC: Logs in (OAuth flow)
      ALC-->>Attio UI: Redirects back with auth token
      Attio UI-->>User: Shows app is now installed
      Attio UI->>Event Handler: Fires 'connection-added' event
      Event Handler->>Attio Server SDK: Calls createWebhookHandler()
      Attio Server SDK-->>Event Handler: Returns webhook handler details
      Event Handler->>ALC: Registers webhook
  ```
</MermaidDiagram>

### Usage

1. App provides a [record action](../entry-points/record-action) which will manifest
   itself in Attio's UI as - a button on the People record page - in the CMD-K quick action palette.
2. User views the record page
3. User clicks button
4. Attio's UI fires the `onTrigger()` function provided by the record action
5. Record Action notifies the user that async things are happening
   with [`showToast()`](../notifications/show-toast).
6. Record Action loads the phone number of the person whose record page we are on
   asynchronously via [GraphQL](../graphql) using [`runQuery()`](../graphql/run-query). - If no phone numbers are found, the user is notified via an [`alert()`](../notifications/alert).
   Otherwise...
7. Record Action calls a
   [server function](../server/server-functions) called `sendToALC()`.
8. Server function uses [`fetch()`](../server/available-globals#server-only)
   to send a `POST` request to `api.acmeleadchecker.ai`.
9. Server function calls the [Attio REST API](/rest-api/overview) with [`ATTIO_API_TOKEN`](../server/attio-api-token) to mark the record
   as "Pending".
10. Server function returns success.
11. Record Action hides first toast
    with [`hideToast()`](../notifications/show-toast#hidetoast-promise-void).
12. Record Action notifies the user that the process was successful
    with [`showToast()`](../notifications/show-toast).

...some time later...

10. Acme Lead Checker's server calls a webhook provided by the app.
11. Webhook Handler calls the [Attio REST API](/rest-api/overview) with [`ATTIO_API_TOKEN`](../server/attio-api-token) to mark the record
    as "Complete".

<MermaidDiagram id="app-usage-sequence">
  ```mermaid theme={"system"}
  sequenceDiagram
      actor User
      participant Attio UI
      participant Record Action
      participant GraphQL
      participant Server Function
      participant ALC as api.acmeleadchecker.ai
      participant Webhook
      participant Attio API

      User->>Attio UI: Clicks button
      Attio UI->>Record Action: Fires onTrigger()
      Record Action-->>Attio UI: showToast()
      Attio UI-->>User: Shows "Loading" toast
      Record Action->>GraphQL: Load phone numbers
      GraphQL-->>Record Action: Query result
      Record Action->>Server Function: Calls sendToALC()
      Server Function->>ALC: POST request
      Server Function->>Attio API: with ATTIO_API_TOKEN to mark record "Pending"
      Server Function-->>Record Action: Returns success
      Record Action-->>Attio UI: hideToast()
      Attio UI-->>User: Hides "Loading" toast
      Record Action-->>Attio UI: showToast()
      Attio UI-->>User: Shows "Success" toast

      Note over User,Attio API: Some time later...

      ALC->>Webhook: Calls the app's webhook
      Webhook->>Attio API: with ATTIO_API_TOKEN to mark record "Complete"
  ```
</MermaidDiagram>

## Implementation

### `app.ts`

An app always contains an `app.ts` file in the `src` folder, which describes its different entry points.
Here's an example of an empty app which doesn't have any features yet.

```ts theme={"system"}
import type {App} from "attio"

export const app: App = {
  record: {
    actions: [],
    bulkActions: [],
    widgets: [],
  },
  callRecording: {
    insight: {
      textActions: [],
    },
    summary: {
      textActions: [],
    },
    transcript: {
      textActions: [],
    },
  },
}
```

### Record action

Our [Record action](../entry-points/record-action) can be defined in any file, and must have the type `App.Record.Action`.

```typescript send-to-alc-record-action.ts theme={"system"}
import type {App} from "attio"
import {runQuery, showToast, alert} from "attio/client"
import getPersonPhoneNumbersQuery from "./get-person-phone-numbers.graphql"
import sendToAlc from "./send-to-alc.server"

export const sendToAlcAction: App.Record.Action = {
  id: "send-to-alc", // internal unique identifier
  label: "Send to ALC", // user-facing label
  onTrigger: async ({recordId}) => {
    const {hideToast} = await showToast({
      title: "Preparing to send to ALC...",
      variant: "neutral",
    })

    const {person} = await runQuery(getPersonPhoneNumbersQuery, {recordId})
    // `person` is strongly typed here as:
    // {
    //   name: {
    //     full_name: string | null
    //   } | null
    //   phone_numbers: string[]
    // } | null
    // ...so TypeScript will help us know the checks we need to perform.

    if (!person) {
      await hideToast()
      await alert({
        title: "Failed to load person data",
        text: "Please try again.",
      })
      return
    }

    const firstPhoneNumber = person.phone_numbers[0] ?? null
    if (!firstPhoneNumber) {
      await hideToast()
      await alert({
        title: "No phone number found",
        text: "Please add a phone number to the person and try again.",
      })
      return
    }

    try {
      await sendToAlc(recordId, person.name?.full_name ?? "Unknown", firstPhoneNumber)
    } catch {
      await hideToast()
      await alert({
        title: "Failed to send to ALC",
        text: "Please try again.",
      })
      return
    }

    await hideToast()
    await showToast({
      title: "Successfully sent to ALC!",
      variant: "success",
    })
  },
  objects: "person", // only show this action on person records
}
```

We must then include our record action in `app.ts`.

```ts theme={"system"}
import type {App} from "attio"

import {sendToAlcAction} from "./send-to-alc-record-action"

export const app: App = {
  record: {
    actions: [sendToAlcAction],
    // ...
  },
  // ...
}
```

### GraphQL query

Now let's write that [GraphQL](../graphql) query we're importing.

```graphql get-person-phone-numbers.graphql theme={"system"}
query getPersonPhoneNumbers($recordId: String!) {
  person(id: $recordId) {
    name {
      full_name
    }
    phone_numbers
  }
}
```

### Server function

[Server function](../server) file names *MUST*:

* have a `.server.ts` suffix
* contain an `export default async function`

The suffix is how Attio knows to execute them on the server. However,
they are imported as if they were in the same bundle as the client side code,
even though they are not.

<Warning>
  Because they live in different bundles and runtimes, everything passed to, returned from, or
  thrown by server functions *MUST* be serializable.
</Warning>

```typescript send-to-alc.server.ts theme={"system"}
import {ATTIO_API_TOKEN, getWorkspaceConnection} from "attio/server"

export default async function sendToAlc(recordId: string, name: string, phoneNumber: string) {
  // Get the authorization token from the workspace connection
  // that the user has set up in their Attio account.
  const connection = getWorkspaceConnection()
  const authorizationToken = connection.value

  const response = await fetch("https://api.acmeleadchecker.ai/api/v1/leads", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authorizationToken}`,
    },
    body: JSON.stringify({recordId, name, phoneNumber}),
  })

  if (!response.ok) {
    throw new Error("Failed to send to ALC")
  }

  const lead = await response.json()

  await fetch(`https://api.attio.com/v2/objects/people/records/${recordId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${ATTIO_API_TOKEN}`,
    },
    body: JSON.stringify({
      data: {
        values: {
          alc_lead_id: [{value: lead.id}],
        },
      },
    }),
  })

  return lead
}
```

### Webhook handler

Our [webhook handler](../server/webhooks) is going to be called by Acme Lead Checker
when they have processed our lead that we sent them.

Webhook handler files *MUST*:

* Live under the `src/webhooks` directory
* Have a `.webhook.ts` suffix.
* Contain an `export default async function` that:
  * takes an HTTP [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) argument
  * returns an HTTP [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response)

```typescript webhooks/lead-processed.webhook.ts theme={"system"}
import {ATTIO_API_TOKEN} from "attio/server"

export default async function leadProcessedWebhook(req: Request): Promise<Response> {
  const body = await req.json()

  const recordId = body.record_id
  const status = body.status

  if (!recordId || !status) {
    return new Response("Bad Request", {status: 400})
  }

  await fetch(`https://api.attio.com/v2/objects/people/records/${recordId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${ATTIO_API_TOKEN}`,
    },
    body: JSON.stringify({
      data: {
        values: {
          alc_status: [{value: status}],
        },
      },
    }),
  })

  return new Response(null, {status: 200})
}
```

### Connection event handlers

In order to let Acme Lead Checker know how to call our app's webhook, we need to
tell them as soon as our user creates an authorized [connection](../server/connections);
we accomplish this with [event handlers](../server/events).

Connection Event Handler files *MUST*:

* Live in `src/events`
* Have a `.event.ts` suffix.
* Contain an `export default async function` that:
  * Takes a `{ connection: Connection }` argument
  * Returns `void`

#### Connection added event handler

When a connection is added, we need to:

1. Create a webhook
2. Register our webhook with Acme Lead Checker
3. Update our webhook with the unique identifier of our webhook on ALC's side

```typescript events/connection-added.event.ts theme={"system"}
import type {Connection} from "attio/server"
import {createWebhookHandler, updateWebhookHandler} from "attio/server"

export default async function connectionAdded({connection}: {connection: Connection}) {
  // The filename must match the file in src/webhooks, but without the suffix
  const handler = await createWebhookHandler({fileName: "lead-processed"})

  const authorizationToken = connection.value

  const response = await fetch("https://api.acmeleadchecker.ai/api/v1/webhooks", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${authorizationToken}`,
    },
    body: JSON.stringify({
      name: handler.id,
      url: handler.url,
      event: "lead.processed",
    }),
  })

  if (!response.ok) {
    throw new Error(`Failed to register webhook: ${response.statusText}`)
  }

  const webhook = await response.json()

  // Save the external webhook ID so we can delete it when the connection is removed
  await updateWebhookHandler(handler.id, {
    externalWebhookId: webhook.webhook_id,
  })
}
```

#### Connection removed event handler

When a connection is removed, we need to:

1. Load all our app's webhook handlers (there should only be one)
2. For each handler, tell ALC to stop calling it
3. Delete the webhook from Attio

```typescript events/connection-removed.event.ts theme={"system"}
import type {Connection} from "attio/server"
import {deleteWebhookHandler, listWebhookHandlers} from "attio/server"

export default async function connectionRemoved({connection}: {connection: Connection}) {
  try {
    const handlers = await listWebhookHandlers()
    const authorizationToken = connection.value

    // Delete webhooks on ALC
    // There should be only one webhook handler active as we have single workspace connection
    await Promise.all(
      handlers.map(async (handler) => {
        const response = await fetch(
          `https://api.acmeleadchecker.ai/api/v1/webhooks/${handler.externalWebhookId}`,
          {
            method: "DELETE",
            headers: {
              Authorization: `Bearer ${authorizationToken}`,
            },
          },
        )
        if (!response.ok) {
          throw new Error(`Failed to delete webhook: ${response.statusText}`)
        }
      }),
    )

    // Delete webhooks on Attio
    await Promise.all(
      handlers.map(async (handler) => {
        await deleteWebhookHandler(handler.id)
      }),
    )
  } catch (error) {
    console.error(error)
    // don't rethrow the error so the connection is still removed
  }
}
```