에이전트 단위 웹훅

개요

에이전트 단위 웹훅은 에이전트별 통화 이벤트를 수신합니다. 적용 우선순위는 웹훅 개요를 참고하세요.

지원되는 이벤트

이벤트	설명
`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을 입력하세요.

웹훅 페이로드 예시

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": "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\"}}"
      },
      {
        "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

관련 문서