> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wittify.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrations & Tools
> Connect your agent to outside services. Browse the marketplace of 21+ apps, plug in MCP connectors, switch on built-in agent tools (handoff, calendar, order tracking, payment), build custom REST API tools, and route real-time webhook events.
Integrations & Tools is **Step 6 (Hybrid)** or **Step 5 (Text / Voice)**. The page has four sections: **Integration Marketplace**, **Agent Tools**, **Custom API Tools**, **Webhooks & Events**. Each section is independent, you can leave any of them empty if you don't need it. The step is optional, you can advance with nothing connected.
## What this step does
This is where you give the agent capabilities beyond just answering questions: send a refund link, look up an order, transfer the conversation to a human, post to Slack the moment a lead is captured. There are four ways to wire those capabilities, listed by how much setup they take:
1. **Marketplace** , one-click OAuth or API key, no code.
2. **Agent Tools** , four built-in tools (Human Handoff, Calendar Booking, Order Tracking, Payment Collection) that you configure with a form.
3. **Custom API Tools** , user-defined REST endpoints. The agent decides when to call them.
4. **Webhooks & Events** , the agent fires HTTP POST notifications to your server when events happen.
## Section 1: Integration Marketplace
A server-driven catalog of apps grouped by category. Each card shows the app's logo, name, a one-line description, a connection status pill, and a colored auth tag (**OAuth** in purple, **API Key** in blue).
### Stats and filters bar
At the top of the marketplace card, a row with three stat chips and a search box:
| Chip | What it counts |
| ------------------ | ------------------------------------------------------- |
| **Available** | Total integrations in the catalog |
| **Enabled** | How many you've already connected |
| **MCP Connectors** | How many Model Context Protocol connectors you've added |
The search box reads **Search integrations...** and filters by name or description. Search input is capped at 120 characters.
A row of filter tabs below the stats:
* **All** , every integration in the catalog (default)
* **Enabled** , only the ones you've connected
* **Native** , Wittify-built integrations (no auth bridge)
* **MCP** , only your MCP connectors
When a filter returns no matches, an empty state reads **No integrations match this filter** with the hint *Try a different search or filter.*
### Connect via OAuth
Click any card with the **OAuth** tag. The button reads **Configure**:
1. Click the card. A popup opens (the click opens it synchronously, so the browser doesn't block it).
2. Authorize on the provider's site (Google, Slack, Calendly, etc.).
3. The provider redirects back to the wizard with a confirmation token in the URL.
4. The connection is finalized server-side, the URL is cleaned up, and the catalog refetches with the card now showing a green **Enabled** pill.
If your browser blocks popups, you'll see a toast: *Popup blocked. Allow popups and try again.* On other failures: *Could not connect integration.*
### Connect via API Key
Click any card with the **API Key** tag. A modal opens with the title **Connect `{App Name}`** and the description *Enter credentials to connect this integration.*
| Field | Notes |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **API Key** | Hidden password field. Placeholder: *Paste your API key.* Autocomplete is off. |
| **Store subdomain** (Shopify only) | Visible only when the app's name contains "Shopify". Hint: *Your Shopify store subdomain (the part before .myshopify.com).* Placeholder: **my-store**. |
Below the form, a security note: *Credentials are sent directly to Composio over HTTPS and stored server-side, never in your browser.* The Connect button is disabled until both fields are filled.
The submit button reads **Connect**. It changes to **Connecting...** with a spinner while the request runs. On success, a toast reads *Integration connected* and the modal closes. On failure: *Could not connect integration*, with the modal staying open so you can fix the credential.
### Disconnect
Click the **Configure** button on a connected card to open the configure panel. The panel shows **Connected**, **Last synced 2 min ago**, and an **Authorized access** summary, plus a trigger picker:
| Trigger | When the integration fires |
| -------------------------------- | ------------------------------------------- |
| **Conversation ended** (default) | After the agent says goodbye |
| **Lead captured** | The moment the agent finishes the lead form |
| **Human handoff requested** | Whenever the agent transfers to a human |
Two buttons at the bottom: **Save Settings** (primary) and **Disconnect** (red border).
Clicking Disconnect opens a confirmation: *Are you sure you want to disconnect {Name}? Your agent will no longer be able to use this integration.* Cancel to keep, or click the red **Disconnect** to remove. A success toast reads *Integration disconnected.*
### MCP add card
Below the marketplace grid, a dashed "Add MCP Connector" card lets you wire any service that speaks the **Model Context Protocol** (a standard way for tools to expose themselves to AI agents). Click the card to open the **Add MCP Connector** modal, with the subtitle *Connect any external system via Model Context Protocol*:
| Field | Notes |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Name** (required) | Up to 100 characters, displayed on the card |
| **URL** (required) | Must be HTTPS. Error message: *Must be a valid HTTPS URL.* |
| **Timeout** | Number in milliseconds. Hint: *In milliseconds. Leave blank for default (30,000ms).* |
| **Headers** | Key/value pairs, up to 20. Click **+ New Key Value Pair** to add another row. Click the trash icon to remove. |
| **Query** | Same shape as Headers. |
Required fields are marked with a red asterisk. The submit button reads **Create MCP** for new connectors, **Save Changes** when you're editing.
After creating, the connector appears as a card in the marketplace grid alongside the other integrations, with **MCP** as its tag color (blue). Each MCP card has two icon buttons in the corner: **Edit** (pencil) reopens the modal in edit mode, **Delete** (trash) opens a confirmation: *Are you sure you want to delete "{Name}"? This action cannot be undone.*
Toasts: *MCP connector created*, *MCP connector updated*, *MCP connector deleted* on success. Failures show *Could not save MCP connector*, *Could not update MCP connector*, *Could not delete MCP connector*.
### When the marketplace can't load
If the catalog fetch fails, the section shows an inline error: **Couldn't load integrations** with the hint *The server rejected the request. Check your connection and try again*, plus a **Retry** button.
## Section 2: Agent Tools
Four built-in tools your agent can invoke during a conversation. The card title reads **Agent Tools** with the description *Built-in capabilities your agent can use during conversations.*
Each tool is rendered as a row with an icon, name, description, and a switch on the end. Switch off (default for all four): the row is muted. Switch on: the row gets a primary tinted background and an expanded form opens below with that tool's settings.
### Human Handoff
Description: *Transfer conversations to a live support agent when needed.*
| Setting | Options |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Handoff Trigger** | **Customer requests it**, **Agent decides**, **Both** (chip group) |
| **Routing Channel** | **Email notification**, **Webhook**, **Live chat URL** |
| Target field | Auto-renames based on channel: **Notification Email** (e.g. `support@company.com`), **Webhook URL** (e.g. `https://your-server.com/handoff`), or **Live Chat URL** (e.g. `https://livechat.company.com`). HTTPS validation applies for the latter two. |
| **Unavailable Message** | Multi-line text. Up to 500 characters. Default placeholder: *Our team is currently offline. We'll get back to you as soon as possible.* |
### Calendar Booking
Description: *Schedule meetings and appointments for customers.*
| Setting | Notes |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Booking Page URL** | HTTPS required. Hint: *Link to your scheduling page (Calendly, Cal.com, or custom).* Placeholder: `https://calendly.com/your-name`. |
| **Meeting Durations** | Three checkboxes: **15 minutes**, **30 minutes**, **60 minutes**. Pick whichever the agent should offer. |
### Order Tracking
Description: *Look up and share order status with customers.*
| Setting | Notes |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lookup API Endpoint** | HTTPS required. Hint: *REST API endpoint to query order status.* Placeholder: `https://api.yourstore.com/v1/orders`. Rendered in a monospace font. |
| **HTTP Method** | Dropdown with **GET** or **POST**. |
| **Auth Header Value** | Hidden password field. Placeholder: `Bearer your-api-key`. Autocomplete off. |
| **Customer Lookup Fields** | Three checkboxes: **Order ID**, **Email**, **Phone**. The agent will ask the customer for whichever one(s) you check. |
### Payment Collection
Description: *Send payment links and process transactions.*
| Setting | Notes |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Payment Page URL** | HTTPS required. Hint: *Base URL for your payment or checkout page.* Placeholder: `https://checkout.stripe.com/pay/...`. |
| **Default Currency** | Dropdown of currencies, formatted as `USD - US Dollar`, `EUR - Euro`, etc. |
## Section 3: Custom API Tools
Define your own REST endpoints that the agent can call mid-conversation. Card title reads **Custom API Tools** with the description *Define custom REST API endpoints your agent can call during conversations.*
When the list is empty, you see a centered code icon and the line **No custom tools added yet.** Below, the **+ Add tool** button is dashed-bordered.
### Add tool form
Click **+ Add tool** to open the inline form:
| Field | Notes |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Tool name** | Up to 50 characters. Placeholder: `e.g. Check inventory`. |
| **Method** | Dropdown of **GET**, **POST**, **PUT**, **PATCH**, **DELETE**. |
| **Endpoint URL** | HTTPS required. Placeholder: `https://api.example.com/v1/resource`. Error message when invalid: *Must be a valid HTTPS URL.* |
| **Description** | Up to 200 characters. Placeholder: *Describe what this tool does...* |
Two buttons at the bottom: **Cancel** (clears the form) and **Add tool** (the primary button, disabled until name and a valid HTTPS endpoint are filled).
### Tool list
Each saved tool appears as a row with the HTTP method in a small monospace pill, the tool name in bold, the endpoint underneath, and an optional description below that. A trash icon on the end removes it after a confirmation: **Remove custom tool** , *Are you sure you want to remove "{Name}"? This action cannot be undone.*
| Limit | Value |
| ---------------- | ---------------- |
| Max custom tools | **10** per agent |
When you reach 10 tools, the **+ Add tool** button is replaced by the line *Maximum 10 custom tools.*
## Section 4: Webhooks & Events
The agent's outbound notifications. Card title reads **Webhooks & Events** with the description *Send real-time HTTP POST notifications when events occur in your agent.*
Five event rows, each with its own icon, label, and switch:
| Event | Icon | When it fires |
| --------------------------- | ----------------- | ------------------------------------ |
| **Conversation Started** | speech bubble | The customer sends the first message |
| **Conversation Ended** | check circle | The agent or customer ends the chat |
| **Human Handoff Requested** | left/right arrows | The Human Handoff tool fires |
| **Lead Captured** | user plus | The agent finishes a lead form |
| **Ticket Created** | document | The agent files a support ticket |
When you switch a row on, a **Webhook URL** input appears below. Placeholder: `https://your-server.com/webhook`. HTTPS required. Error message when invalid: *Must be a valid HTTPS URL.*
The events are independent, switch on whichever you need.
## How saves work on this step
| Setting type | When it persists |
| --------------------------- | ----------------------------------------------- |
| Marketplace OAuth / API key | Immediately on the redirect / submit |
| Marketplace disconnect | Immediately on the confirm dialog |
| MCP create / edit / delete | Immediately, with a toast on success or failure |
| Agent Tools fields | When you click **Save Draft** or **Next step** |
| Custom API Tools | Same as Agent Tools |
| Webhooks & Events | Same as Agent Tools |
If a Webhook URL or Agent Tool URL is invalid (must start with `https://`), the save is allowed but the agent won't be able to fire that webhook until you fix it. The red error text under the field is your hint.
## Common questions
The full marketplace appears once you save the wizard for the first time. Click **Save Draft** on the first wizard step (or click **Next**) to unlock it.
Two common causes: (1) the popup was blocked, look for a toast or check your browser's popup settings. (2) The provider's authorization page rejected the request, try again from the marketplace card.
The button stays disabled until you have a non-empty **Tool name** and a valid HTTPS **Endpoint URL**. Description and method are optional and have defaults.
Three checks: (1) the event's switch is **on**, (2) the URL passes HTTPS validation (no red error text), (3) your server actually accepts POST requests at that path. Wittify retries failed deliveries, but the URL has to be reachable in the first place. Test it with `curl -X POST https://your-server.com/webhook` from a terminal.
MCP is a richer protocol , the connector exposes a list of available tools and the agent decides which to call based on conversation context. Custom API Tools are simpler, you define each endpoint individually and write a description telling the agent when to use it. Use MCP for systems that expose multiple capabilities (e.g. a CRM with read/write/search), use Custom API Tools for one-off endpoints.
You can't delete it, but you can switch it off. The form below the row stays available, but the agent won't invoke the tool while the switch is off.
The agent uses any of the checked fields. When more than one is on, it picks based on conversation context (e.g. if the customer mentions they don't remember the order ID, it falls back to Email). If you want a specific lookup field always used, leave just that one checked.
## Next
Embed on your website, connect social channels, plug in telephony, manage allowed domains, activate your agent.