🦞 19. Twilio 전화알림 연동

OpenClaw를 “대화형 비서”에서 한 단계 올려, 실제로 전화까지 거는 실행형 비서로 만드는 가이드입니다. 이 문서는 복잡한 양방향 통화봇보다, 먼저 실무에서 바로 쓰는 전화 알림 자동화에 집중합니다.

안내: 본문은 생성형 AI를 활용해 정리했으며, 토큰/전화번호 등 민감정보는 예시에서 마스킹했습니다.

flowchart LR
A[OpenClaw 이벤트 발생] --> B[전화 브리지 API 호출]
B --> C[Twilio Voice API]
C --> D[수신자 전화 연결]
D --> E[TTS 알림 재생]

0) 이 방식이 좋은 이유

• 빠름: 10~20분이면 첫 통화 테스트 가능
• 안정적: 실시간 음성 대화보다 장애 포인트가 적음
• 확장 쉬움: 나중에 승인/시간제한/다중 수신자로 확장 가능

1) 준비물

• Twilio 계정 + Voice 발신 번호 1개
• OpenClaw가 동작 중인 서버 1대
• 브리지 서버(같은 서버 가능)
• 환경변수 4개
  • TWILIO_ACCOUNT_SID
  • TWILIO_AUTH_TOKEN
  • TWILIO_FROM_NUMBER (예: +1...)
  • CALL_BRIDGE_TOKEN (브리지 호출용 비밀 토큰)

1-1) 발신번호는 어떻게 받나? (Twilio에서 발급 가능)

네, Twilio에서 발신번호를 직접 발급(구매)할 수 있습니다.

빠른 순서:

1. Twilio 계정 생성(Trial 가능)
2. Console에서 Phone Number 검색/구매
3. Voice 가능 번호인지 확인 후 발급
4. 발급된 번호를 TWILIO_FROM_NUMBER에 설정

실무 팁:

• Trial 계정은 기능 제한이 있을 수 있어, 테스트 대상 번호 검증(Verified Caller ID)이 필요할 수 있습니다.
• 국가/번호 유형(지역번호·수신자 부담)에 따라 규제 문서(주소/신분) 제출이 필요할 수 있습니다.

참고 링크:

• Twilio Phone Numbers: https://www.twilio.com/en-us/phone-numbers
• Twilio Free Trial 시작: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account
• 규제 컴플라이언스 시작: https://www.twilio.com/docs/phone-numbers/regulatory/getting-started

2) 최소 브리지 API 만들기 (FastAPI 예시)

아래 예시는 OpenClaw/스크립트에서 POST를 받으면 Twilio로 전화를 거는 최소 구현입니다.

# file: call_bridge.py
import os
from fastapi import FastAPI, Header, HTTPException
from twilio.rest import Client
 
app = FastAPI()
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
 
ALLOWLIST = {x.strip() for x in os.environ.get("CALL_ALLOWLIST", "").split(",") if x.strip()}
BRIDGE_TOKEN = os.environ["CALL_BRIDGE_TOKEN"]
 
@app.post("/call")
def make_call(payload: dict, authorization: str = Header(default="")):
    if authorization != f"Bearer {BRIDGE_TOKEN}":
        raise HTTPException(status_code=401, detail="unauthorized")
 
    to = payload.get("to", "").strip()
    msg = payload.get("message", "알림이 도착했습니다.").strip()
 
    if not to:
        raise HTTPException(status_code=400, detail="to required")
    if ALLOWLIST and to not in ALLOWLIST:
        raise HTTPException(status_code=403, detail="number not allowed")
 
    twiml = f"<Response><Say language='ko-KR'>{msg}</Say></Response>"
    call = client.calls.create(
        to=to,
        from_=os.environ["TWILIO_FROM_NUMBER"],
        twiml=twiml,
    )
    return {"ok": True, "callSid": call.sid}

실행:

uvicorn call_bridge:app --host 0.0.0.0 --port 8787

3) OpenClaw에서 전화 트리거하기

가장 단순한 방식은 OpenClaw 작업 흐름(스크립트/cron/수동 실행)에서 브리지 API를 호출하는 것입니다.

curl -X POST http://127.0.0.1:8787/call \
  -H "Authorization: Bearer $CALL_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+82xxxxxxxxxx",
    "message": "또우님, 30분 뒤 미팅 시작입니다."
  }'

4) 실무 안전장치 (필수)

1. 번호 allowlist: 지정 번호만 발신 허용
2. 시간 제한: 심야(예: 22:00~08:00) 발신 금지
3. 쿨다운: 같은 번호 연속 발신 최소 간격(예: 10분)
4. 실패 fallback: 통화 실패 시 Telegram/문자 알림 전환

5) 테스트 체크리스트

• 브리지 API 헬스체크(200) 확인
• 허용 번호로 테스트 콜 성공
• allowlist 미등록 번호 차단 확인
• 야간 차단/쿨다운 동작 확인
• 실패 시 대체 알림(텔레그램) 확인

6) 다음 확장

• 단순 TTS 알림 → “승인 필요/확인 필요” 음성 메뉴(키패드 입력)
• 단일 번호 → 팀 단위 라우팅
• 이벤트별 우선순위(긴급만 전화, 일반은 메시지)

한 줄 결론

Twilio 연동은 OpenClaw를 “말 잘하는 AI”에서 실제로 깨워주는 실행형 비서로 바꾸는 가장 체감 큰 확장입니다.

관련 문서

• OpenClaw 06: Cron Job
• OpenClaw 18: 텔레그램 안될 때 5분 복구
• OpenClaw 13: Subagents 설계와 프롬프트
• Twilio Outbound Call 튜토리얼: https://www.twilio.com/docs/voice/tutorials/how-to-make-outbound-phone-calls