Integrate Twilio Notifications
개요
파일 전송 작업의 상태 변화를 SMS 문자로 전달받으려면 Twilio 알림을 연동할 수 있습니다.
연동을 완료하면 전송이 시작(Started), 완료(Completed), 실패(Failed) 되는 등 지정한 이벤트가 발생할 때마다 지정한 휴대폰 번호로 문자 메시지가 자동으로 전송됩니다.
전체 과정은 ① Twilio 자격 증명 및 발신 번호 확인 → ② 제품에서 알림 설정 두 단계로 진행됩니다.
준비 사항
시작하기 전에 다음 사항을 확인하세요.
| 항목 | 설명 |
|---|---|
| Twilio 계정 | SMS를 발송할 수 있는 Twilio 계정이 필요합니다. 체험(Trial) 계정은 발송에 제약이 있으므로 운영 환경에서는 유료 계정 사용을 권장합니다. |
| Twilio 전화번호 | SMS 발신이 가능한 Twilio 전화번호가 필요합니다. |
| 수신 번호 | 알림을 받을 휴대폰 번호를 E.164 형식(국가 번호 포함)으로 준비합니다. |
| 네트워크 | 제품이 설치된 환경에서 api.twilio.com(443)으로의 외부 HTTPS 통신이 허용되어야 합니다. |
Twilio 자격 증명 및 발신 번호 확인
Twilio로 SMS 알림을 받으려면 Twilio Console에서 계정 자격 증명과 발신 번호를 확인합니다.
Step 1. Account SID 및 Auth Token 확인
Twilio Console(https://console.twilio.com)에 로그인합니다.
홈 화면의 Account Info에서 Account SID(AC로 시작)와 Auth Token을 확인합니다.
Auth Token은 비밀번호와 같은 정보입니다. 값을 알고 있는 사람은 해당 계정으로 문자 발송 및 통화를 실행하여 비용을 발생시킬 수 있으므로 공개 저장소나 외부 문서에 노출되지 않도록 주의합니다.
필요한 경우 Console에서 Auth Token을 다시 발급(Rotate)할 수 있습니다.
Step 2. Twilio Phone Number 확인
Console에서 Phone Numbers → Manage → Active Numbers 메뉴를 열어 SMS 발신이 가능한 Twilio 전화번호를 확인합니다.
번호가 없는 경우 새로운 번호를 구매합니다.
일부 번호는 음성 전용이거나 특정 국가에서만 사용할 수 있으므로 SMS 기능이 지원되는 번호인지 확인합니다.
전화번호는 E.164 형식(국가 번호 포함)으로 사용합니다.
Step 3. 수신 번호 및 발송 조건 확인
알림을 받을 휴대폰 번호를 E.164 형식으로 준비합니다.
Twilio Trial 계정에서는 Verified Caller IDs에 등록된 번호로만 SMS를 보낼 수 있으므로 수신 번호를 미리 인증하거나 계정을 유료로 업그레이드합니다.
또한 Messaging → Settings → Geo Permissions에서 발송 대상 국가가 허용되어 있는지 확인합니다.
기본적으로 계정 등록 국가만 활성화되어 있으므로 다른 국가로 발송하려면 해당 국가를 활성화해야 합니다.
확인 사항
- ✔ Account SID와 Auth Token을 확인했습니다.
- ✔ SMS 발신이 가능한 Twilio 전화번호를 확인했습니다.
- ✔ 수신 번호가 발송 조건(번호 인증 및 국가 권한)을 충족합니다.
Twilio 알림 설정
확인한 자격 증명과 전화번호를 제품의 알림 설정에 입력합니다.
Notifications 설정 창을 열면 아래와 같은 화면이 표시됩니다.
Step 1. Account SID 입력
Account SID 항목에 확인한 Account SID(AC로 시작)를 입력합니다.
Step 2. Auth Token 입력
Auth Token 항목에 확인한 Auth Token을 입력합니다.
Step 3. Twilio Phone Number (From) 입력
Twilio Phone Number (From) 항목에 발신에 사용할 Twilio 전화번호를 E.164 형식으로 입력합니다.
예:
Step 4. Recipient Phone Number (To) 입력
Recipient Phone Number (To) 항목에 알림을 받을 휴대폰 번호를 E.164 형식으로 입력합니다.
예:
Step 5. 알림 이벤트 선택
Events 항목에서 알림을 받을 이벤트를 선택합니다.
여러 개를 선택할 수 있으며, 선택한 이벤트가 발생할 때만 SMS가 발송됩니다.
| 이벤트 | 발생 시점 |
|---|---|
| Started | 전송 작업이 시작되었을 때 |
| Completed | 전송이 정상적으로 완료되었을 때 |
| Paused | 전송이 일시 중지되었을 때 |
| Resumed | 일시 중지된 전송이 다시 시작되었을 때 |
| Recovered | 중단 또는 오류 후 전송이 자동 복구되어 재개되었을 때 |
| Canceled | 사용자가 전송을 취소했을 때 |
| Failed | 전송이 실패했을 때 |
| Skipped | 특정 파일이 건너뛰어졌을 때 (예: 이미 존재하는 파일 또는 필터 조건에 해당하는 경우) |
SMS는 발송 건수에 따라 Twilio 요금이 부과되므로 필요한 이벤트만 선택하는 것을 권장합니다.
Step 6. 설정 저장
입력을 마쳤으면 Add를 클릭하여 연동을 저장합니다.
확인 사항
- ✔ Account SID와 Auth Token이 입력되었습니다.
- ✔ 발신 번호와 수신 번호가 입력되었습니다.
- ✔ 알림받을 이벤트가 선택되었습니다.
연동 확인
설정이 정상적으로 동작하는지 확인합니다.
Step 1. 테스트 이벤트 발생
실제 전송 작업을 실행하거나 선택한 이벤트 중 하나를 발생시킵니다.
Step 2. 수신 휴대폰 확인
지정한 수신 번호로 알림 문자가 도착했는지 확인합니다.
확인 사항
- ✔ 수신 번호로 알림 문자가 도착했습니다.
- ✔ 발생한 이벤트가 정확하게 전달되었습니다.
설정 완료
설정을 저장하면 연동이 적용됩니다.
이후 선택한 이벤트가 발생할 때마다 지정한 수신 번호로 SMS 알림이 자동으로 전송됩니다.
문제 해결 (Troubleshooting)
문자가 도착하지 않는 경우 아래 항목을 확인하세요.
| 문제 | 확인 사항 |
|---|---|
| 문자가 도착하지 않음 | Account SID, Auth Token, 발신 번호 및 수신 번호가 정확하게 입력되었는지, 전화번호가 E.164 형식(+와 국가 번호 포함)인지 확인합니다. |
| 인증 오류가 발생함 | Account SID와 Auth Token이 올바른지, Auth Token이 재발급(Rotate)되지 않았는지 확인합니다. |
| Trial 계정에서 발송되지 않음 | 수신 번호가 Verified Caller IDs에 등록되어 있는지 확인하거나 유료 계정으로 업그레이드합니다. |
| 특정 국가로 발송되지 않음 | Messaging → Settings → Geo Permissions에서 대상 국가가 허용되어 있는지 확인합니다. 국가별 추가 등록이 필요한 경우도 있습니다. |
| 발신 번호 오류 | 사용 중인 Twilio 전화번호가 SMS 발신을 지원하는 번호인지 확인합니다. |
| 폐쇄망에서 연동 실패 | api.twilio.com(443)으로의 아웃바운드 HTTPS 통신이 방화벽 또는 프록시에서 허용되어 있는지 확인합니다. |