> ## 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.

# Custom Integrations

> Connect any REST or GraphQL API to your Bothive agents.

## When to build custom vs use native

<CardGroup cols={2}>
  <Card title="Use a native integration when..." icon="check" className="glass-effect">
    * The service is in Bothive's 25+ integration list
    * OAuth is managed for you
    * The capability covers your use case
    * You want zero maintenance
  </Card>

  <Card title="Build a custom integration when..." icon="wrench" className="glass-effect">
    * 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
  </Card>
</CardGroup>

## 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

<Steps>
  <Step title="Define the capability in HiveLang">
    Declare what capabilities your custom integration provides:

    ```hivelang theme={null}
    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.
      }
    }
    ```
  </Step>

  <Step title="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
  </Step>

  <Step title="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 }` |
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Test the capability">
    In the Integration dashboard → **Test** → enter sample parameters → run the test call. Verify the response matches expected schema.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Example — internal CRM integration

```hivelang theme={null}
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 |

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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."
  </Accordion>
</AccordionGroup>

## Next reads

<CardGroup cols={3}>
  <Card title="Integration Capabilities" icon="list" href="./integration-capabilities" className="glass-effect" />

  <Card title="Build Your First Agent" icon="hammer" href="./build-your-first-agent" className="glass-effect" />

  <Card title="API Reference" icon="code" href="../api/overview" className="glass-effect" />
</CardGroup>