HalosHalosDocs

Integrations

Integrations connect your agents to your real tools and data. Without integrations, agents rely on what you tell them in chat. With integrations, they can read your actual inbox, check your calendar, browse your Notion workspace, navigate any website, and more.

Available Integrations

| Integration | What It Enables | Auth Method | |------------|-----------------|-------------| | Gmail | Read, organize, label, draft, and send emails | Google OAuth | | Google Calendar | View, create, and manage calendar events | Google OAuth | | Apple Calendar | View events and create new ones via CalDAV | App-specific password | | Calendar URL (ICS) | Subscribe to any external calendar feed | URL subscription | | Notion | Access pages, databases, and workspace content | Notion OAuth | | Slack | Read channels, messages, and workspace activity | Slack OAuth | | GitHub | Access repositories, pull requests, issues, and code | GitHub OAuth | | Telegram | Connect agents to Telegram bots for mobile chat | Bot token | | Agent Email | Give agents their own email address for external mail | Resend (built-in) |

OAuth Integrations

Connecting via OAuth

  1. Go to Settings > Connections
  2. Click Connect next to the service you want
  3. You'll be redirected to the service's login/authorization page
  4. Grant the requested permissions
  5. You're redirected back to Halos — the integration is active

All OAuth integrations use standard OAuth flows. Halos never sees or stores your passwords. Tokens are encrypted at rest.

What Permissions Are Requested

Each integration requests the minimum permissions needed:

Gmail:

  • Read emails and metadata
  • Organize and label
  • Send on your behalf (only used when agent has sufficient trust)

Google Calendar:

  • View events
  • Create and modify events (only at higher trust levels)

Notion:

  • Read pages and databases you choose to share
  • Search your workspace
  • Create and update content

Slack:

  • Read public channel messages
  • Post messages to channels
  • View workspace and user info

GitHub:

  • Read repository content
  • View pull requests and issues
  • Access user and organization data

Calendar Integrations

Halos supports three ways to connect calendars:

Google Calendar

Connected via Google OAuth (same authorization as Gmail). Provides full read/write access — your agents can view events, create new ones, and modify existing events based on their trust level.

Apple Calendar

Connected via CalDAV with an app-specific password:

  1. Go to Settings > Connections
  2. Click Connect next to Apple Calendar
  3. Enter your Apple ID email and an app-specific password (generated from your Apple ID settings)
  4. Halos connects to caldav.icloud.com to sync your events

Your agents can read events from all your iCloud calendars and create new events.

Calendar URL (ICS/Webcal)

Subscribe to any standard calendar feed:

  1. Go to Settings > Connections
  2. Click Connect next to Calendar URL
  3. Paste any webcal:// or https:// URL that serves an ICS file
  4. Halos syncs the calendar events

This is read-only — perfect for subscribing to team calendars, sports schedules, public events, or any external calendar that provides an ICS feed.

Calendar Capabilities by Source

| Capability | Google Calendar | Apple Calendar | Calendar URL | |-----------|-----------------|----------------|-------------| | View events | Yes | Yes | Yes | | Create events | Yes | Yes | No | | Modify events | Yes | No | No | | Delete events | Yes | No | No |

How Agents Use Integrations

Once an integration is connected, your agents can access that data within the limits of their trust tier.

Observer Tier (Default)

At the Observer tier, agents can read integrated data but not modify it:

  • Gmail: Read and summarize emails, flag important messages
  • Calendar: View your schedule, note conflicts
  • Notion: Read pages and search content
  • Slack: Read messages and summarize channels
  • GitHub: View code, PRs, and issues

Higher Tiers

As you promote agents to Helper, Partner, or Trusted, they can do more:

| Tier | Gmail | Calendar | Notion | GitHub | |------|-------|----------|--------|--------| | Observer | Read, summarize | View events | Read pages | View code/PRs | | Helper | Draft replies, label | Draft events | Search, reference | Comment on PRs | | Partner | Send routine replies | Create events | Update pages | Create issues | | Trusted | Full email management | Full calendar management | Full workspace access | Full repo access |

Which Agent Gets Which Integration?

Integrations are account-level — once you connect Gmail, any agent could access it. But in practice, you control this through:

  1. Agent specialty — An email agent naturally uses Gmail; a code agent naturally uses GitHub
  2. Knowledge collection access — Control which context each agent can see
  3. Trust tier — Lower-trust agents have read-only access regardless
  4. Training instructions — Tell agents explicitly what to use or ignore

Browser Automation

Beyond traditional API integrations, every agent has access to browser automation powered by Stagehand + Browserbase. This means your agents can interact with any website — not just the services listed above.

What Agents Can Do in the Browser

| Tool | What It Does | |------|-------------| | browser_navigate | Open any URL in a cloud browser | | browser_act | Click buttons, fill forms, scroll, select options using natural language | | browser_extract | Pull structured data from the current page | | browser_observe | See what elements are visible and what actions are possible |

Use Cases

  • Fill out web forms on sites that don't have APIs
  • Monitor dashboards and extract metrics
  • Navigate complex sites with JavaScript-heavy interfaces
  • Log into accounts and perform actions (browser sessions persist)
  • Research on sites that block API access
  • Compare prices across e-commerce sites
  • Check order status on shipping sites

How It Works

Browser sessions run on Browserbase cloud infrastructure. Each agent gets its own browser session that persists across interactions — so if an agent logs into a site, it stays logged in for future requests.

Navigate to our analytics dashboard and tell me today's metrics

Go to LinkedIn and check if anyone viewed my profile this week

Fill out the expense report form at [URL] with these details: [details]

Agent Email Addresses

Beyond OAuth integrations, you can give any agent its own dedicated email address. This is separate from the Gmail integration — it's an email address that belongs to the agent itself.

How It Works

  1. Go to an agent's profile page
  2. In the Email section, set up an email address
  3. The agent gets an address like luna@mail.halos.sh
  4. External emails sent to that address arrive in the agent's inbox
  5. The agent can process, respond, or forward based on its trust level

Use Cases

  • Support agent: Give it support@yourdomain.com to handle customer emails
  • Admin agent: Give it admin@yourdomain.com to receive system notifications
  • Personal agent: Forward specific newsletters or alerts to the agent's address
  • Sales agent: Give it a dedicated address for lead inquiries

Inbound Email Processing

When an email arrives at an agent's address:

  1. The email is stored in the agent's inbox
  2. Images and attachments are analyzed (via Gemini if configured)
  3. The agent can read the email using the read_inbox tool
  4. Based on its trust level, it can respond via the send_email tool

Telegram Integration

Connect any agent to a Telegram bot for quick mobile interactions:

  1. Create a Telegram bot via @BotFather
  2. Go to the agent's profile page
  3. Enter the bot token in the Telegram section
  4. Messages sent to the bot go directly to the agent

Features

  • Text messages — Full conversational chat through Telegram
  • Voice messages — Send voice notes; the agent transcribes and responds
  • Voice replies — Agent responses can be converted to voice using ElevenLabs
  • Memory extraction — Important details from Telegram conversations are saved to the agent's memory
  • Full tool access — The agent has access to all its tools when responding via Telegram

This is especially useful for quick check-ins when you don't want to open the Halos app.

Integration Tutorials

Setting Up Gmail

What you'll need: A Google account with Gmail.

  1. Go to Settings > Connections
  2. Click Connect next to Google
  3. Sign in with your Google account
  4. Grant the requested permissions
  5. Back in Halos, your email agent can now read your inbox

Try it:

@Luna check my inbox and tell me what's important

Setting Up Apple Calendar

What you'll need: An Apple ID with iCloud Calendar enabled.

  1. Go to your Apple ID settings and generate an app-specific password
  2. Go to Settings > Connections in Halos
  3. Click Connect next to Apple Calendar
  4. Enter your Apple ID email and the app-specific password
  5. Your calendar events are now accessible to your agents

Try it:

What's on my calendar for tomorrow?

Setting Up Notion

What you'll need: A Notion account with at least one workspace.

  1. Go to Settings > Connections
  2. Click Connect next to Notion
  3. Sign in to Notion
  4. Choose which pages/databases to share
  5. Back in Halos, your agents can now reference your Notion content

Try it:

What's in my project roadmap on Notion?

Setting Up GitHub

What you'll need: A GitHub account with repository access.

  1. Go to Settings > Connections
  2. Click Connect next to GitHub
  3. Authorize Halos to access your repositories
  4. Back in Halos, your code agent can now browse your repos

Try it:

@Atlas what open PRs do I have on the main repo?

Setting Up Telegram

What you'll need: A Telegram account.

  1. Message @BotFather on Telegram
  2. Create a new bot with /newbot and follow the prompts
  3. Copy the bot token
  4. Go to your agent's profile page in Halos
  5. Paste the token in the Telegram section
  6. Start chatting with your bot on Telegram

Disconnecting

To remove an integration:

  1. Go to Settings > Connections
  2. Click Disconnect next to the service
  3. Confirm the disconnection

Disconnecting revokes access immediately. Your agents will no longer be able to read or interact with that service's data. The integration can be reconnected at any time.

Security & Privacy

  • OAuth only — Halos never stores passwords for OAuth-connected services
  • Token encryption — All tokens are encrypted at rest using AES-256
  • Minimal permissions — Each integration requests only what's needed
  • User-revocable — You can disconnect any integration instantly
  • Trust-gated — Even with an integration connected, agents can only do what their trust tier allows
  • No cross-user access — Each user's integrations are completely isolated

Next Steps

  • Agent Types — See which integrations work best with each agent type
  • Skills & Trust — Understand what agents can do with integrated data
  • Workflows — Follow tutorials that combine agents and integrations
  • Knowledge Base — Manage the context your agents use