Telephony AI Agent에서 DTMF 이벤트를 활성화하는 방법

Source: Dev.to

Overview

모든 발신자가 음성 에이전트와 대화하기를 원하는 것은 아닙니다. 많은 통화 시나리오에서 사용자는 선택을 하거나, 작업을 확인하거나, 통화 흐름을 진행하기 위해 키를 누르기를 기대합니다. 이는 특히 메뉴 기반 시스템, 짧은 응답, 또는 음성 인식이 신뢰할 수 없을 때 흔히 발생합니다.

DTMF(듀얼톤 멀티주파수) 입력은 음성 에이전트에게 이러한 상호작용을 명확하고 예측 가능한 방식으로 처리할 수 있는 방법을 제공합니다. 발신자가 전화기에서 키를 누르면 에이전트는 즉시 해당 입력을 받아 통화 흐름을 제어하거나 애플리케이션 로직을 트리거하는 데 사용할 수 있습니다.

이 포스트에서는 일반적인 상호작용 패턴을 시작으로, 실시간으로 키패드 입력을 처리하는 시스템이 어떻게 동작하는지 살펴보며 VideoSDK 기반 음성 에이전트에서 DTMF 이벤트를 활용하는 방법을 탐구합니다.

작동 원리

• DTMF 이벤트 감지 – 에이전트는 통화 세션 중 발신자로부터 키 입력(0–9, *, #)을 감지합니다.
• 실시간 처리 – 각 키 입력은 DTMF 이벤트를 생성하며, 즉시 에이전트에 전달됩니다.
• 콜백 통합 – 사용자 정의 콜백 함수가 들어오는 DTMF 이벤트를 처리합니다.
• 동작 실행 – 에이전트는 수신된 DTMF 입력에 따라 동작을 수행하거나 워크플로를 트리거합니다(예: IVR 흐름 구축, 사용자 입력 수집, 애플리케이션 로직 호출).

Source: …

Step 1 – DTMF 이벤트 활성화

DTMF 이벤트 감지는 두 가지 방법으로 활성화할 수 있습니다:

1️⃣ 대시보드에서

VideoSDK 대시보드에서 SIP 게이트웨이를 생성하거나 편집할 때 DTMF 옵션을 활성화합니다.

2️⃣ API를 통해

API를 사용해 SIP 게이트웨이를 생성하거나 업데이트할 때 enableDtmf 파라미터를 true 로 설정합니다.

curl -H 'Authorization: $YOUR_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "Twilio Inbound Gateway",
           "enableDtmf": true,
           "numbers": ["+0123456789"]
         }' \
     -X POST https://api.videosdk.live/v2/sip/inbound-gateways

활성화되면 해당 게이트웨이를 통해 라우팅되는 모든 통화에 대해 DTMF 이벤트가 감지되고 퍼블리시됩니다.

인바운드 호출, 아웃바운드 호출 및 라우팅 규칙을 설정하려면 Quick Start Example 를 확인하세요.

Step 2 – 구현

from videosdk.agents import AgentSession, DTMFHandler

async def entrypoint(ctx: JobContext):

    async def dtmf_callback(digit: int):
        if digit == 1:
            agent.instructions = (
                "You are a Sales Representative. Your goal is to sell our products."
            )
            await agent.session.say(
                "Routing you to Sales. Hi, I'm from Sales. How can I help you today?"
            )
        elif digit == 2:
            agent.instructions = (
                "You are a Support Specialist. Your goal is to help customers with technical issues."
            )
            await agent.session.say(
                "Routing you to Support. Hi, I'm from Support. What issue are you facing?"
            )
        else:
            await agent.session.say(
                "Invalid input. Press 1 for Sales or 2 for Support."
            )

    dtmf_handler = DTMFHandler(dtmf_callback)

    session = AgentSession(
        dtmf_handler=dtmf_handler,
    )

전체 작업 예제

import logging
from videosdk.agents import (
    Agent,
    AgentSession,
    CascadingPipeline,
    ConversationFlow,
    JobContext,
    DTMFHandler,
)
from videosdk.plugins.deepgram import DeepgramSTT
from videosdk.plugins.openai import OpenAILLM
from videosdk.plugins.elevenlabs import ElevenLabsTTS
from videosdk.plugins.silero import SileroVAD
from videosdk.plugins.turn_detector import TurnDetector, pre_download_model

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    handlers=[logging.StreamHandler()],
)

# Ensure the VAD model is available locally
pre_download_model()


class VoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful voice assistant that can answer questions."
        )

    async def on_enter(self) -> None:
        await self.session.say("Hello, how can I help you today?")

    async def on_exit(self) -> None:
        await self.session.say("Goodbye!")


async def entrypoint(ctx: JobContext):
    agent = VoiceAgent()
    conversation_flow = ConversationFlow(agent)

    pipeline = CascadingPipeline(
        stt=DeepgramSTT(),
        llm=OpenAILLM(),
        tts=ElevenLabsTTS(),
        vad=SileroVAD(),
        turn_detector=TurnDetector(),
    )

    async def dtmf_callback(message):
        print("DTMF message received:", message)

    dtmf_handler = DTMFHandler(dtmf_callback)

    session = AgentSession(
        agent=agent,
        pipeline=pipeline,
        conversation_flow=conversation_flow,
        dtmf_handler=dtmf_handler,
    )

    await session.start(wait_for_participation=True)

ant=True, run_until_shutdown=True)

def make_context() -> JobContext:
    room_options = RoomOptions(name="DTMF Agent Test", playground=True)
    return JobContext(room_options=room_options) 

if __name__ == "__main__":
    job = WorkerJob(
        entrypoint=entrypoint,
        jobctx=make_context,
        options=Options(
            agent_id="YOUR_AGENT_ID",
            max_processes=2,
            register=True,
            host="localhost",
            port=8081,
        ),
    )
    job.start()

Tip: 편집기에서 전체 화면 모드를 전환하면 코드를 더 잘 볼 수 있습니다.

DTMF 감지 활성화의 이점

• 예측 가능한 통화 흐름 구축
• 사용자를 메뉴로 안내
• 통화 경험을 방해하지 않고 애플리케이션 로직 트리거

음성 입력과 결합하면 DTMF는 사용자가 에이전트와 상호 작용하는 방식을 더 많이 제어할 수 있게 합니다. 이는 통화 중 명확하고 결정적인 사용자 입력이 필요한 모든 음성 에이전트에 DTMF를 실용적인 추가 요소로 만듭니다.

리소스 및 다음 단계

• 전체 코드 구현을 보려면 **dtmf‑event‑implementation‑example**를 살펴보세요.
• 인바운드 콜, 아웃바운드 콜 및 라우팅 규칙을 설정하려면 **Quick Start Example**를 확인하세요.
• AI 에이전트를 **deploy your AI Agents**하는 방법을 알아보세요.
• **VideoSDK documentation**에서 더 많은 기능을 살펴보세요.

👉 댓글에 생각, 어려움, 성공 사례를 공유하거나 **Discord community**에 참여하세요. 여러분의 여정을 배우고 더 나은 AI 기반 커뮤니케이션 도구를 만들 수 있도록 돕게 되어 기쁩니다!