Custom Integrations

When to build custom vs use native

Use a native integration when...

The service is in Bothive’s 25+ integration list
OAuth is managed for you
The capability covers your use case
You want zero maintenance

Build a custom integration when...

You’re connecting your own internal API
The service isn’t natively supported yet
You need a custom schema or subset of endpoints
You want full control over what the agent can access

How custom integrations work

A custom integration is a named capability that maps to an HTTP endpoint. You define:

The capability name (e.g., crm.getContact)
The HTTP method and URL
The authentication method
The request/response schema

Your agent uses capabilities { crm.getContact } in HiveLang — no different from any native integration.

Step-by-step setup

Define the capability in HiveLang

Declare what capabilities your custom integration provides:

bot CRMBot {
  description: "Reads customer data from our CRM"

  capabilities {
    crm.getContact
    crm.updateContact
    crm.getDeals
  }

  instructions {
    Look up customer data before answering account questions.
    Never modify a contact without explicit user confirmation.
  }
}

Create the integration in the dashboard

Go to Integrations → Custom → New Integration.Fill in:

Name: CRM Integration
Base URL: https://api.yourcrm.com/v2
Auth method: API Key / Bearer / OAuth2

Define capabilities

For each capability, add an endpoint definition:

Field	Example
Capability name	`crm.getContact`
HTTP method	`GET`
Path	`/contacts/{contact_id}`
Parameters	`contact_id: string`
Response mapping	`{ name, email, plan, company }`

Set authentication

Choose your auth method:

API Key:   X-API-Key: {env.CRM_API_KEY}
Bearer:    Authorization: Bearer {env.CRM_TOKEN}
OAuth2:    Managed OAuth flow with token refresh

Test the capability

In the Integration dashboard → Test → enter sample parameters → run the test call. Verify the response matches expected schema.

Deploy and test in the agent

Deploy your HiveLang bot. Ask the agent to use the capability. Check the run trace to confirm the custom endpoint was called correctly.

Example — internal CRM integration

bot SalesAssistant {
  description: "Reads deal and contact data from our internal CRM"

  capabilities {
    crm.getContact
    crm.getDeals
    crm.addNote
    gmail.sendEmail
  }

  instructions {
    You are a sales assistant. Before answering account questions:
    1. Look up the contact in the CRM using their email
    2. Check their active deals and stage
    3. Answer based on real CRM data — never guess

    When asked to add a note, confirm the content before calling crm.addNote.
    When sending emails, always create a draft first unless told to send directly.
  }

  on "brief me on *" {
    contact = call crm.getContact with { email: $match[0] }
    deals = call crm.getDeals with { contact_id: contact.id }
    say "Contact: *{contact.name}* ({contact.company})\nPlan: {contact.plan}\nOpen deals: {deals.length}\nLatest deal stage: {deals[0].stage}"
  }
}

Authentication reference

Method	When to use	How Bothive handles it
API Key	Static key that doesn’t expire	Stored encrypted, injected per request
Bearer Token	Short-lived tokens	Stored encrypted, injected per request
OAuth 2.0 (Client Credentials)	Service-to-service	Token refresh handled automatically
OAuth 2.0 (Auth Code)	User-authorized access	Full OAuth flow + token refresh
Basic Auth	Legacy APIs	Username/password encoded and injected

Model Context Protocol (MCP) Servers

Bothive is fully compatible with the open standard Model Context Protocol (MCP). Instead of defining HTTP endpoints and schemas manually in the dashboard, you can connect an existing MCP server. Bothive will automatically discover its tools and expose them as HiveLang capabilities.

Provide your MCP server URL

In the Integration dashboard → Custom → Connect MCP Server, provide your SSE endpoint or WebSocket URL.

Automatic capability discovery

Bothive connects to the server and automatically reads the tool definitions. Every MCP tool becomes a capability prefixed with your server name (e.g., myserver.get_weather).

Use in your agent

bot WeatherAgent {
  capabilities {
    myserver.get_weather
  }
  
  on "What's the weather in {city}?" {
    data = call myserver.get_weather with { location: city }
    say "It's {data.temp} degrees."
  }
}

Custom integration limits

Plan	Custom integrations	Requests/day
Free	2	500
Pro	10	10,000
Business	Unlimited	100,000
Enterprise	Unlimited	Custom

Testing custom integrations

Use the integration test runner

In the integration dashboard, you can run live test calls against your endpoints with sample parameters. This lets you verify the schema before connecting to an agent.

Check the trace for custom calls

Every custom integration call appears in the run trace — same as native integrations. Look for the capability name, parameters sent, and response received.

Handle errors in your instructions

Add explicit rules for when the custom API returns an error: “If crm.getContact returns null, ask the user to confirm their email address.”

Start Here

Getting Started

Core Concepts

Building Agents

Deployment & Operations

Teams & Organisations

Integrations

API Reference

Resources

Custom Integrations

When to build custom vs use native

Use a native integration when...

Build a custom integration when...

How custom integrations work

Step-by-step setup

Example — internal CRM integration

Authentication reference

Model Context Protocol (MCP) Servers

Custom integration limits

Testing custom integrations

Next reads

Integration Capabilities

Build Your First Agent

API Reference

​When to build custom vs use native

Use a native integration when...

Build a custom integration when...

​How custom integrations work

​Step-by-step setup

​Example — internal CRM integration

​Authentication reference

​Model Context Protocol (MCP) Servers

​Custom integration limits

​Testing custom integrations

​Next reads

Integration Capabilities

Build Your First Agent

API Reference

When to build custom vs use native

How custom integrations work

Step-by-step setup

Example — internal CRM integration

Authentication reference

Model Context Protocol (MCP) Servers

Custom integration limits

Testing custom integrations

Next reads