Skip to main content

Custom Integrations

Connect any REST or GraphQL API to your Bothive agents. Custom integrations feel first-class — same experience as native ones.

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:
  1. The capability name (e.g., crm.getContact)
  2. The HTTP method and URL
  3. The authentication method
  4. The request/response schema
Your agent uses capabilities { crm.getContact } in HiveLang — no different from any native integration.

Step-by-step setup

1

Define the capability in HiveLang

Declare what capabilities your custom integration provides:
2

Create the integration in the dashboard

Go to IntegrationsCustomNew Integration.Fill in:
  • Name: CRM Integration
  • Base URL: https://api.yourcrm.com/v2
  • Auth method: API Key / Bearer / OAuth2
3

Define capabilities

For each capability, add an endpoint definition:
4

Set authentication

Choose your auth method:
5

Test the capability

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

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

Authentication reference

Custom integration limits

Testing custom integrations

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.
Every custom integration call appears in the run trace — same as native integrations. Look for the capability name, parameters sent, and response received.
Add explicit rules for when the custom API returns an error: “If crm.getContact returns null, ask the user to confirm their email address.”

Next reads

Integration Capabilities

Build Your First Agent

API Reference