EspoCRM | ElevenLabs Documentation

With the webhook tools 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.

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 as a new caller who asks for a quote. The lead appears in EspoCRM with the status New and the source Call.

Add a procedure so your receptionist searches first, and only adds a lead when no match is found.

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.