# Connectors

> External accounts the agent accesses on your behalf — Google Drive, Mercado Pago, Skydropx, Odoo, GitHub — and how they are connected.

URL: https://www.ghosty.studio/en/docs/connectors

A connector is an external account the agent can use **on your behalf**. It is connected once per person and used by all your agents.

## How it works

- **The account connects; each agent is granted access.** The key is stored encrypted under `(your user, provider)`. As with databases, an agent only uses the connectors you give it in its page → **Connectors** (a new agent starts with none). On team channels it reads and writes; on customer channels it only reads, unless you allow it.
- **It acts as whoever invokes it.** In Teams, if `@handle` sends an email from a channel, it sends it with the account of the person who mentioned it, not with a shared account. On a public channel (WhatsApp) personal connectors **are not available**.
- **Disconnecting revokes.** Removing a connector deletes the key and revokes the grant at the provider.

## Where they are connected

- **Studio**: the **Connectors** chip in the chat (`/c`), and each agent's page shows which ones it has. Credential-based ones (Mercado Pago, Skydropx) are pasted in *Settings → Credentials*.
- **Teams**: the workspace's *Settings → Integrations*, for what the agent uses inside the workspace (GitHub, Calendly, Deník…).
- **Mobile app**: *Settings → Integrations* with the same list, through the [connectors API](#api).

## Catalog

| Connector | Type | What the agent can do |
|---|---|---|
| Google Drive | OAuth2 + picker | Read the sheets, docs and CSVs you pick; append rows and update cells. |
| Mercado Pago | Credentials (access token) | Payment links (Checkout Pro) to your account. |
| Skydropx | Credentials (Client ID:Secret) | Quote, create and track shipments. |
| EasyBits | OAuth2 | Documents, sites, video and images from your account. |
| Odoo | Credentials (URL, user, API key) (Teams) | Read and create ERP records. |
| GitHub | OAuth2 (Teams) | Issues, PRs and code from the workspace's repos. |
| Calendly | OAuth2 (Teams) | Scheduling and availability. |
| Google Calendar, Deník, Kommo, Mailmask | — | Coming soon. |

## Google Drive

The agent **only sees the files you pick**. When connecting, Google asks for access to "the files you use with this app" (`drive.file`) and then Google's picker opens so you choose your price list, inventory or catalog. Nothing else in your Drive is within its reach.

- **What it reads**: Google Sheets (every tab), Google Docs and CSV or text files. PDF and `.xlsx` not yet.
- **Tools**: `drive_archivos` (what you picked), `drive_leer`, `hoja_agregar_fila` and `hoja_actualizar`.
- **Writing** to a sheet works from team channels (your chat, Teams, scheduled). To let a customer (Messenger, WhatsApp) write, for example their order, tick "Can write from customer channels" in the agent's page → Connectors.
- **Add or remove files**: *Connectors → Google Drive → Files*. Which files **each agent** sees is chosen in its page → Connectors.
- **Disconnecting** revokes the grant in your Google account.

## Odoo and other credential-based connectors

Non-OAuth connectors are set up with their credentials (instance URL, user, key). The URL goes through a network guard: only public hosts, no private IPs and no `localhost`, so a connector can't be used to reach your internal network from the agent's machine.

## API

For your own clients (the mobile app uses these):

| Route | What it does |
|---|---|
| `GET /api/v2/me/connectors` | Catalog with `conectado: true/false` ("connected") per connector. |
| `POST /api/v2/me/connectors/:id/start` | Returns the authorization `url` to open in the browser. |
| `DELETE /api/v2/me/connectors/:id` | Disconnects and revokes. |

They require an OAuth2 bearer; see [Authentication](/en/docs/api/authentication).

```bash
# catalog with each connector's state
curl https://www.ghosty.studio/api/v2/me/connectors -H "Authorization: Bearer $TOKEN"

# start authorization for one (open the returned url in the browser)
curl -X POST https://www.ghosty.studio/api/v2/me/connectors/easybits/start -H "Authorization: Bearer $TOKEN"

# disconnect (revokes at the provider)
curl -X DELETE https://www.ghosty.studio/api/v2/me/connectors/easybits -H "Authorization: Bearer $TOKEN"
```