Status Callback
통화 상태 변경 시 전송되는 Status Callback의 이벤트 종류와 파라미터를 안내합니다.
Status Callback은 통화 상태가 변경될 때마다 지정한 URL로 이벤트를 전송합니다.
- 발신(outbound): 통화 생성 시
status_callback파라미터로 통화마다 설정합니다. - 수신(inbound): 외부에서 걸려오는 통화는 발신 시점이 없으므로, 전화번호 설정의 "수신 통화 상태 webhook"(
status_callback)에 URL을 미리 등록합니다. 대시보드 전화번호 상세 또는 번호 수정 API의status_callback으로 설정하며, 그 번호로 걸려오는 모든 통화의 상태 전이가 통지됩니다.
call = client.calls.create(
to="01012345678",
from_="07052358010",
url="https://my-app.com/twiml",
status_callback="https://my-app.com/status",
status_callback_event="initiated ringing answered completed",
)이벤트 종류
status_callback_event에 수신할 이벤트를 공백으로 구분하여 지정합니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| initiated | event | 선택 | 통화가 시작됨 (발신 시작) |
| ringing | event | 선택 | 상대방 전화벨이 울리는 중 |
| answered | event | 선택 | 상대방이 전화를 받음 |
| completed | event | 선택 | 통화가 종료됨 |
요청 파라미터
기본 파라미터(CallId, AccountId, From, To, Direction)에 추가로 다음 파라미터가 포함됩니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| CallStatus | string | 필수 | 현재 통화 상태. 진행: initiated/ringing/answered. 종료(completed 이벤트의 실제 사유): completed/busy/no-answer/failed/canceled/rejected. rejected/busy 는 수신 통화를 받기 전 거절한 경우입니다. |
| Duration | string | 선택 | 통화 시간 (초) — completed 이벤트에서만 포함 |
| Timestamp | string | 필수 | 이벤트 발생 시각 (ISO 8601) |
| Direction | string | 필수 | inbound(수신) 또는 outbound(발신) |
| AnsweredBy | string | 선택 | AMD(자동응답기 감지) 결과 — machine_detection 을 켠 발신 통화의 completed 이벤트에만 포함. human(사람) / machine(자동응답기·음성사서함) / unknown(판정 불가) |
예제
from flask import Flask, request
app = Flask(__name__)
@app.route("/status", methods=["POST"])
def status_callback():
call_id = request.form.get("CallId")
status = request.form.get("CallStatus")
duration = request.form.get("Duration")
print(f"통화 {call_id}: {status}")
if status == "completed" and duration:
print(f" 통화 시간: {duration}초")
return "", 204Status Callback 요청에도 X-Signature 헤더가 포함됩니다. 서명 검증 가이드를 참고하여 요청의 무결성을 확인하세요.