> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bothive.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Channels & Tools

> Step-by-step guide to connecting deployment channels and integrations to your bot.

## Overview

Every bot has two types of connections:

<CardGroup cols={2}>
  <Card title="Channels" icon="signal" className="glass-effect">
    Where your agent **receives messages and sends replies**. Examples: Web, Telegram, Slack, API.

    One agent can be connected to multiple channels simultaneously.
  </Card>

  <Card title="Tools (Integrations)" icon="plug" className="glass-effect">
    External systems your agent can **read from or write to**. Examples: GitHub, Gmail, Stripe.

    Integrations are used by the agent when it calls a capability in `capabilities { }`.
  </Card>
</CardGroup>

## Connecting a channel

<Steps>
  <Step title="Open the Channels tab">
    In your bot dashboard → **Channels**. You'll see all available channels.
  </Step>

  <Step title="Select a channel">
    Click the channel you want to connect. Each channel shows its setup requirements:

    | Channel  | What you need                     |
    | -------- | --------------------------------- |
    | Web      | Nothing — toggle to activate      |
    | Telegram | Bot token from @BotFather         |
    | Slack    | Bot OAuth token (`xoxb-...`)      |
    | API      | Your server's auth header         |
    | WhatsApp | WhatsApp Business API credentials |
  </Step>

  <Step title="Enter credentials">
    Paste the required token or credential. Bothive encrypts and stores it securely.
  </Step>

  <Step title="Verify the connection">
    Bothive automatically verifies the connection. A green  means the channel is live. A red  means the credential is invalid or the webhook failed to register.
  </Step>

  <Step title="Test with a real message">
    Send a test message through the channel. Confirm:

    * Message is received by Bothive
    * Agent responds within 3 seconds
    * Response is formatted correctly for the channel
    * Run appears in the **Runs** tab with a trace
  </Step>
</Steps>

## Connecting a tool (integration)

<Steps>
  <Step title="Open the Integrations tab">
    In your bot dashboard → **Integrations** → find the integration you want to connect.
  </Step>

  <Step title="Choose auth method">
    | Auth method | Common for                                      |
    | ----------- | ----------------------------------------------- |
    | OAuth 2.0   | Google (Gmail, Calendar), GitHub, Slack, Notion |
    | API Key     | Stripe, Paystack, Airtable, OpenAI              |
    | Bot Token   | Telegram                                        |
    | Custom      | Your own internal APIs                          |
  </Step>

  <Step title="Authorize OAuth or paste API key">
    For OAuth: Click **Connect with \[Provider]** → sign in → authorize the scopes. Bothive stores the access token and handles refresh automatically.

    For API key: Paste the key → click **Save**. The key is encrypted at rest.
  </Step>

  <Step title="Test the integration">
    Click **Test** on the integration. Bothive runs a live test call. If it succeeds, the integration is ready.
  </Step>

  <Step title="Add capabilities to your HiveLang bot">
    ```hivelang theme={null}
    bot MyBot {
      capabilities {
        gmail.readEmail       // Now that Gmail is connected
        github.createIssue    // And GitHub is connected
      }
    }
    ```
  </Step>
</Steps>

## Auth method reference

| Method                         | Stored as               | Token refresh | User required        |
| ------------------------------ | ----------------------- | ------------- | -------------------- |
| OAuth 2.0 (Auth Code)          | Encrypted token pair    | Automatic     | Yes — must authorize |
| OAuth 2.0 (Client Credentials) | Encrypted client secret | Automatic     | No                   |
| API Key                        | Encrypted string        | Manual        | No                   |
| Bot Token                      | Encrypted string        | Manual        | No                   |
| Basic Auth                     | Encrypted credentials   | Manual        | No                   |

## Common connection errors

<AccordionGroup>
  <Accordion title="Telegram: Webhook failed to register">
    The bot token may be invalid or already used by another webhook. Go to BotFather → `/revoke` to reset the token → reconnect with the new token.
  </Accordion>

  <Accordion title="Slack: 'not_authed' or 'invalid_auth'">
    The OAuth token has expired or been revoked. Go to your Slack App dashboard → reinstall the app to your workspace → copy the new `xoxb-` token.
  </Accordion>

  <Accordion title="Gmail: 'insufficient permissions'">
    The Gmail OAuth scope is missing. Disconnect the integration → reconnect and make sure to approve all requested scopes when prompted.
  </Accordion>

  <Accordion title="GitHub: '404 Not Found' on tool calls">
    The GitHub OAuth app may not have access to the specific repository. In GitHub → **Settings** → **Applications** → find Bothive → grant access to the required repos.
  </Accordion>

  <Accordion title="Stripe: 'No such customer'">
    The Stripe API key is in test mode but you're looking up live customers (or vice versa). Ensure your Stripe API key matches the mode (`sk_test_` vs `sk_live_`) you're testing in.
  </Accordion>

  <Accordion title="Custom integration: 401 Unauthorized">
    Check that the API key or Bearer token is correct and that it hasn't expired. Try the same credential in Postman or curl to isolate whether it's a Bothive configuration issue or an API issue.
  </Accordion>
</AccordionGroup>

## Revoking access

To disconnect a channel or integration:

1. Open **Channels** or **Integrations** in your bot dashboard
2. Click the connected item → **Disconnect**
3. Confirm — Bothive deletes the stored credential

For OAuth integrations, also revoke access from the provider's OAuth settings to fully remove access.

## Next reads

<CardGroup cols={3}>
  <Card title="Deploy to Channels" icon="signal" href="./deploy-to-channels" className="glass-effect" />

  <Card title="Integration Capabilities" icon="list" href="./integration-capabilities" className="glass-effect" />

  <Card title="Custom Integrations" icon="wrench" href="./custom-integrations" className="glass-effect" />
</CardGroup>