# 음성 AI 커스텀 액션

## 음성 AI 커스텀 액션

이 문서에서는 통화 중 실시간 웹훅 연동을 활성화하는 음성 AI 커스텀 액션 사용 방법을 알아보겠습니다. 이 강력한 기능을 통해 AI 직원이 대화 중에 외부 시스템과 상호작용하여 데이터를 가져오고, 프로세스를 실행하며, 통화가 끝날 때까지 기다리지 않고도 자동화를 개선할 수 있습니다.

**목차**

* [음성 AI 커스텀 액션이란?](#음성-ai-커스텀-액션이란)
* [음성 AI 커스텀 액션의 주요 장점](#음성-ai-커스텀-액션의-주요-장점)
* [음성 AI 대화 트리거](#음성-ai-대화-트리거)
* [웹훅 커스텀 액션](#웹훅-커스텀-액션)
* [동적 매개변수 수집](#동적-매개변수-수집)
* [음성 AI 커스텀 액션 설정 방법](#음성-ai-커스텀-액션-설정-방법)
* [음성 AI - 실시간 테스트](#음성-ai-실시간-테스트)
* [자주 묻는 질문](#자주-묻는-질문)

***

## 음성 AI 커스텀 액션이란?

음성 AI 커스텀 액션을 사용하면 AI 직원이 실시간 대화 중에 외부 API로 커스텀 POST 웹훅을 호출할 수 있습니다. 이러한 액션에는 인증, 헤더, 통화에서 실시간으로 수집된 동적 매개변수가 포함될 수 있습니다. 이를 통해 AI 직원은 발신자가 말하는 내용에 따라 즉시 정보를 검색하거나 전송할 수 있습니다.

***

### 음성 AI 커스텀 액션의 주요 장점

음성 AI 커스텀 액션을 사용하면 실시간 통화 중에 외부 시스템과 원활하게 연동할 수 있습니다. 이를 통해 AI 직원의 개인화 능력이 향상되고 문제를 더 빠르게 해결할 수 있습니다.

* 대화 상황에 따라 실시간 API 호출을 수행합니다.
* 통화 중에 데이터 조회나 제출을 자동화합니다.

**예를 들어:** 고객이 "최근 주문 상태가 어떻게 되나요?"라고 묻는다면, AI가 즉시 주문 관리 시스템을 호출하여 실시간 상태를 조회할 수 있습니다. 발신자를 대기시킬 필요가 없죠.

* 인증과 헤더가 포함된 POST 요청을 구성합니다.
* 전화번호나 주문 ID 같은 통화 데이터를 동적으로 전달합니다.
* 실제 운영 전에 웹훅 응답을 테스트합니다.
* 통화 중에 필요한 사항을 해결하여 후속 작업을 줄입니다.

***

### 음성 AI 대화 트리거

트리거는 통화 중에 커스텀 액션이 실행되는 조건을 정의합니다. 간단한 구문 기반 트리거를 만들거나 더 복잡한 로직을 구성할 수 있습니다. 트리거는 "매개변수 X가 있을 때만 실행" 같은 **조건**과 함께 계층화할 수도 있습니다.

**트리거 예시:**

* 사용자가 "예약을 확인하고 싶어요"라고 말할 때
* 이메일이 언급될 때
* 숫자 문자열(예: 주문번호)이 말해질 때

![트리거 설정 예시](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055755629/original/vgHTKbSkl3-K92KksuOOFk68vYIqwNYOkw.png?1760133377)

***

### 웹훅 커스텀 액션

웹훅 연동은 음성 AI 커스텀 액션의 핵심입니다. AI 직원이 API를 지원하는 모든 외부 시스템(CRM, 스케줄링 도구, 데이터베이스 등)과 상호작용할 수 있게 해줍니다.

**각 커스텀 액션은 다음을 포함하는 POST 요청으로 정의됩니다:**

* 웹훅 엔드포인트 URL
* 헤더(예: API 키, 토큰)
* 동적 매개변수가 포함된 요청 본문
* 인증(Bearer 토큰, Basic Auth 등)

**예:** Salesforce 같은 CRM과 연동한다면, 웹훅 URL은 /api/v1/lookupContact 같은 엔드포인트를 대상으로 하고 연락처의 이메일이나 전화번호 같은 매개변수를 포함할 수 있습니다.

![웹훅 설정 화면](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055755818/original/0AnIb0Kcut2JhaBPtg13Hc2HJYhgfZpu7A.png?1760134023)

***

### 동적 매개변수 수집

음성 AI는 대화 중에 관련 데이터를 실시간으로 추출하고 라벨링할 수 있습니다. 이러한 값은 웹훅 요청에 사용되는 매개변수에 자동으로 할당됩니다. 예를 들어, AI가 배송 상태 조회를 트리거하기 전에 주문번호와 이메일 주소를 모두 추출해야 하는 경우에 유용합니다. 추출된 값을 웹훅 페이로드에 할당하여 연동이 상황에 맞고 개인화되도록 보장할 수 있습니다.

**지원하는 데이터 유형:**

* 텍스트 (문자열)
* 숫자 (숫자형)
* 이메일
* 전화번호
* 날짜

![매개변수 설정 화면](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055755787/original/ce1pQwudBZ1h7MA3OKbJUXB1XQna-sm0fA.png?1760133816)

***

### 음성 AI 커스텀 액션 설정 방법

음성 AI 커스텀 액션은 음성 AI 에이전트 인터페이스에서 몇 단계만으로 구성할 수 있습니다. 시작하는 방법은 다음과 같습니다:

#### **1단계:** 음성 AI 에이전트로 이동

Voice AI(음성 AI) > Agent Goals(에이전트 목표) > Switch to Advanced Mode(고급 모드로 전환) (*아직 활성화되지 않은 경우*) > Custom Actions(커스텀 액션)으로 이동하세요.

![음성 AI 에이전트 화면](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055756037/original/ZDxjDk2l3UtR29agJ99VMgLzn8fPCh3gSg.gif?1760134862)

#### **2단계:** 커스텀 액션 만들기

* New Action(새 액션)을 클릭하여 커스텀 액션 설정 창을 엽니다.

![새 액션 버튼](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055755970/original/L86KAuL1cDyz8H2y8lY-p93YQNZgVNIgQw.jpeg?1760134618)

#### **3단계:** 커스텀 액션 구성

필요한 모든 커스텀 액션 세부사항을 입력합니다. 모든 항목이 필수는 아닙니다.

* 이름
* **대화 트리거 조건** 설정

***예시:** 사용자가 "계좌 잔액을 확인해주세요"라고 묻는다면, "잔액을 확인"이라는 구문으로 트리거를 설정하고 은행 API에 전달할 전화번호에 대한 매개변수를 정의할 수 있습니다.*

* **웹훅 URL**을 추가하고 **POST**를 메소드로 선택합니다.
* 필요에 따라 커스텀 **헤더**를 추가합니다.
* 필요한 **인증** 세부사항(예: Bearer 토큰)을 입력합니다.
* 대화에서 동적으로 가져올 **매개변수**를 정의합니다.
* **Test Webhook(웹훅 테스트)** 기능을 사용하여 설정을 검증합니다.

![커스텀 액션 설정 화면](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055756544/original/nF_csn19zfxSMnNRhz8aoPEHn3sVJIkc_Q.jpeg?1760136422)

![추가 설정 옵션](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055756461/original/QakH6lkuv8dghp6PziRjzkrBE7VA8QnEpw.png?1760135971)

***

### 음성 AI - 실시간 테스트

커스텀 액션을 저장하기 전에 내장된 **Test Webhook(웹훅 테스트)** 도구를 사용할 수 있습니다. 이를 통해 통화 시나리오를 시뮬레이션하고, 테스트 데이터를 전달하며, 외부 시스템의 응답을 실시간으로 확인할 수 있습니다. 테스트 도구를 사용하여 고객이 "예약을 다시 잡고 싶어요"라고 말하는 상황을 모방하고, 웹훅이 제공된 날짜와 시간을 캘린더 시스템에 올바르게 가져와서 보내는지 확인할 수 있습니다.

**다음과 같은 작업이 가능합니다:**

* 전체 요청(헤더 + 본문)을 확인합니다.
* 원시 응답(200 OK, 404 Not Found 등)을 봅니다. 예를 들어, 웹훅 응답에 예상 배송 날짜가 포함되어 있다면, AI 직원이 즉시 발신자에게 "패키지는 목요일까지 도착할 예정입니다"라고 알려줄 수 있습니다.
* 저장하기 전에 잘못된 구성을 식별하고 수정합니다.

![웹훅 테스트 화면](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155055756518/original/QnD2obzf89LBLKjkEbmtslKhe45Euau57g.png?1760136257)

***

### 자주 묻는 질문

**Q: GET이나 다른 요청 유형을 사용할 수 있나요?**

아니요, 커스텀 액션에서는 현재 POST 요청만 지원됩니다.

**Q: 음성 AI 커스텀 액션은 어디에서 접근하나요?**

\*\*Voice AI(음성 AI) > Agent Goals(에이전트 목표) > Switch to Advanced Mode(고급 모드로 전환) (아직 활성화되지 않은 경우) > Custom Actions(커스텀 액션)\*\*에서 접근할 수 있습니다.

**Q: 웹훅에서 인증을 지원하나요?**

네, Bearer 토큰, Basic Auth를 사용하거나 헤더에 키를 전달할 수 있습니다.

**Q: 통화 중에 웹훅이 실패하면 어떻게 되나요?**

시스템이 실패를 로그에 기록하며, 데이터가 반환되지 않거나 웹훅이 시간 초과될 경우 대체 동작을 정의할 수 있습니다.

**Q: 한 번의 통화에서 여러 웹훅을 트리거할 수 있나요?**

네. 각 커스텀 액션은 고유한 조건에 따라 독립적으로 트리거될 수 있습니다.

**Q: 이러한 액션을 설정하려면 개발자가 필요한가요?**

반드시 그런 것은 아닙니다. 외부 시스템의 API 문서에 접근할 수 있다면 최소한의 기술적 능력으로도 설정할 수 있습니다.

***

*원문 최종 수정: Fri, 10 Oct, 2025 at 5:50 PM* *Hyperclass 사용 가이드 — hyperclass.ai*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyperclass.gitbook.io/hyperclass-docs/ai-ai-employee/voice-ai-custom-actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.