# External Service Integrations

## Overview
Gipity connects to external services so you can manage tasks, send messages, access APIs, and more - all through natural conversation. Authentication is handled automatically once a service is connected.

## Built-in Providers

### Google (tested)
- Search and read emails, send and reply
- List, create, update, and delete calendar events
- Access Drive, Sheets, and other Google APIs
- *Use the dedicated Gmail/Calendar tools for common operations - they have better formatting and error handling*

### Telegram (tested)
- Receive and respond to messages via Telegram bot

### Slack (experimental)
- OAuth2 via `https://slack.com/api`
- User provides their own Slack app credentials (client ID + secret)

### GitHub (experimental)
- OAuth2 via `https://api.github.com`
- User provides their own GitHub OAuth app credentials

### Todoist (experimental)
- API key auth via `https://api.todoist.com`
- User provides their Todoist API token

### Notion (experimental)
- OAuth2 via `https://api.notion.com/v1`
- User provides their own Notion integration credentials

> **Note:** "Experimental" means the provider's OAuth/API-key URLs and base URLs are seeded in the database, and the generic `service_call` proxy should work in theory - but the end-to-end flow (connect → token → real API call → response) has not been verified against a real account. If you try one of these and it works (or doesn't), let us know.

## Additional Providers
The platform supports registering new providers at runtime via the skill store (`skill_store_search` / `skill_store_install`). Any service with an OAuth2 or API-key auth model can be added.

## Connecting a Service
To use a service, the user needs to connect it first. Ask the user to connect the service they want to use - this opens an authorization flow (OAuth) or asks for their API key, depending on the provider.

For OAuth services, the user provides their own OAuth app credentials (client ID and secret from the provider's developer portal). This is a one-time setup per service.

API key services just need the user's API key.

## Checking Status
You can check which services are connected and view their permission settings.

## Permissions
- **Read operations** (GET): allowed once a service is connected
- **Write operations** (POST/PUT/PATCH/DELETE): require approval by default
- Users can adjust permission settings per service

## Tips
- For Google Gmail/Calendar, prefer the dedicated tools - they have better formatting and error handling
- Always check the provider's API documentation for correct paths and parameters
- Responses are JSON by default; large responses are truncated at 50KB

---

## Implementation Reference
- Connect services: `connector_manage` tool (actions: connect, disconnect, list, status, permissions, providers)
- Make API calls: `service_call` tool (provider, method, path, params, body)
- Auth is injected automatically - never include auth headers
- Provider base URLs are locked - only the path portion is configurable

