> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt. # EspoCRM With the [webhook tools](/docs/reception-ai/integrations/webhooks) below, your receptionist can recognize callers who are already in EspoCRM and add new callers as leads, with their name, phone number, and what they need, so your team can follow up. EspoCRM's API takes a static API key and JSON request bodies, so it works the same for EspoCRM Cloud and self-hosted installs. ## Before you start ### Create a role In EspoCRM, go to **Administration** → **Roles** and create a role that can read and create **Leads** and read **Contacts**. Leave every other scope disabled. ### Create an API user Go to **Administration** → **API Users** and create a user. Set the authentication method to **API Key**, and assign the role you just created. Save, then copy the API key from the user's detail view. Every tool below sends the key in a request header named `X-Api-Key`. Set its **Type** to **Secret**. > **Warning** > > The API key can read and change everything its role allows. Keep the role narrow, and regenerate > the key in EspoCRM if it leaks. ### Find your EspoCRM address Your tools' URLs start with the address you open in your browser to use EspoCRM, followed by `/api/v1/`. The tables below use `https://YOUR-CRM.example.com`; replace it with your own. ## Create the tools For each tool, go to **Integrations**, select **Add integration**, choose **Webhook Tool**, and set **Assign to agents** to **Receptionist**. Set **Value** to **Fixed value** for every parameter marked "Always" below. ### Find a lead | Field | Value | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | `find_espocrm_lead` | | **Description** | "Find the caller among our leads by phone number. Use it at the start of a call to check whether they've contacted us before." | | **Method** | GET | | **URL** | `https://YOUR-CRM.example.com/api/v1/Lead` | | **Request Headers** | `X-Api-Key`: your API key | | **Query Parameters** | `textFilter` (string, required): "The caller's phone number with its country code, for example +14155550123." `select` (string): Always `id,name,status`. `maxSize` (integer): Always `5`. | To also recognize existing customers, create a second tool named `find_espocrm_contact` with the same settings and the URL `https://YOUR-CRM.example.com/api/v1/Contact`. ### Add a new lead | Field | Value | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Name** | `create_espocrm_lead` | | **Description** | "Add the caller as a new lead when `find_espocrm_lead` didn't find them." | | **Method** | POST | | **URL** | `https://YOUR-CRM.example.com/api/v1/Lead` | | **Request Headers** | `X-Api-Key`: your API key | | **Body Parameters** | `firstName` (string, required): "The caller's first name." `lastName` (string, required): "The caller's last name." `phoneNumber` (string, required): "The caller's phone number in international format, for example +14155550123." `emailAddress` (string): "The caller's email address, if they gave one." `description` (string, required): "What the caller needs, and when they'd like a call back." `status` (string): Always `New`. `source` (string): Always `Call`. | To route new leads to one salesperson, add `assignedUserId` (string) as a fixed value with that user's ID. You can see the ID in the address bar when you open the user in EspoCRM. Select **Enable** on each tool, then [test your receptionist](/docs/reception-ai/receptionist/testing) as a new caller who asks for a quote. The lead appears in EspoCRM with the status **New** and the source **Call**. > **Tip** > > Add a [procedure](/docs/reception-ai/receptionist/rules-and-procedures) so your receptionist > searches first, and only adds a lead when no match is found. > **Warning** > > The search also matches names and email addresses, so a caller could try to look up someone else. > Add a rule that your receptionist never reads CRM records back to callers, and keep **select** > limited to `id,name,status`. ## Limitations * `textFilter` is the same search as EspoCRM's own search box: it looks in names, email addresses, and phone numbers. A search by phone number can also match a different record whose number starts with the same digits, so your receptionist should confirm the caller's name. * Your receptionist can't add a note or a task to an existing lead or contact with these tools. The new lead's description holds the call details. * The tools don't set teams. EspoCRM takes teams as a list of team IDs (`teamsIds`), and a webhook tool always fills a list from the conversation, so it can't put every lead in the same team, and your receptionist shouldn't choose teams. Use `assignedUserId` to route leads instead. ## Troubleshooting | Problem | What to check | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | 401 from EspoCRM | The header must be named `X-Api-Key` and hold the key from the API user's detail view. Check the API user is active. | | 403 from EspoCRM | The API user's role can't read or create leads. Edit the role in **Administration** → **Roles**. | | 409 when adding a lead | EspoCRM found a possible duplicate, such as a lead with the same name or email address. Your receptionist should search first. | | Known callers aren't found | Store phone numbers in international format, such as `+14155550123`, and check the number is on a lead or contact, not only on an account. | | `status` or `source` errors | The values must match your lead **Status** and **Source** options exactly, as set in **Administration** → **Entity Manager** → **Lead**. |