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