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:- The capability name (e.g.,
crm.getContact) - The HTTP method and URL
- The authentication method
- The request/response schema
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 Integrations → Custom → New 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
Use the integration test runner
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
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
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.”