1. 문자 서비스 개요

DXCMS 관리자 패널의 [문자 서비스] 메뉴는 SMS(단문)•LMS(장문)•MMS(멀티미디어) 문자 메시지를 회원 또는 지정 번호로 발송하고, SMS API 서비스(드라이버)를 설정하며, 발송 이력을 확인하는 통합 문자 관리 도구입니다.

📌  접근 경로: 관리자 대시보드 → 문자 서비스 (또는 URL: /admin/sendsms)

1.1 화면 구성 — 3탭 구조

탭	기능 및 설명
📱 문자 발송	수신 대상과 문자 내용을 설정하여 SMS/LMS/MMS를 발송합니다. 우측에 발송 정보 요약 및 최근 7일 발송 현황이 표시됩니다.
⚙ API 설정	사용할 SMS API 서비스 드라이버를 선택하고 API 키를 설정합니다. 드라이버별 연결 테스트 기능 포함.
📋 발송 로그	발송 이력을 날짜 역순으로 조회합니다. 일시·드라이버·수신 수·성공·실패·내용 미리보기 표시.

1.2 지원 문자 유형

유형	최대 글자 수	특징	사용 시기
SMS	90자	단문 문자	간단한 알림, 인증번호, 짧은 공지사항.
LMS	2,000자	장문 문자	상세 공지, 이벤트 안내, 긴 내용의 발송. 제목(최대 40자) 설정 가능.
MMS	2,000자	멀티미디어	이미지·사진 첨부가 필요한 문자. 드라이버 지원 여부에 따라 다름.
AUTO	자동 판단	자동 감지	입력한 내용이 90자 이하이면 SMS, 초과하면 LMS로 자동 전환. 가장 일반적으로 사용합니다.

1.3 지원 SMS 드라이버 (4종)

드라이버	서비스명	특성 배지	특징
ncp	네이버 클라우드 NCP SENS	국내 표준	국내 가장 널리 사용되는 클라우드 SMS API. NCP(Naver Cloud Platform) 계정 필요. 국내 번호 발송에 최적화.
coolsms	CoolSMS	간편	국내 중소기업·개인 사업자에게 인기 있는 SMS 서비스. API 키와 시크릿만으로 간단하게 설정 가능.
kt	KT Bizmeka	기업	KT의 기업용 문자 서비스. 대기업·공공기관에서 주로 사용. API 키와 사용자 ID로 인증.
twilio	Twilio	글로벌	글로벌 SMS 서비스. 국제 문자 발송에 적합. Account SID + Auth Token + 발신번호(+1로 시작) 필요.

💡  드라이버를 "자동 감지(auto)"로 설정하면 NCP → CoolSMS → KT → Twilio 순서로 설정 완료된 드라이버를 자동으로 선택하여 발송합니다.

2. API 설정 탭

문자를 발송하기 전 먼저 [API 설정] 탭에서 사용할 SMS 서비스를 선택하고 API 키를 등록해야 합니다.

2.1 화면 레이아웃

API 설정 탭은 좌측(1/3)의 드라이버 선택 목록과 우측(2/3)의 선택된 드라이버 설정 패널로 구성됩니다.
 

영역	설명
드라이버 선택 목록 (좌측)	5개 버튼(자동 감지·NCP·CoolSMS·KT·Twilio). 클릭 시 우측 패널이 해당 드라이버 설정 화면으로 전환. 선택된 드라이버는 인디고 배경으로 강조.
드라이버 설정 패널 (우측)	선택한 드라이버의 API 키 입력 필드 + 연결 테스트 영역. 비밀번호형 필드는 설정된 경우 빈 값으로 표시되며 "저장된 키가 있습니다." 안내 표시.
[설정 저장] 버튼 (좌측 하단)	인디고색 저장 버튼. 클릭 시 현재 선택된 드라이버 ID와 모든 API 필드값을 settings 테이블에 저장.

2.2 자동 감지 (auto) 패널

자동 감지를 선택하면 설정된 드라이버 중 사용 가능한 것을 우선순위대로 자동으로 선택합니다.
 

자동 감지 우선순위	1순위: NCP SENS → 2순위: CoolSMS → 3순위: KT Bizmeka → 4순위: Twilio
설정 완료 배지	각 드라이버 줄 오른쪽에 "설정 완료"(초록) 또는 "미설정"(회색) 배지가 표시됩니다.
추천 용도	여러 SMS 서비스를 등록해두고, 특정 서비스에 장애 발생 시 자동으로 다음 서비스로 대체하고 싶을 때.
고정 드라이버와 차이	특정 드라이버를 선택하면 해당 서비스만 사용. 자동 감지는 설정된 순서로 순차 시도.

2.3 NCP SENS 설정

네이버 클라우드 플랫폼(NCP)의 Simple & Easy Notification Service(SENS) API를 사용합니다.
 

필드명	DB 저장 키	설명 및 발급 위치
액세스 키 (Access Key)	sms_ncp_access_key	NCP 콘솔 → 마이페이지 → API 인증키 → 액세스 키
시크릿 키 (Secret Key)	sms_ncp_secret_key	NCP 콘솔 → 마이페이지 → API 인증키 → 시크릿 키. 비밀번호형: 저장 후 빈 값이면 기존 유지.
서비스 ID	sms_ncp_service_id	NCP 콘솔 → SMS → 서비스 목록에서 확인. "ncp:sms:kr:..." 형식.
발신번호	sms_ncp_from	NCP에 등록된 발신번호. 하이픈 없이 숫자만 입력. 예: 0212345678 또는 01012345678.

💡  NCP SENS에서 발신번호를 사전 등록해야 합니다. NCP 콘솔 → SMS → 발신번호 관리에서 등록 후 심사를 받아야 발송이 가능합니다.

2.4 CoolSMS 설정

CoolSMS(쿨에스엠에스) API v4를 사용합니다. 국내 중소기업•개인 사용에 적합합니다.
 

필드명	DB 저장 키	설명 및 발급 위치
API 키	sms_coolsms_api_key	CoolSMS 콘솔 → 개발 정보 → API Key Management → API Key.
API 시크릿	sms_coolsms_api_secret	CoolSMS 콘솔 → 개발 정보 → API Key Management → API Secret. 비밀번호형 필드.
발신번호	sms_coolsms_from	CoolSMS에 등록된 발신번호. 예: 01012345678. 하이픈 없이 숫자만.

💡  CoolSMS에서도 발신번호 등록이 필수입니다. CoolSMS 콘솔 → 발신번호 관리에서 등록 및 인증 후 사용하세요.

2.5 KT Bizmeka 설정

KT의 기업용 문자 서비스 Bizmeka API를 사용합니다.
 

필드명	DB 저장 키	설명 및 발급 위치
API 키	sms_kt_apikey	KT Bizmeka 관리 콘솔 → API 설정에서 발급.
사용자 ID	sms_kt_userid	KT Bizmeka 계정 ID(로그인 ID).
발신번호	sms_kt_from	KT에 등록된 발신번호. 예: 01012345678.

2.6 Twilio 설정

글로벌 SMS 서비스 Twilio를 사용합니다. 국제 문자 발송에 적합합니다.
 

필드명	DB 저장 키	설명 및 발급 위치
Account SID	sms_twilio_account_sid	Twilio 콘솔 → 대시보드 → Account SID. "AC"로 시작하는 문자열.
Auth Token	sms_twilio_auth_token	Twilio 콘솔 → 대시보드 → Auth Token. 비밀번호형 필드.
발신번호	sms_twilio_from	Twilio에서 구입한 가상번호. 국가코드 포함 형식. 예: +12025551234.

⚠️  Twilio는 Trial 계정의 경우 검증된 번호로만 문자를 보낼 수 있습니다. 프로덕션 서비스에는 유료 계정으로 업그레이드가 필요합니다.

2.7 설정 저장 처리

1. CSRF 토큰 검증
2. 비밀번호형 필드(sms_ncp_secret_key, sms_coolsms_api_secret, sms_twilio_auth_token) 처리: 빈 값이면 기존 저장된 값 유지
3. 모든 필드를 settings 테이블에 ON DUPLICATE KEY UPDATE 방식으로 UPSERT
4. dx_set_config()로 현재 요청의 설정 캐시도 갱신
5. DxCache::flush() + DxSms::flushCache()로 캐시 초기화
6. "SMS 설정이 저장되었습니다." 성공 메시지 표시, API 설정 탭 유지

3. 연결 테스트

각 드라이버 설정 패널 하단에 [연결 테스트] 영역이 제공됩니다. 설정이 올바른지 실제 번호로 테스트 문자를 발송하여 확인합니다.

3.1 테스트 발송 방법

1. API 설정 탭 → 테스트할 드라이버 선택
2. API 키 설정 후 [설정 저장] 클릭
3. 설정 패널 하단 연결 테스트 영역의 [수신번호] 필드에 테스트 번호 입력 (예: 01012345678)
4. [테스트 발송] 버튼 클릭
5. "[DXCMS] SMS 연동 테스트 메시지입니다." 문자 수신 확인
6. 성공 메시지: "테스트 문자 발송 성공 → 010XXXXXXXX"
7. 실패 시 오류 메시지 확인 후 API 키•발신번호 재확인

⚠️  테스트 발송 시 실제 문자 발송 비용이 청구됩니다. 테스트 수신번호는 반드시 본인 또는 동의한 번호를 사용하세요.

3.2 주요 발송 실패 원인

오류 메시지	원인 및 해결
API 키가 잘못됨	입력한 API 키 또는 시크릿 키가 틀렸습니다. 콘솔에서 키를 다시 확인하세요.
발신번호 미등록	해당 SMS 서비스에 발신번호가 등록·승인되지 않았습니다. 각 서비스 콘솔에서 발신번호 등록 후 재시도.
잔액 부족	SMS 서비스 계정의 충전 금액이 없습니다. 각 서비스에서 충전 후 재시도.
drv 설정 불완전	선택한 드라이버의 필수 API 키 중 하나 이상이 비어있습니다. 모든 필수 필드를 입력하세요.
수신번호 형식 오류	10자 미만의 번호는 수신자 목록에서 자동 제외됩니다. 정확한 번호를 입력하세요.

4. 문자 발송 탭

API 설정이 완료되면 [문자 발송] 탭에서 문자를 발송합니다. 드라이버가 없으면 발송 버튼이 비활성화(opacity 40%)되며 경고 배너가 표시됩니다.

4.1 수신 대상 — 3가지 방식

방식	대상	설명
📱 직접 입력	직접 입력한 번호	전화번호를 줄바꿈 또는 쉼표로 구분하여 직접 입력. 하이픈(-) 포함 가능(자동 제거). 10자리 미만 번호 자동 제외.
👥 전체 회원	활성 회원 전체	members 테이블의 status=1이고 phone!='' 인 모든 회원. 우측 발송 정보 패널에 수신 가능 회원 수 표시.
🏷 역할별	특정 권한의 회원	member/manager/admin 중 선택. 선택한 권한을 가진 활성 회원 중 phone이 등록된 회원에게만 발송.

💡  전화번호 자동 정제: preg_replace('/[^0-9]/', '', $phone)으로 숫자 외 모든 문자를 제거합니다. 010-1234-5678 입력 시 01012345678로 자동 변환됩니다.

4.2 문자 유형 선택

발송할 문자 유형을 4개 라디오 버튼으로 선택합니다. 선택된 유형은 하늘색 강조로 표시됩니다.
 

유형값	서버 options 처리	동작
AUTO	options['type'] 미설정	드라이버에 type을 전달하지 않음. 입력 내용 길이에 따라 드라이버 자체적으로 SMS/LMS를 결정. 가장 권장.
SMS	options['type']='SMS'	강제로 SMS로 발송. 90자 초과 시 내용이 잘릴 수 있습니다.
LMS	options['type']='LMS'	강제로 LMS로 발송. 제목 입력 행(LMS/MMS 전용)이 표시됩니다. 최대 2,000자.
MMS	options['type']='MMS'	강제로 MMS로 발송. 드라이버가 MMS를 지원해야 합니다. 이미지 첨부는 드라이버별로 다릅니다.

4.3 LMS/MMS 제목 입력

문자 유형으로 LMS 또는 MMS를 선택하면 [제목] 입력 행이 표시됩니다.
 

제목 필드 (sms_subject)	최대 40자. LMS·MMS 발송 시에만 표시. AUTO/SMS 선택 시 숨겨집니다.
제목 미입력 시	서버에서 options["subject"]가 빈 문자열로 처리됩니다. 드라이버에 따라 기본 처리됩니다.

4.4 글자 수 카운터

내용 입력 텍스트 영역 하단에 실시간 글자 수와 예상 문자 유형이 표시됩니다.
 

표시 항목	동작
현재 N자	input 이벤트마다 실시간으로 글자 수를 계산하여 표시합니다.
유형 힌트	90자 이하: "SMS" (초록색 표시). 91자 이상: "LMS" (노랑색 표시). 사용자가 내용 길이에 따른 유형을 즉시 파악할 수 있습니다.
참고 안내	"SMS ≤90자 / LMS ≤2000자" 우측 하단에 고정 표시.

4.5 발송 정보 패널 (우측 사이드바)

사용 드라이버	현재 활성화된 드라이버 이름. 미설정 시 "미설정(빨간색)".
활성 드라이버	DB에 저장된 sms_driver 값. "자동 감지" 또는 드라이버 ID.
수신 가능 회원	phone 컬럼이 있고 status=1인 회원 수(실시간 집계). 전체 회원 발송 시 최대 수신 수.
최근 7일 발송 현황	sms_logs 테이블에서 7일 내 발송 건의 전체·성공·실패 수 집계.

문자 서비스