에이전트 단위 웹훅

개요

에이전트 단위 웹훅은 에이전트별 통화 이벤트를 수신합니다.
워크스페이스 단위 웹훅과 함께 사용할 수 있으며, 적용 우선순위는 웹훅 개요 문서를 참고하세요.

지원되는 이벤트

현재 지원되는 이벤트는 아래와 같습니다.

이벤트	설명
`call_started`	통화 시작 시 트리거
`call_ended`	통화 종료 시 트리거
`mid_call`	통화 중 특정 이벤트 발생 시 트리거

이벤트 타입 및 페이로드는 제품 업데이트에 따라 확장될 수 있습니다.

활용 사례

시스템 통합

통화 완료 시 CRM 레코드 업데이트
통화 분석 결과 기반 워크플로우 자동화 실행
데이터베이스에 통화 기록 저장

통화 모니터링

통화 시간과 완료 상태 추적
상담원 실시간 성과 모니터링
실시간 플로우 전환 추적 및 분석

실시간 이벤트 처리

플로우 에이전트 노드 전환 시 실시간 알림

설정

웹훅 엔드포인트 구현

웹훅 요청을 수신할 HTTP/HTTPS 서버 엔드포인트를 준비합니다.

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.post("/webhook")
async def handle_webhook(request: Request):
    try:
        data = await request.json()
        event = data.get("event")

        if event == "call_ended":
            print("통화 종료 이벤트:", data.get("call"))
        else:
            print("이벤트:", event)

        return JSONResponse(status_code=200, content={"received": True})
    except Exception:
        return JSONResponse(status_code=500)

에이전트별 웹훅 등록

대시보드에서 에이전트 설정 → 웹훅 탭의 통화 데이터 웹훅 URL 필드를 사용하여 URL을 설정합니다.

웹훅 페이로드 예시

call started
call ended
mid call

{
  "event": "call_started",
  "call": {
    "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "call_type": "web",
    "call_from": null,
    "call_to": null,
    "dynamic_variables": {
      "last_call_at": "2024-12-18T15:45:12Z"
    },
    "metadata": {
      "db_user_uid": "1a7d624b-76fe-4326-90dc-487935e55212"
    },
    "start_timestamp": 1741842354957,
    "opt_out_sensitive_data_storage": false
  }
}

{
  "event": "call_ended",
  "call": {
    "agent_id": "7ea3516d-08f6-4129-ab40-a731e379b320",
    "call_id": "3079f46c-d141-4cd9-805f-69f212136b66",
    "call_type": "web",
    "call_from": null,
    "call_to": null,
    "dynamic_variables": {
      "last_call_at": "2024-12-18T15:45:12Z"
    },
    "metadata": {
      "db_user_uid": "1a7d624b-76fe-4326-90dc-487935e55212"
    },
    "disconnection_reason": "user_hangup",
    "start_timestamp": 1741652312146,
    "end_timestamp": 1741652351189,
    "duration_ms": 39043,
    "transcript": [
      {
        "role": "agent",
        "content": "안녕하세요. 상담사 신유진입니다. 먼저 본인 확인을 위해 예약자분 성함을 말씀해주시겠어요?"
      },
      { "role": "user", "content": "한승준입니다." },
      {
        "role": "agent",
        "content": "네, 잠시만 기다려주세요. 예약자 정보를 확인하고 있습니다."
      },
      {
        "role": "agent",
        "content": "예약자 정보 확인이 완료되었습니다. 감사합니다. 혹시 어떠한 사유로 연락을 주셨을까요?"
      }
    ],
    "transcript_with_tool_calls": [
      {
        "role": "agent",
        "content": "안녕하세요. 상담사 신유진입니다. 먼저 본인 확인을 위해 예약자분 성함을 말씀해주시겠어요?"
      },
      { "role": "user", "content": "한승준입니다." },
      {
        "role": "agent",
        "content": "네, 잠시만 기다려주세요. 예약자 정보를 확인하고 있습니다."
      },
      {
        "role": "tool_call_invocation",
        "tool_call_id": "ee87e2213039",
        "name": "verify_identity",
        "arguments": {
          "call_from": "01012345678",
          "user_provided_name": "한승준"
        }
      },
      {
        "role": "tool_call_result",
        "tool_call_id": "ee87e2213039",
        "content": "{\"result\":{\"user_id\":\"USR12345\",\"name\":\"한승준\",\"verification_status\":\"verified\",\"customer_type\":\"premium member\",\"last_visit\":\"2024-12-25\"}}"
      },
      {
        "role": "agent",
        "content": "예약자 정보 확인이 완료되었습니다. 감사합니다. 혹시 어떠한 사유로 연락을 주셨을까요?"
      }
    ],
    "recording_url": "https://storage.googleapis.com/agentify/egress/AFnsj7RP/audio_recording.ogg",
    "call_cost": { "total_credits_used": 45, "duration_seconds": 39 },
    "call_analysis": {
      "summary": "본 통화는 상담원 신유진이 한승준 고객의 예약자 정보 확인을 진행한 통화 요약입니다. 고객은 본인 확인에 성공적으로 응답했습니다.",
      "user_sentiment": "neutral",
      "custom_analysis_data": [
        {
          "type": "string",
          "name": "문의사항",
          "value": "본인인증 후 추가 문의사항 없이 고객이 통화를 종료하였습니다."
        },
        { "type": "boolean", "name": "문제 해결 여부", "value": false }
      ]
    },
    "opt_out_sensitive_data_storage": false
  }
}

mid_call 이벤트는 flow_transition과 call_message 두 가지 유형을 지원합니다.

flow_transition

플로우 에이전트의 노드 간 전환 시 발생합니다.

{
  "event": "mid_call",
  "mid_call": {
    "agent_id": "b2e8f431-7c9a-4d61-8e23-f6a9c8d04e57",
    "call_id": "9a5d4c82-3e7f-4b91-a8d6-2c1b5e8f9a03",
    "timestamp": 1742158394821,
    "event_type": "flow_transition",
    "event_data": {
      "from_node_id": "q42fqAQd78",
      "to_node_id": "wrJssptDp8",
      "from_node_name": "주문정보 확인",
      "to_node_name": "배송상태 조회"
    }
  }
}

call_message

통화 중 실시간 메시지 발생 시 전송됩니다.사용자 메시지 예시:

{
  "event": "mid_call",
  "mid_call": {
    "agent_id": "b2e8f431-7c9a-4d61-8e23-f6a9c8d04e57",
    "call_id": "9a5d4c82-3e7f-4b91-a8d6-2c1b5e8f9a03",
    "timestamp": 1742158401445,
    "event_type": "call_message",
    "event_data": {
      "role": "user",
      "content": "주문한 제품이 언제 도착하나요?"
    }
  }
}

에이전트 메시지 예시:

{
  "event": "mid_call",
  "mid_call": {
    "agent_id": "b2e8f431-7c9a-4d61-8e23-f6a9c8d04e57",
    "call_id": "9a5d4c82-3e7f-4b91-a8d6-2c1b5e8f9a03",
    "timestamp": 1742158408132,
    "event_type": "call_message",
    "event_data": {
      "role": "agent",
      "content": "고객님의 주문을 확인해보겠습니다. 주문번호 ORD-2024-8291의 배송상태를 조회 중입니다. 잠시만 기다려 주세요."
    }
  }
}

민감 데이터 저장 금지를 활성화한 경우, 주요 통화 정보가 저장되지 않을 수 있습니다. 중요 데이터의 지속적인 활용을 위해 웹훅을 통한 수집 및 저장을 권장합니다.

시작하기

빌드하기

테스트하기

배포하기

모니터링

개요

지원되는 이벤트

활용 사례

시스템 통합

통화 모니터링

실시간 이벤트 처리

설정

웹훅 페이로드 예시

flow_transition

call_message

시작하기

빌드하기

테스트하기

배포하기

모니터링

​개요

​지원되는 이벤트

​활용 사례

​시스템 통합

​통화 모니터링

​실시간 이벤트 처리

​설정

​웹훅 페이로드 예시

​flow_transition

​call_message

개요

지원되는 이벤트

활용 사례

시스템 통합

통화 모니터링

실시간 이벤트 처리

설정

웹훅 페이로드 예시

flow_transition

call_message