Custom API Integrations — Connecting Your Agent to Any System

If your business uses a tool that isn't in the pre-built integration list, you can connect it as a custom integration. Any system with an HTTP API can become a tool your agent uses during calls.

What Custom Integrations Can Do

Custom integrations are HTTP requests your agent can make during a conversation:

• Look up information — check inventory, verify insurance eligibility, find customer records
• Create records — book appointments in your PMS, create leads in your CRM, submit service requests
• Update records — modify bookings, update customer preferences, change appointment status
• Notify external systems — send webhooks to trigger workflows, alert staff, update dashboards

How They Work

Each custom integration is defined with:

• Name and description — what the tool does (helps the agent decide when to use it)
• HTTP method — GET, POST, PUT, PATCH, DELETE
• URL template — the API endpoint, with optional parameter placeholders
• Parameters — what data the agent collects from the caller and passes to the API
• Authentication — API key, bearer token, or OAuth credentials
• Response mapping — how to extract the useful information from the API response

During a call, when the agent decides it needs to use a custom integration, it:

1. Collects the required parameters from the conversation
2. Builds the HTTP request
3. Sends it to your API
4. Reads the response
5. Continues the conversation with the results

Context Burden Levels

Each integration has a context burden level that controls how the agent decides to use it:

• Ambient — the agent uses it automatically in the background, without mentioning it to the caller
• Conversational — the agent uses it naturally as part of the conversation ("Let me check that for you")
• Requested — the agent only uses it when the caller explicitly asks ("Can you look up my account?")
• Confirmed — the agent asks for confirmation before using it ("I can book that for you — shall I go ahead?")
• Verified — the agent requires identity verification before using it (for sensitive operations)

This gives you fine-grained control over when and how your agent interacts with external systems.

Authentication

Custom integrations support multiple auth methods:

• API Key — passed as a header or query parameter
• Bearer Token — passed in the Authorization header
• OAuth — for integrations that require user-level authorization

Credentials are encrypted with AES-256-GCM and stored securely. They are never exposed in logs, transcripts, or the dashboard.

Correlation Headers

Every outbound HTTP request from a custom integration includes three correlation headers so your endpoint can tie the request back to the call that triggered it:

These are added by Allison automatically — no configuration required, no per-integration parameter setup. If your endpoint cares about the call context (writing breadcrumbs, correlating with your own call log, joining post-call webhook events), read these headers; if it doesn't, ignore them.

On live calls, X-Allison-Org-ID and X-Allison-Tool-Key are always present; X-Allison-Call-ID is sent unless the rare bridge-edge case where the call hasn't been bound yet. Dashboard test invocations (the "Test" button) send none of the three headers — they're not tied to a real call. Receivers should treat all three as optional and fall back gracefully when absent.

Testing

Every custom integration has a built-in test button. You can send a test request with sample parameters and see the full request/response — status code, headers, body, and latency. This lets you verify the integration works before your agent tries to use it on a live call.