EspoCRM | ElevenLabs Documentation

아래 웹훅 도구를 사용하면 리셉셔니스트가 EspoCRM에 이미 등록된 발신자를 인식하고, 이름, 전화번호, 필요한 사항과 함께 신규 발신자를 리드로 추가하여 팀에서 후속 조치를 할 수 있습니다. EspoCRM의 API는 고정 API 키와 JSON 요청 본문을 사용하므로 EspoCRM Cloud와 자체 호스팅 설치 환경에서 동일하게 작동합니다.

시작하기 전에

역할 만들기

EspoCRM에서 관리 → 역할로 이동한 후, 리드를 읽고 생성하며 연락처를 읽을 수 있는 역할을 만드세요. 그 외의 모든 범위는 비활성화된 상태로 두세요.

API 사용자 만들기

관리 → API 사용자로 이동하여 사용자를 만드세요. 인증 방법을 API 키로 설정하고, 방금 만든 역할을 할당하세요. 저장한 다음 사용자 세부 정보 보기에서 API 키를 복사하세요.

아래의 모든 도구는 X-Api-Key라는 요청 헤더로 키를 전송합니다. 유형을 비밀로 설정하세요.

API 키는 해당 역할에 허용된 모든 항목을 읽고 변경할 수 있습니다. 역할의 권한을 최소화하고, 키가 유출된 경우 EspoCRM에서 키를 재생성하세요.

EspoCRM 주소 찾기

도구의 URL은 브라우저에서 EspoCRM을 열 때 사용하는 주소 뒤에 /api/v1/을 붙인 형식입니다. 아래 표에서는 https://YOUR-CRM.example.com을 사용합니다. 이 부분을 실제 주소로 바꾸세요.

도구 만들기

각 도구에서 통합으로 이동해 통합 추가를 선택하고 웹훅 도구를 선택한 다음, 에이전트에 할당을 리셉셔니스트로 설정하세요. 아래에서 “항상”으로 표시된 모든 매개변수의 값은 고정 값으로 설정하세요.

리드 찾기

필드	값
이름	`find_espocrm_lead`
설명	”전화번호로 리드에서 발신자를 찾습니다. 통화 시작 시 이전에 연락한 적이 있는지 확인하려면 사용하세요.”
메서드	GET
URL	`https://YOUR-CRM.example.com/api/v1/Lead`
요청 헤더	`X-Api-Key`: API 키
쿼리 매개변수	`textFilter` (문자열, 필수): “국가 코드가 포함된 발신자의 전화번호(예: +14155550123).” `select` (문자열): 항상 `id,name,status`. `maxSize` (정수): 항상 `5`.

기존 고객도 인식하려면 동일한 설정으로 find_espocrm_contact라는 두 번째 도구를 만들고 URL을 https://YOUR-CRM.example.com/api/v1/Contact로 설정하세요.

신규 리드 추가

필드	값
이름	`create_espocrm_lead`
설명	”`find_espocrm_lead`에서 발신자를 찾지 못한 경우 발신자를 신규 리드로 추가합니다.”
메서드	POST
URL	`https://YOUR-CRM.example.com/api/v1/Lead`
요청 헤더	`X-Api-Key`: API 키
본문 매개변수	`firstName` (문자열, 필수): “발신자의 이름.” `lastName` (문자열, 필수): “발신자의 성.” `phoneNumber` (문자열, 필수): “국제 형식의 발신자 전화번호(예: +14155550123).” `emailAddress` (문자열): “발신자가 제공한 경우 이메일 주소.” `description` (문자열, 필수): “발신자에게 필요한 사항과 다시 연락받고 싶은 시점.” `status` (문자열): 항상 `New`. `source` (문자열): 항상 `Call`.

신규 리드를 한 명의 영업 담당자에게 배정하려면 해당 사용자의 ID를 고정 값으로 assignedUserId (문자열)에 추가하세요. EspoCRM에서 사용자를 열면 주소 표시줄에서 ID를 확인할 수 있습니다.

각 도구에서 활성화를 선택한 다음, 견적을 요청하는 신규 발신자 역할로 리셉셔니스트를 테스트하세요. EspoCRM에 상태 New, 소스 Call로 리드가 표시됩니다.

리셉셔니스트가 먼저 검색하고 일치하는 항목이 없을 때만 리드를 추가하도록 절차를 추가하세요.

검색은 이름과 이메일 주소도 일치시키므로, 발신자가 다른 사람을 조회하려 할 수 있습니다. 리셉셔니스트가 CRM 기록을 발신자에게 절대 읽어 주지 않도록 규칙을 추가하고, select는 id,name,status로 제한하세요.

제한 사항

textFilter는 EspoCRM 자체 검색 상자와 동일한 검색 기능으로, 이름, 이메일 주소, 전화번호를 검색합니다. 전화번호로 검색하면 같은 숫자로 시작하는 다른 번호의 기록도 일치할 수 있으므로 리셉셔니스트가 발신자의 이름을 확인해야 합니다.
이 도구로는 기존 리드나 연락처에 메모 또는 작업을 추가할 수 없습니다. 신규 리드의 설명에 통화 세부 정보가 저장됩니다.
도구는 팀을 설정하지 않습니다. EspoCRM은 팀을 팀 ID 목록(teamsIds)으로 처리하며, 웹훅 도구는 항상 대화에서 목록을 채우므로 모든 리드를 같은 팀에 배정할 수 없고 리셉셔니스트도 팀을 선택해서는 안 됩니다. 대신 assignedUserId를 사용해 리드를 배정하세요.

문제 해결

문제	확인할 사항
EspoCRM에서 401 반환	헤더 이름은 `X-Api-Key`여야 하며 API 사용자 세부 정보 보기의 키를 포함해야 합니다. API 사용자가 활성 상태인지 확인하세요.
EspoCRM에서 403 반환	API 사용자의 역할에 리드를 읽거나 생성할 권한이 없습니다. 관리 → 역할에서 역할을 수정하세요.
리드 추가 시 409 발생	EspoCRM에서 동일한 이름이나 이메일 주소를 가진 리드처럼 중복 가능성이 있는 항목을 찾았습니다. 리셉셔니스트가 먼저 검색해야 합니다.
알려진 발신자를 찾을 수 없음	전화번호를 `+14155550123` 같은 국제 형식으로 저장하고, 번호가 계정에만이 아니라 리드 또는 연락처에도 있는지 확인하세요.
`status` 또는 `source` 오류	값은 관리 → 엔터티 관리자 → 리드에서 설정한 리드 상태 및 소스 옵션과 정확히 일치해야 합니다.