Connecting Channels & Tools
The connection flow is the same for every channel and integration — connect, verify, test. Here’s how.
Overview
Every bot has two types of connections:Channels
Where your agent receives messages and sends replies. Examples: Web, Telegram, Slack, API.One agent can be connected to multiple channels simultaneously.
Tools (Integrations)
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 { }.Connecting a channel
1
Open the Channels tab
In your bot dashboard → Channels. You’ll see all available channels.
2
Select a channel
Click the channel you want to connect. Each channel shows its setup requirements:
3
Enter credentials
Paste the required token or credential. Bothive encrypts and stores it securely.
4
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.
5
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
Connecting a tool (integration)
1
Open the Integrations tab
In your bot dashboard → Integrations → find the integration you want to connect.
2
Choose auth method
3
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.
4
Test the integration
Click Test on the integration. Bothive runs a live test call. If it succeeds, the integration is ready.
5
Add capabilities to your HiveLang bot
Auth method reference
Common connection errors
Telegram: Webhook failed to register
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.Slack: 'not_authed' or 'invalid_auth'
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.Gmail: 'insufficient permissions'
Gmail: 'insufficient permissions'
The Gmail OAuth scope is missing. Disconnect the integration → reconnect and make sure to approve all requested scopes when prompted.
GitHub: '404 Not Found' on tool calls
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.
Stripe: 'No such customer'
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.Revoking access
To disconnect a channel or integration:- Open Channels or Integrations in your bot dashboard
- Click the connected item → Disconnect
- Confirm — Bothive deletes the stored credential