# Add Integrations

Connect your AI voice agents to CRMs, calendars, and other business tools

Integrations allow your AI voice agents to interact with external services in real-time during calls. Your agent can look up customer information, schedule appointments, create tickets, and much more.

## Overview

urvo integrations work by connecting your workspace to third-party services. Once connected, you can enable specific tools that your agents can use during conversations. The agent will automatically call these tools when appropriate based on the conversation context.

**What you'll learn:**
- How to connect integrations to your workspace
- Available authentication methods
- How to enable and configure tools
- How to assign tools to agents

## Prerequisites

Before connecting an integration, ensure you have:
- Admin or Owner role in your workspace
- Access to the third-party service's admin panel
- API credentials or OAuth permissions for the service

## Connecting an Integration

### Step 1: Navigate to Integrations

1. Log in to your urvo dashboard
2. Click **"Integrations"** in the left sidebar
3. You'll see a list of available integrations organized by category

### Step 2: Select Your Integration

Browse integrations by category:
- **CRM** - GoHighLevel, HubSpot, Salesforce
- **Calendar** - Cal.com, Google Calendar
- **Productivity** - Google Sheets, Slack, Notion
- **Support** - Zendesk

Click **"Connect"** on the integration you want to add.

### Step 3: Authenticate

Depending on the integration, you'll use one of these authentication methods:

#### OAuth 2.0 (Recommended)
For services like GoHighLevel, Google, and Salesforce:
1. Click **"Connect with [Service]"**
2. You'll be redirected to the service's login page
3. Log in and authorize urvo
4. You'll be redirected back to urvo automatically

#### API Key
For services like Cal.com, HubSpot, and Stripe:
1. Get your API key from the service's settings
2. Paste the key into the API Key field
3. Click **"Validate"** to test the connection
4. Click **"Save"** to complete setup

#### OAuth 2.0 Client Credentials
For enterprise services requiring client credentials:
1. Enter your **Client ID**
2. Enter your **Client Secret**
3. Enter the **Token URL** (e.g., `https://api.service.com/oauth/token`)
4. Optionally add scopes and extra parameters
5. Click **"Connect"**

### Step 4: Enable Tools

After connecting, you can enable specific tools for your agents:

1. Go to **Agent Settings** → **Tools**
2. Click **"Add Tool"**
3. Select an integration tool from the dropdown
4. Configure any tool-specific settings
5. Click **"Save"**

### Step 5: Test the Integration

Before going live, test your integration:
1. Use the **"Test Agent"** feature
2. Have a conversation that would trigger the tool
3. Verify the tool executed correctly in the call transcript

## Authentication Methods

### OAuth 2.0 Authorization Code

The most secure method for user-facing services. urvo redirects you to the service to grant permission, then receives an access token automatically.

**Supported by:** GoHighLevel, Google (Sheets, Calendar, Gmail), Salesforce

**How it works:**
1. You authorize urvo in the service's interface
2. urvo receives an authorization code
3. urvo exchanges the code for access and refresh tokens
4. Tokens are encrypted and stored securely
5. urvo automatically refreshes tokens before they expire

### API Key Authentication

Simple key-based authentication for services that provide API keys.

**Supported by:** Cal.com, HubSpot, Stripe, OpenAI

**How it works:**
1. Generate an API key in the service's dashboard
2. Paste the key into urvo
3. urvo validates the key with a test API call
4. The key is encrypted and stored securely

### OAuth 2.0 Client Credentials

Machine-to-machine authentication for enterprise services.

**Supported by:** Salesforce (Service Account), custom APIs

**Required fields:**
- Client ID
- Client Secret
- Token URL
- Scopes (optional)

## Managing Connections

### Viewing Connected Integrations

1. Go to **Integrations** in your dashboard
2. Connected integrations show a green "Connected" badge
3. Click on a connection to see details

### Updating Credentials

If your credentials expire or change:
1. Go to **Integrations** → Select the integration
2. Click **"Update Credentials"**
3. Follow the authentication flow again

### Disconnecting an Integration

1. Go to **Integrations** → Select the integration
2. Click **"Disconnect"**
3. Confirm the disconnection

Note: Disconnecting removes all credentials and disables associated tools.

## Adding Tools to Agents

### Available Tool Types

Integration tools are pre-configured by urvo to work with connected services. Common tool types include:

| Category | Tools |
|---|---|
| **CRM** | Create Contact, Update Contact, Search Contacts, Add Note |
| **Calendar** | Check Availability, Book Appointment, Cancel Appointment |
| **Sheets** | Read Row, Write Row, Search Sheet, Append Row |
| **Support** | Create Ticket, Update Ticket, Search Knowledge Base |

### Configuring Tool Parameters

Some tools have configurable parameters:

1. **Required Parameters** - Must be provided by the caller or agent
2. **Default Values** - Pre-filled values you can customize
3. **Dynamic Parameters** - Extracted from the conversation automatically

Example - Book Appointment tool:
- `calendar_id` - Your calendar ID (default value)
- `event_name` - Extracted from conversation
- `date_time` - Extracted from conversation
- `attendee_email` - Extracted from conversation

### Tool Execution During Calls

When a tool is called during a conversation:

1. The agent recognizes the need for the tool
2. urvo's proxy server calls the integration API
3. Authentication is handled automatically
4. Results are returned to the agent
5. The agent incorporates the response into the conversation

## Best Practices

### Security

- Use OAuth 2.0 when available (more secure than API keys)
- Regularly rotate API keys
- Grant minimum required permissions
- Review connected integrations periodically

### Performance

- Enable only the tools your agent needs
- Use specific tool descriptions to help the agent
- Test tools before going live

### Reliability

- Monitor integration health in the dashboard
- Set up alerts for failed tool calls
- Have fallback responses when tools are unavailable

## Troubleshooting

### Connection Failed

1. Verify your credentials are correct
2. Check if the service is experiencing outages
3. Ensure you have the required permissions
4. Try disconnecting and reconnecting

### Tool Not Working

1. Check the tool is enabled for the agent
2. Verify the integration is still connected
3. Review the agent's tool configuration
4. Check API rate limits haven't been exceeded

### Token Expired

OAuth tokens expire periodically. urvo automatically refreshes them, but if issues occur:
1. Go to **Integrations**
2. Click **"Refresh"** on the connection
3. If that fails, reconnect the integration

## Next Steps

- View the [Integrations Overview](/integrations) for details on specific integrations
- Learn about [Agent Configuration](/how-to/configure-agent) to optimize tool usage
- Check [Best Practices](/guides/best-practices) for integration tips

## Next Steps

With integrations set up, you're ready to:

- [Monitor calls and performance](/how-to/analyze-calls)
- Set up advanced workflows and automations
- Configure custom integrations for your specific tools
- Train your team on integration management