> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LeadSquared Integration

> Automatically call new leads from your LeadSquared CRM

## Overview

Connect your LeadSquared CRM to automatically trigger AI calls when new leads are created. Configure your agent to call leads with custom data mapping and call scheduling parameters.

**How It Works:**

1. Connect LeadSquared account
2. Configure agent variable mapping
3. Add webhook URL to LeadSquared
4. New leads automatically trigger calls

***

## Step 1: Connect LeadSquared Account

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Dashboard → Integrations**
  </Step>

  <Step title="Find LeadSquared">
    Locate **LeadSquared** in the available integrations
  </Step>

  <Step title="Click Connect">
    Click the **"Connect"** button
  </Step>

  <Step title="Enter Credentials">
    Fill in the required fields:

    **Host URL**

    * Your LeadSquared API endpoint
    * Example: `https://api-in21.leadsquared.com`
    * Find this in your LeadSquared account settings

    **Access Key**

    * Your LeadSquared access key
    * Found in Settings → API & Webhooks

    **Secret Key**

    * Your LeadSquared secret key
    * Keep this secure and never share
  </Step>

  <Step title="Save Connection">
    Click **"Connect"** to save your credentials
  </Step>
</Steps>

<Note>
  Your credentials are stored securely and used only for API communication with LeadSquared.
</Note>

***

## Step 2: Configure Agent Variable Mapping

Map your agent's call metadata variables to LeadSquared lead fields.

<Steps>
  <Step title="Go to Agent Configuration">
    Navigate to the agent you want to configure for LeadSquared leads
  </Step>

  <Step title="Open Variable Source Tab">
    Click on the **"Variable Source"** tab in agent settings
  </Step>

  <Step title="Add Variable Mapping">
    For each call metadata variable:

    1. Click **"Add Variable"**
    2. Enter **Variable Name** (e.g., `name`, `phone`, `email`)
    3. Select **Source**: `leadsquared`
    4. Select **LeadSquared Field** from dropdown
    5. Choose **Format** if needed (optional)
  </Step>
</Steps>

### Variable Mapping Example

```
Call Metadata Variable → LeadSquared Field
-----------------------------------------------
name                   → ProspectName
phone                  → Phone
email                  → EmailAddress
company                → Company
city                   → City
```

<Tip>
  The agent will receive these values from LeadSquared when a call is triggered, using them during the conversation.
</Tip>

***

## Step 3: Generate Webhook URL

Your webhook URL follows this format:

```
https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared
```

### Authentication

The webhook requires authentication. You can provide your API key in **two ways**:

**Option 1: Query Parameter**

```
https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY
```

**Option 2: Header**

* Add header: `X-API-KEY: YOUR_API_KEY`
* Use this when query parameter is not preferred

<Note>
  Your API key can be found in **Dashboard → API Keys**
</Note>

### Get Your Agent ID

1. Go to your agent's configuration page
2. Look in the URL or agent settings
3. Copy the agent ID

**Complete Example URL (with API key):**

```
https://api.callkaro.ai/call/crm-webhook?agent_id=6803fa770b666a64ab1694c1e&type=leadsquared&x_api_key=ck_1234567890abcdef
```

***

## Step 4: Configure Webhook in LeadSquared

<Steps>
  <Step title="Log into LeadSquared">
    Access your LeadSquared account
  </Step>

  <Step title="Go to Webhooks">
    Navigate to **Settings → API & Webhooks → Webhooks**
  </Step>

  <Step title="Create New Webhook">
    Click **"Create Webhook"** or **"Add Webhook"**
  </Step>

  <Step title="Enter Webhook URL">
    Paste your Callkaro webhook URL with agent ID and API key

    **Using Query Parameter (Recommended):**

    ```
    https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY
    ```
  </Step>

  <Step title="Add Authentication (If Using Header)">
    If you prefer header authentication:

    1. Enter webhook URL without `x_api_key` parameter
    2. Add custom header in LeadSquared:
       * **Header Name:** `X-API-KEY`
       * **Header Value:** Your Callkaro API key
  </Step>

  <Step title="Set Content-Type to JSON">
    **Important:** Set the Content-Type to `application/json`

    1. Look for **"Content-Type"** or **"Request Format"** setting
    2. Select **`application/json`** from the dropdown
    3. Do NOT use `form` or `application/x-www-form-urlencoded`

    <Warning>
      LeadSquared often defaults to `form` - you MUST change this to `application/json` or the webhook will fail.
    </Warning>
  </Step>

  <Step title="Select Trigger Event">
    Choose **"Lead Created"** or relevant trigger event
  </Step>

  <Step title="Save Webhook">
    Click **"Save"** to activate the webhook
  </Step>
</Steps>

***

## Advanced Parameters

Add optional parameters to your webhook URL to control call behavior.

### Available Parameters

| Parameter             | Format         | Description                                            | Example |
| --------------------- | -------------- | ------------------------------------------------------ | ------- |
| `min_trigger_time`    | `HH:MM`        | Earliest time to trigger calls (24-hour format)        | `09:00` |
| `max_trigger_time`    | `HH:MM`        | Latest time to trigger calls (24-hour format)          | `18:00` |
| `carry_over`          | `true`/`false` | Whether to carry over calls outside window to next day | `true`  |
| `num_of_retries`      | Number         | Total number of retry attempts if call fails           | `3`     |
| `gap_between_retries` | `X,Y,Z`        | Gap in hours between retries (comma-separated)         | `2,4,6` |

### Parameter Examples

<Tabs>
  <Tab title="Basic Call Window">
    **Configure calls between 9 AM and 6 PM:**

    ```
    https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY&min_trigger_time=09:00&max_trigger_time=18:00
    ```
  </Tab>

  <Tab title="With Retries">
    **Call window + 3 retries with increasing gaps:**

    ```
    https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY&min_trigger_time=09:00&max_trigger_time=18:00&num_of_retries=3&gap_between_retries=2,4,8
    ```

    **Retry Schedule:**

    * Call 1: Lead created time
    * Call 2: 2 hours after first call (if failed)
    * Call 3: 4 hours after second call (if failed)
    * Call 4: 8 hours after third call (if failed)
  </Tab>

  <Tab title="With Carry Over">
    **Carry over missed calls to next day:**

    ```
    https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY&min_trigger_time=09:00&max_trigger_time=18:00&carry_over=true
    ```

    **Behavior:**

    * Lead created at 8:00 PM (outside window)
    * With `carry_over=true`: Call scheduled for 9:00 AM next day
    * With `carry_over=false`: Call attempt immediately (may fail)
  </Tab>

  <Tab title="Complete Configuration">
    **All parameters combined:**

    ```
    https://api.callkaro.ai/call/crm-webhook?agent_id=YOUR_AGENT_ID&type=leadsquared&x_api_key=YOUR_API_KEY&min_trigger_time=09:00&max_trigger_time=18:00&carry_over=true&num_of_retries=3&gap_between_retries=2,3,3
    ```
  </Tab>
</Tabs>

***

## Parameter Details

### min\_trigger\_time & max\_trigger\_time

**Format:** `HH:MM` (24-hour format)

**Purpose:** Define the calling window for your campaigns

**Examples:**

* `09:00` - 9:00 AM
* `13:30` - 1:30 PM
* `18:00` - 6:00 PM

<Warning>
  Calls triggered outside this window will be handled based on `carry_over` setting.
</Warning>

***

### carry\_over

**Format:** `true` or `false`

**Purpose:** Determines behavior for leads created outside calling hours

**Options:**

* `true`: Schedule call for next available time within window
* `false`: Attempt call immediately (may fail if outside hours)

**Example Scenario:**

```
Settings:
min_trigger_time=09:00
max_trigger_time=18:00
carry_over=true

Lead created: 7:00 PM (outside window)
Result: Call scheduled for 9:00 AM next day
```

***

### num\_of\_retries

**Format:** Number (integer)

**Purpose:** Total number of retry attempts if call fails

**Valid Values:** `0` to `10`

**Examples:**

* `0` - No retries, single call attempt
* `1` - One retry (2 total attempts)
* `3` - Three retries (4 total attempts)

***

### gap\_between\_retries

**Format:** Comma-separated hours `X,Y,Z`

**Purpose:** Time gaps between retry attempts

**Important:**

* Number of values must equal `num_of_retries`
* Values in hours
* No spaces between commas

**Examples:**

<Tabs>
  <Tab title="Equal Gaps">
    ```
    num_of_retries=3
    gap_between_retries=2,2,2
    ```

    **Schedule:**

    * Attempt 1: Lead created time
    * Attempt 2: +2 hours
    * Attempt 3: +2 hours
    * Attempt 4: +2 hours
  </Tab>

  <Tab title="Increasing Gaps">
    ```
    num_of_retries=3
    gap_between_retries=1,3,6
    ```

    **Schedule:**

    * Attempt 1: Lead created time
    * Attempt 2: +1 hour
    * Attempt 3: +3 hours
    * Attempt 4: +6 hours
  </Tab>

  <Tab title="Custom Pattern">
    ```
    num_of_retries=4
    gap_between_retries=2,4,6,12
    ```

    **Schedule:**

    * Attempt 1: 10:00 AM (lead created)
    * Attempt 2: 12:00 PM (+2 hours)
    * Attempt 3: 4:00 PM (+4 hours)
    * Attempt 4: 10:00 PM (+6 hours)
    * Attempt 5: 10:00 AM next day (+12 hours)
  </Tab>
</Tabs>

<Warning>
  Ensure the number of gap values matches `num_of_retries` exactly, or the webhook will fail.
</Warning>

***

## Complete Setup Example

### Scenario: Sales Team Lead Calls

**Requirements:**

* Call new leads automatically
* Business hours: 9 AM to 6 PM
* Retry failed calls 3 times
* Increasing gaps: 2, 4, 6 hours
* Carry over evening leads to next morning

**Webhook URL:**

```
https://api.callkaro.ai/call/crm-webhook?agent_id=6803fa770b666a64ab1694c1e&type=leadsquared&x_api_key=ck_1234567890abcdef&min_trigger_time=09:00&max_trigger_time=18:00&carry_over=true&num_of_retries=3&gap_between_retries=2,4,6
```

**Variable Mapping:**

| Call Metadata      | LeadSquared Field     |
| ------------------ | --------------------- |
| `name`             | `ProspectName`        |
| `phone`            | `Phone`               |
| `email`            | `EmailAddress`        |
| `company`          | `Company`             |
| `product_interest` | `mx_Product_Interest` |

**Result:**

* Lead created at 10 AM → Call at 10 AM
* Lead created at 7 PM → Call at 9 AM next day
* Failed calls retry: +2h, +4h, +6h
* Agent has access to all mapped fields during call

***

## Testing Your Integration

<Steps>
  <Step title="Create Test Lead">
    Create a test lead in LeadSquared with sample data
  </Step>

  <Step title="Check Webhook Trigger">
    Verify LeadSquared webhook fires successfully
  </Step>

  <Step title="Monitor Call">
    Check Callkaro dashboard for triggered call
  </Step>

  <Step title="Review Data">
    Confirm agent received correct lead data during call
  </Step>

  <Step title="Test Retries">
    Test retry behavior by marking call as failed
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Calls not triggering" icon="phone-slash">
    **Possible causes:**

    * Webhook URL incorrect
    * Agent ID wrong
    * LeadSquared webhook not saved
    * LeadSquared credentials invalid

    **Solutions:**

    1. Verify webhook URL format
    2. Check agent ID is correct
    3. Confirm webhook is active in LeadSquared
    4. Test LeadSquared credentials in Integrations page
  </Accordion>

  <Accordion title="Variables not mapping" icon="circle-exclamation">
    **Issue:** Agent doesn't receive lead data

    **Solutions:**

    1. Check variable source is set to `leadsquared`
    2. Verify LeadSquared field names are correct
    3. Ensure fields exist in LeadSquared lead
    4. Test with a lead that has all mapped fields
  </Accordion>

  <Accordion title="Calls outside window" icon="clock">
    **Issue:** Calls triggering outside min/max times

    **Solutions:**

    * Check time format is `HH:MM` (24-hour)
    * Verify `carry_over` setting
    * Ensure timezone matches your LeadSquared account
  </Accordion>

  <Accordion title="Retries not working" icon="rotate">
    **Issue:** No retry attempts after failed call

    **Solutions:**

    * Verify `num_of_retries` is set
    * Check `gap_between_retries` count matches retries
    * Ensure proper format: `2,3,4` (no spaces)
    * Confirm call actually failed (not just unanswered)
  </Accordion>

  <Accordion title="Invalid webhook error" icon="triangle-exclamation">
    **Issue:** LeadSquared shows webhook error

    **Solutions:**

    * Check URL has no typos
    * Ensure `type=leadsquared` is included
    * Verify agent\_id is valid
    * Remove any extra spaces or characters
  </Accordion>
</AccordionGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Set Appropriate Call Windows" icon="business-time">
    **Why:** Respect customer availability and increase answer rates

    **Recommendations:**

    * Business hours: `09:00` to `18:00`
    * Avoid early morning and late evening
    * Consider customer timezone
  </Accordion>

  <Accordion title="Use Intelligent Retry Patterns" icon="clock-rotate-left">
    **Why:** Balance persistence with customer experience

    **Good Patterns:**

    * Quick follow-up: `1,2,4` hours
    * Spaced out: `4,8,24` hours
    * Aggressive: `1,1,2` hours

    **Avoid:**

    * Too frequent: `0.5,0.5,0.5` (spam-like)
    * Too long: `24,48,72` (lost interest)
  </Accordion>

  <Accordion title="Enable Carry Over" icon="calendar-day">
    **Why:** Never miss a lead due to timing

    **Best Practice:**

    * Set `carry_over=true` for most campaigns
    * Ensures all leads get called
    * Respects calling hours
  </Accordion>

  <Accordion title="Map Essential Fields Only" icon="list-check">
    **Why:** Keep agent context focused

    **Essential Fields:**

    * Name (for personalization)
    * Phone (validation)
    * Email (backup contact)
    * Product interest (conversation context)

    **Avoid:**

    * Unnecessary personal data
    * Too many fields (overwhelming)
    * Sensitive information not needed
  </Accordion>
</AccordionGroup>

***

## FAQs

<AccordionGroup>
  <Accordion title="Can I use multiple agents?" icon="users">
    Yes! Create separate webhook URLs for each agent with different agent\_ids.
  </Accordion>

  <Accordion title="What happens if LeadSquared is down?" icon="server">
    Calls won't trigger until LeadSquared service resumes. No data is lost.
  </Accordion>

  <Accordion title="Can I test without creating real leads?" icon="vial">
    Yes, use LeadSquared's webhook test feature or create test leads in a sandbox.
  </Accordion>

  <Accordion title="How do I know if a call was triggered?" icon="bell">
    Check your Callkaro dashboard → Call History for new calls from this agent.
  </Accordion>

  <Accordion title="Can I change parameters later?" icon="edit">
    Yes, simply update the webhook URL in LeadSquared with new parameters.
  </Accordion>
</AccordionGroup>

***

## Getting Help

<CardGroup cols={2}>
  <Card title="Webhook Documentation" icon="webhook" href="/webhook/introduction">
    Learn more about webhooks and call data
  </Card>

  <Card title="Contact Support" icon="headset">
    Get help with LeadSquared integration setup
  </Card>
</CardGroup>