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

# KeyCRM with CostCare AI

> Learn how to connect KeyCRM with CostCare AI, trigger AI-agent processing from a KeyCRM pipeline stage, and escalate leads back to a manager.

# KeyCRM with CostCare AI

Connect KeyCRM with CostCare AI to automate lead processing with AI agents and keep your KeyCRM pipeline updated.

With this integration, CostCare AI can receive signals from KeyCRM when a lead moves to a specific pipeline stage. This signal starts the AI-agent workflow. If the AI agent needs help from a real manager, CostCare AI can move the lead card in KeyCRM to a dedicated manager stage.

<Info>
  CostCare AI listens to webhook events from KeyCRM and can update the lead card stage in KeyCRM when the AI agent escalates the lead to a manager.
</Info>

## How the integration works

The integration works with KeyCRM pipeline stages and webhook events.

There are two main flows:

<CardGroup cols={2}>
  <Card title="KeyCRM to CostCare AI" icon="webhook">
    When a lead moves to a specific stage in KeyCRM, KeyCRM sends a webhook signal to CostCare AI. This signal tells the AI agent to start processing the lead.
  </Card>

  <Card title="CostCare AI to KeyCRM" icon="diagram-project">
    When the AI agent escalates a lead to a real manager, CostCare AI can move the lead card in KeyCRM to a dedicated stage, such as “Manager work”.
  </Card>
</CardGroup>

## Lead processing flow

<Steps>
  <Step title="Lead is created or updated in KeyCRM">
    A lead exists in your KeyCRM pipeline and contains the information your team uses during the sales process.
  </Step>

  <Step title="Lead moves to the AI-processing stage">
    A manager or automation moves the lead to the stage where AI processing should begin.
  </Step>

  <Step title="KeyCRM sends a webhook to CostCare AI">
    KeyCRM sends the lead data and stage-change event to the webhook URL generated in CostCare AI.
  </Step>

  <Step title="AI agent starts processing">
    CostCare AI receives the webhook signal and starts the AI-agent workflow for this lead.
  </Step>

  <Step title="AI agent continues or escalates">
    If the AI agent has enough information, it continues processing the lead according to the configured scenario. If the agent does not have enough information or the conversation requires human support, it can escalate the lead to a real manager.
  </Step>

  <Step title="Lead is moved to the manager stage in KeyCRM">
    During escalation, CostCare AI can move the lead card to a dedicated stage in KeyCRM, for example “Manager work”.
  </Step>
</Steps>

<Note>
  The manager escalation stage must be created in KeyCRM before you configure the AI agent to transfer leads to this stage.
</Note>

## Before you start

Before connecting KeyCRM to CostCare AI, make sure you have:

<CardGroup cols={2}>
  <Card title="Access to CostCare AI" icon="user">
    You need access to your CostCare AI workspace and the Integrations section.
  </Card>

  <Card title="Access to KeyCRM" icon="key">
    You need access to the KeyCRM account where your leads and sales pipelines are managed.
  </Card>

  <Card title="KeyCRM API key" icon="lock">
    You need a KeyCRM API key to connect your account with CostCare AI.
  </Card>

  <Card title="AI-processing stage" icon="diagram-project">
    Decide which KeyCRM stage should trigger the AI agent to start processing the lead.
  </Card>

  <Card title="Manager escalation stage" icon="user-headset">
    Create a dedicated stage in KeyCRM where leads should be moved when the AI agent escalates them to a real manager.
  </Card>
</CardGroup>

## Recommended KeyCRM pipeline setup

Before configuring the AI agent, prepare the required stages in your KeyCRM pipeline.

For example, your pipeline may include:

* **New lead** — the lead has just entered the pipeline.
* **AI processing** — the stage that triggers CostCare AI to start the AI-agent workflow.
* **Manager work** — the stage where the lead is moved if the AI agent escalates the conversation to a real manager.
* **Qualified** — the lead has been successfully qualified.
* **Closed** — the lead has been completed or rejected.

<Info>
  You can use your own stage names. The important part is to clearly define which stage starts AI processing and which stage is used for manager escalation.
</Info>

## Connect KeyCRM to CostCare AI

### 1. Open Integrations in CostCare AI

In your CostCare AI account, go to **Integrations**.

Select **KeyCRM** from the list of available integrations.

Click **Connect**.

<Frame>
  <img src="https://mintcdn.com/costcare/SXwrUt5wnUNM4GM3/images/Integration_KeyCRM_1_eng.png?fit=max&auto=format&n=SXwrUt5wnUNM4GM3&q=85&s=7785fa48b04fd3da05ff04a147466f37" alt="Integration KeyCRM 1 eng" width="2940" height="1530" data-path="images/Integration_KeyCRM_1_eng.png" />
</Frame>

### 2. Add your KeyCRM API key

Paste your KeyCRM API key into the connection window.

Then click **Continue**.

<Frame>
  <img src="https://mintcdn.com/costcare/SXwrUt5wnUNM4GM3/images/Integration_KeyCRM_2_eng.png?fit=max&auto=format&n=SXwrUt5wnUNM4GM3&q=85&s=140441bf9dd560b4913d11b97cd3219e" alt="Integration KeyCRM 2 eng" width="2940" height="1530" data-path="images/Integration_KeyCRM_2_eng.png" />
</Frame>

<Note>
  The API key allows CostCare AI to connect with your KeyCRM account, receive lead data, and update the lead card stage when required by the AI-agent scenario.
</Note>

### 3. Copy the webhook URL

After the API key is added, CostCare AI will generate a webhook URL.

Copy this webhook URL. You will need to add it to KeyCRM.

### 4. Add the webhook in KeyCRM

In KeyCRM, create a webhook that triggers when a lead moves to the stage where the AI agent should start processing.

Paste the webhook URL copied from CostCare AI into the webhook settings in KeyCRM.

<Frame>
  <img src="https://mintcdn.com/costcare/SXwrUt5wnUNM4GM3/images/Integration_KeyCRM_3_eng.png?fit=max&auto=format&n=SXwrUt5wnUNM4GM3&q=85&s=e32beec358e203094fced1a4f06fa03a" alt="Integration KeyCRM 3 eng" width="1422" height="871" data-path="images/Integration_KeyCRM_3_eng.png" />
</Frame>

<Info>
  The webhook should be configured for the stage-change event that represents the moment when the lead should be passed to the AI agent.
</Info>

### 5. Finish the connection

After adding the webhook in KeyCRM, return to CostCare AI and click **Done**.

Once completed, the integration status will change to **Connected**.

<Frame>
  <img src="https://mintcdn.com/costcare/SXwrUt5wnUNM4GM3/images/Integration_KeyCRM_4_eng.png?fit=max&auto=format&n=SXwrUt5wnUNM4GM3&q=85&s=e936569e2bd8701c2829b3d657d5f7ef" alt="Integration KeyCRM 4 eng" width="1656" height="950" data-path="images/Integration_KeyCRM_4_eng.png" />
</Frame>

## Configure AI-agent escalation

After the KeyCRM integration is connected, you can configure the AI agent to escalate leads to a real manager.

This behavior is configured in the AI-agent prompt.

For example, you can instruct the AI agent to escalate the lead when:

* the customer asks a question the AI agent cannot answer;
* the AI agent does not have enough information to continue;
* the customer requests to speak with a real person;
* the conversation requires manual review;
* the lead is ready for a manager to continue the sales process.

When escalation happens, CostCare AI can move the lead card in KeyCRM to the stage created for manager work.

<Warning>
  Create the manager escalation stage in KeyCRM before adding this behavior to the AI-agent prompt. If the stage does not exist, the lead may not be moved correctly.
</Warning>

## Example AI-agent prompt instruction

You can add this instruction to the AI-agent prompt:

<Note>
  If you do not have enough information to answer the customer’s question, or if the customer asks to speak with a real manager, escalate the lead to a human manager.

  When escalating, transfer the lead to the “Manager work” stage in KeyCRM.
</Note>

Use the exact name of the stage from your KeyCRM pipeline when describing the escalation rule in the AI-agent prompt.

## What happens after connection

After the integration is connected, CostCare AI listens for webhook events from KeyCRM.

When a lead moves to the defined AI-processing stage, CostCare AI receives the signal and starts the AI-agent workflow.

If the AI agent continues the conversation successfully, the workflow follows the configured scenario.

If the AI agent escalates the lead to a manager, CostCare AI updates the lead card in KeyCRM and moves it to the manager escalation stage.

<Warning>
  The AI agent will not start processing every new lead automatically. It starts only when the lead moves to the KeyCRM stage configured as the trigger.
</Warning>

## What data is sent to CostCare AI

Depending on your KeyCRM setup and webhook configuration, CostCare AI may receive:

* lead details;
* contact information;
* pipeline information;
* current lead stage;
* order or request details;
* custom fields used in your sales process.

<Note>
  The exact data depends on the fields available in KeyCRM and the webhook payload configured in your KeyCRM account.
</Note>

## Important behavior

<CardGroup cols={2}>
  <Card title="AI starts from a stage" icon="diagram-project">
    The AI agent starts processing only after the lead moves to the selected stage in KeyCRM.
  </Card>

  <Card title="CostCare AI listens to webhooks" icon="webhook">
    CostCare AI receives stage-change signals from KeyCRM through webhook events.
  </Card>

  <Card title="Escalation moves the lead" icon="user-headset">
    If the AI agent escalates the lead to a real manager, CostCare AI can move the lead card to the manager stage in KeyCRM.
  </Card>

  <Card title="Stage must exist first" icon="list-check">
    The manager escalation stage must be created in KeyCRM before it is used in the AI-agent prompt.
  </Card>

  <Card title="Agent logic is prompt-based" icon="message-lines">
    The escalation behavior is described in the AI-agent prompt after the KeyCRM integration is connected.
  </Card>

  <Card title="No separate chat card in KeyCRM" icon="message-xmark">
    CostCare AI does not create a separate chat card in KeyCRM for this integration.
  </Card>
</CardGroup>

## Test the integration

To check whether the integration works correctly:

<Steps>
  <Step title="Create or choose a test lead in KeyCRM">
    Use an existing lead or create a new test lead in your KeyCRM pipeline.
  </Step>

  <Step title="Move the lead to the AI-processing stage">
    Move the lead to the stage that should start AI processing.
  </Step>

  <Step title="Check the webhook event">
    Make sure the webhook was triggered successfully in KeyCRM.
  </Step>

  <Step title="Check CostCare AI">
    Confirm that the AI agent received the lead data and started processing.
  </Step>

  <Step title="Test escalation">
    Ask a question that should trigger manager escalation, or simulate a case where the AI agent does not have enough information.
  </Step>

  <Step title="Check the lead stage in KeyCRM">
    Confirm that the lead card was moved to the manager escalation stage, such as “Manager work”.
  </Step>
</Steps>

## Troubleshooting

If the lead was not passed to CostCare AI or was not moved to the correct stage, check the following:

<AccordionGroup>
  <Accordion title="The webhook URL is incorrect">
    Make sure the webhook URL in KeyCRM is the same as the URL generated in CostCare AI.
  </Accordion>

  <Accordion title="The API key is invalid or inactive">
    Check whether your KeyCRM API key is active and was copied correctly.
  </Accordion>

  <Accordion title="The wrong event is selected in KeyCRM">
    Make sure the webhook is triggered by the correct lead stage-change event.
  </Accordion>

  <Accordion title="The lead moved to a different stage">
    The AI agent starts only when the lead moves to the stage selected for AI processing.
  </Accordion>

  <Accordion title="The manager stage does not exist in KeyCRM">
    Create the manager escalation stage in KeyCRM before configuring the AI agent to move leads to this stage.
  </Accordion>

  <Accordion title="The stage name in the prompt is incorrect">
    Make sure the stage name in the AI-agent prompt matches the stage name in KeyCRM.
  </Accordion>

  <Accordion title="The escalation rule is missing from the AI-agent prompt">
    Add a clear instruction to the AI-agent prompt that explains when the lead should be escalated and which KeyCRM stage should be used.
  </Accordion>

  <Accordion title="CostCare AI balance is low">
    If your balance is low, agents may not work without interruptions. Top up your balance and try again.
  </Accordion>
</AccordionGroup>

## Disconnect KeyCRM

To disconnect KeyCRM from CostCare AI:

<Steps>
  <Step title="Open Integrations">
    Go to **Integrations** in your CostCare AI account.
  </Step>

  <Step title="Select KeyCRM">
    Open the connected KeyCRM integration.
  </Step>

  <Step title="Click Disconnect">
    Click **Disconnect** to stop receiving data from KeyCRM.
  </Step>
</Steps>

After disconnecting, CostCare AI will no longer receive webhook events from KeyCRM or update lead stages in KeyCRM.

## FAQ

<AccordionGroup>
  <Accordion title="Does CostCare AI create a chat card in KeyCRM?">
    No. CostCare AI does not create a separate chat card in KeyCRM. The integration receives data through a webhook when a lead moves to a specific stage.
  </Accordion>

  <Accordion title="When does the AI agent start processing a lead?">
    The AI agent starts when the lead moves to the KeyCRM stage configured as the trigger for AI processing.
  </Accordion>

  <Accordion title="Can I choose which KeyCRM stage triggers the AI agent?">
    Yes. You can define the stage in your KeyCRM pipeline that should send the signal to CostCare AI.
  </Accordion>

  <Accordion title="Can CostCare AI move a lead to another stage in KeyCRM?">
    Yes. If the AI agent escalates the lead to a real manager, CostCare AI can move the lead card to a dedicated manager stage in KeyCRM.
  </Accordion>

  <Accordion title="Where is escalation configured?">
    Escalation is configured in the AI-agent prompt after the KeyCRM integration is connected.
  </Accordion>

  <Accordion title="Do I need to create the manager stage before configuring the AI agent?">
    Yes. Create the manager escalation stage in KeyCRM first, then add the escalation instruction to the AI-agent prompt.
  </Accordion>

  <Accordion title="What should I do if the lead is not sent to CostCare AI?">
    Check the API key, webhook URL, webhook event settings, selected pipeline stage, and your CostCare AI balance.
  </Accordion>

  <Accordion title="What should I do if the lead is not moved to the manager stage?">
    Check whether the manager stage exists in KeyCRM, whether its name matches the AI-agent prompt, and whether the escalation rule is clearly described in the prompt.
  </Accordion>
</AccordionGroup>