> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# EspoCRM

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

## 시작하기 전에

### 역할 만들기

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

### API 사용자 만들기

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

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

> **Warning**
>
> 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를 확인할 수 있습니다.

각 도구에서 **활성화**를 선택한 다음, 견적을 요청하는 신규 발신자 역할로 [리셉셔니스트를 테스트](/docs/ko/reception-ai/receptionist/testing)하세요. EspoCRM에 상태 **New**, 소스 **Call**로 리드가 표시됩니다.

> **Tip**
>
> 리셉셔니스트가 먼저 검색하고 일치하는 항목이 없을 때만 리드를 추가하도록 [절차](/docs/ko/reception-ai/receptionist/rules-and-procedures)를
> 추가하세요.

> **Warning**
>
> 검색은 이름과 이메일 주소도 일치시키므로, 발신자가 다른 사람을 조회하려 할 수 있습니다.
> 리셉셔니스트가 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` 오류 | 값은 **관리** → **엔터티 관리자** → **리드**에서 설정한 리드 **상태** 및 **소스** 옵션과 정확히 일치해야 합니다.    |