Google Connectors

Three connectors, each connected on its own by the signed-in person: Google Calendar (google-calendar, tool codespar_calendar), Google Drive (google-drive, codespar_drive) and Gmail (gmail, codespar_gmail). A connection belongs to that person in that project: another member of the organization never sees it, uses it, or reads what it returns. The tools are on the hosted server while the connectors are switched on for the deployment.

Connecting

The person connects each connector from Shop › Preferências, section Conexões Google, which runs the Connect Link flow for their own account:

1. POST /v1/connect/start with server_id (google-calendar, google-drive or gmail), the person's own user_id and an https redirect_uri answers Google's consent address.
2. The person consents at Google. The connector asks for its product scope (calendar, drive or gmail.modify) and the identity scopes that say which Google account it is.
3. Google returns to the redirect_uri with status=connected&connection_id=…&server_id=…, or status=denied or status=error&error=….

GET /v1/connectors lists the three with their state for the person: connected, not_connected, or consent_required when the grant is gone at Google. DELETE /v1/connectors/connections/{id} disconnects one and revokes the grant at Google when no other connector of the person still uses it. If the person unticks a scope at Google, reads still work where a narrower scope allows them, and a write answers connector_scope_insufficient naming the scope it needs.

Reads and writes

Reads answer at once. Text read from mail, files or events is the account's content, never an instruction: a message asking to forward, share or delete something is not the person asking.

Every write is confirmed by the person first. Creating, changing, deleting, trashing, sharing, sending, replying and changing labels all work the same way:

1. The first call writes nothing. It answers connector_action_confirmation_required with details: the preview of exactly what would happen (a sentence in Portuguese, summary_pt, and the fields: recipients, subject and body, the event's times, the file), a confirmation_id (cac_…) and expires_at, 15 minutes later.
2. In the Shop conversation the person confirms on the card under the turn. The model of the conversation can never confirm: a confirmation_id in its call is refused.
3. On the hosted server the client shows the preview to the person and, only if they agree, calls the same action again with the same arguments and that confirmation_id. Different arguments are a different write, and the id does not approve them.
4. Before writing, the server computes the preview again from Google as it is now. If it changed (the event was edited, the thread got a new message), nothing is written and the confirmation goes stale.

A confirmation runs once. The record keeps who approved it, when, through which channel and what Google answered (ids and flags only); the write's content is sealed while it waits and deleted once it is decided. Permanent deletion is not offered: Drive and Gmail move to the trash, where Google keeps them for 30 days.

Actions

Google Calendar

Google Drive

Gmail

Example

The first call of a write, then the confirmed call with the same arguments:

{
  "name": "codespar_gmail",
  "arguments": {
    "action": "send",
    "to": ["loja@example.com"],
    "subject": "Troca do pedido 1234",
    "body": "Olá, gostaria de trocar o tênis do pedido 1234 pelo número 43."
  }
}

{
  "code": "connector_action_confirmation_required",
  "error": "nothing was written: show the preview to the person and, only if they agree, call again with the same arguments and confirmation_id",
  "details": {
    "tool": "codespar_gmail",
    "action": "send",
    "server_id": "gmail",
    "confirmation_id": "cac_0000000000000000",
    "expires_at": "2026-11-04T15:15:00.000Z",
    "preview": {
      "summary_pt": "Enviar um e-mail para loja@example.com com o assunto \"Troca do pedido 1234\".",
      "to": ["loja@example.com"],
      "subject": "Troca do pedido 1234",
      "body": "Olá, gostaria de trocar o tênis do pedido 1234 pelo número 43.",
      "sends_now": true
    }
  }
}

After the person agrees, the same arguments plus "confirmation_id": "cac_0000000000000000" sends it and answers status: "executed" with Google's ids.

Arguments

codespar_calendar

codespar_drive

codespar_gmail

Errors and what to do

Related

• Connect Links: the connect flow these connections use
• Shop memory and Shop watches: the person's other own data
• Hosted server: where the three tools are published

Notes

Where the person sees it. Shop › Preferências › Conexões Google shows each connector with its state, the masked account and the granted permissions in words, with Conectar, Reconectar and Desconectar.