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일 내 발송 건의 전체·성공·실패 수 집계.

5. 발송 처리 흐름

[문자 발송하기] 버튼 클릭 시 서버에서 다음 순서로 처리됩니다.

5.1 처리 순서

1. CSRF 토큰 검증
2. DxSms 클래스 존재 여부 확인
3. 문자 내용(sms_content) 필수 검증 — 빈 값이면 "문자 내용을 입력하세요." 오류
4. 수신자 목록 수집 (to_type에 따라 custom/all/role 분기)
5. 수신번호 정제: preg_replace('/[^0-9]/', '', $phone)으로 숫자만 추출
6. 10자리 미만 번호 제외
7. 유효한 수신자가 없으면 "유효한 수신번호가 없습니다." 오류
8. 단건(수신자 1명): DxSms::send() 호출
9. 다건(수신자 2명 이상): DxSms::sendBulk() 호출
10. 성공/실패 수 집계 후 결과 메시지 표시

5.2 단건 vs 대량 발송

구분	사용 메서드	특징
단건 발송	DxSms::send($to, $content, $options)	수신자 1명. 성공/실패를 boolean으로 반환. 실패 시 DxSms::getLastError()로 오류 확인.
대량 발송	DxSms::sendBulk($recipients, $content, $options)	수신자 2명 이상. 배열로 결과 반환: {ok: N, fail: M, errors: [...]}.

5.3 발송 결과 메시지

결과 색상	조건 및 내용
초록 (success)	실패 0건. "발송 완료: 성공 N건"
노랑 (warning)	성공·실패 모두 발생. "발송 완료: 성공 N건, 실패 M건 — 실패 오류 메시지(최대 3개)"
빨강 (error)	전체 실패(성공 0건). 상세 오류 메시지 표시.

6. 발송 로그 탭

[발송 로그] 탭에서 모든 SMS 발송 이력을 확인합니다. sms_logs 테이블에서 ID 내림차순(최신 순)으로 30건씩 조회됩니다.

6.1 로그 테이블 컬럼

컬럼	내용 및 설명
일시	발송 시각(created_at). YYYY-MM-DD HH:MM:SS 형식으로 표시.
드라이버	발송에 사용된 드라이버 ID(ncp/coolsms/kt/twilio). 회색 배지로 표시.
수신 수	발송을 시도한 총 수신자 수(to_count). 천 단위 쉼표 포함.
성공	발송 성공 건수(ok_count). 초록색 굵은 숫자.
실패	발송 실패 건수(fail_count). 0이면 회색, 1 이상이면 빨간색 굵은 숫자.
내용 미리보기	발송된 문자 내용의 앞부분(content_preview). 긴 내용은 잘려서 표시됩니다.

6.2 로그 페이지네이션

총 로그 수가 30건 초과 시 하단에 페이지 버튼이 표시됩니다. 최대 10페이지까지 버튼으로 이동 가능합니다. URL 파라미터: ?tab=log&p=N으로 특정 페이지 직접 접근 가능합니다.

7. 전체 사용 절차

7.1 처음 설정 절차

1. 관리자 대시보드 → [문자 서비스] 메뉴 클릭
2. [API 설정] 탭 클릭
3. 좌측에서 사용할 SMS 서비스 드라이버 클릭 (예: NCP SENS)
4. 해당 서비스 콘솔에서 API 키•시크릿•서비스 ID•발신번호를 복사
5. 설정 패널의 각 필드에 붙여넣기
6. [설정 저장] 버튼 클릭
7. 연결 테스트 영역에서 본인 번호 입력 후 [테스트 발송] 클릭
8. 실제 문자 수신 확인
9. 성공 시 [문자 발송] 탭으로 이동

7.2 문자 발송 절차

1. [문자 발송] 탭 클릭
2. 우측 발송 정보 패널에서 드라이버가 설정되어 있는지 확인
3. 수신 대상 선택: 직접 입력 / 전체 회원 / 역할별 중 하나 클릭
4. 직접 입력 선택 시: 전화번호 입력 (줄바꿈 또는 쉼표 구분)
5. 역할별 선택 시: 드롭다운에서 대상 권한 선택
6. 문자 유형 선택: AUTO(권장) / SMS / LMS / MMS
7. LMS•MMS 선택 시 제목 입력 (선택사항, 최대 40자)
8. 내용 입력 및 하단 글자 수/유형 힌트 확인
9. [문자 발송하기] 버튼 클릭
10. 발송 결과 메시지 확인 (성공 N건 / 실패 M건)
11. [발송 로그] 탭에서 이력 확인

8. 커스텀 드라이버 등록 (개발자)

dx_sms_drivers 훅으로 자체 SMS 서비스나 알리고, AWS SNS 등 새로운 드라이버를 플러그인으로 등록할 수 있습니다.

8.1 드라이버 등록 방법

DxSms::registerDriver()	드라이버 ID, 클래스명, 파일 경로(선택), prepend(최우선 적용 여부) 인자를 받습니다.
DxSmsDriverInterface	커스텀 드라이버가 반드시 구현해야 하는 인터페이스. getName/getDescription/isAvailable/getFields/getError/send 메서드 필요.
prepend=true	4번째 인자를 true로 설정하면 NCP보다도 높은 1순위로 사용됩니다.
훅 등록 위치	플러그인의 plugin.php 또는 테마의 functions.php에서 dx_add_hook("dx_sms_drivers", ...) 형태로 등록.

8.2 DxSmsDriverInterface 구현 메서드

메서드	역할 및 반환값
getName()	드라이버 표시 이름 반환. 예: "알리고(Aligo)".
getDescription()	드라이버 설명 반환. 예: "알리고 SMS API v2".
isAvailable()	드라이버가 사용 가능한지 여부 반환(bool). 필수 API 키가 모두 설정되어 있으면 true.
getFields()	관리자 UI 설정 패널에 표시할 필드 정의 배열 반환. label/key/type/required/placeholder 포함.
getError()	마지막 오류 메시지 문자열 반환.
send(DxSmsMessage $msg)	실제 문자 발송 처리 메서드. 성공 시 true, 실패 시 false 반환.

9. 자주 묻는 질문 (FAQ)

Q1. 문자 발송 버튼이 비활성화되어 있습니다.

A. 사용 가능한 SMS 드라이버가 설정되지 않은 상태입니다. [API 설정] 탭에서 SMS 서비스를 선택하고 API 키를 등록하세요. 저장 후 우측 발송 정보 패널의 "사용 드라이버"가 드라이버 이름으로 표시되어야 합니다.

Q2. 회원에게 문자를 보내려는데 수신 가능 회원이 0명입니다.

A. 회원 정보에 전화번호(phone 컬럼)가 등록되어 있어야 합니다. 회원 관리 페이지에서 회원의 전화번호를 등록하거나, 회원가입 폼에서 전화번호 입력을 받도록 설정하세요. status=1 이고 phone이 비어있지 않아야 합니다.

Q3. AUTO 유형으로 발송했는데 90자 이내 내용이 LMS로 발송되었습니다.

A. AUTO 유형은 DXCMS 서버에서 type 옵션을 전달하지 않고 각 SMS 드라이버의 자체 판단에 맡깁니다. 드라이버별로 AUTO 처리 방식이 다를 수 있습니다. 정확히 SMS로 보내려면 유형을 "SMS"로 명시적으로 선택하세요.

Q4. 발송은 성공했는데 실제로 문자가 오지 않습니다.

A. 다음을 확인하세요: ① 수신번호가 차단된 번호가 아닌지 확인. ② 해당 SMS 서비스 콘솔에서 실제 발송 내역을 확인. ③ 스팸 차단 앱이 문자를 차단했는지 확인. ④ 발신번호가 회신 차단되지 않았는지 확인.

Q5. NCP SENS 발신번호를 어디서 등록하나요?

A. NCP 콘솔(console.ncloud.com) 접속 → Products & Services → Notification → Simple & Easy Notification Service(SENS) → 발신번호 관리 → 발신번호 등록. 등록 후 심사(보통 1~2 영업일)가 완료되어야 발송이 가능합니다.

Q6. 발송 로그에 기록이 남지 않습니다.

A. sms_logs 테이블이 DB에 존재해야 합니다. 테이블이 없으면 로그 기록이 되지 않습니다. DxSms 클래스의 발송 성공 시 sms_logs 테이블에 INSERT가 수행됩니다. 테이블이 없다면 CREATE TABLE sms_logs를 수동으로 실행하거나 DB 마이그레이션을 확인하세요.

Q7. 여러 SMS 서비스를 등록해두면 자동 전환이 되나요?

A. 네. 드라이버를 "자동 감지(auto)"로 설정하면 NCP → CoolSMS → KT → Twilio 순서로 isAvailable()이 true인 드라이버를 선택합니다. 단, 발송 실패 시 자동으로 다음 드라이버로 재시도하지는 않습니다. 자동 감지는 초기 드라이버 선택 시에만 동작합니다. 

10. 용어 정리

용어	설명
DxSms	DXCMS SMS 발송 핵심 클래스. 드라이버 자동 감지·선택, 단건/대량 발송, 로그 기록 담당.
DxSmsDriverInterface	모든 SMS 드라이버가 구현해야 하는 인터페이스. getName/getDescription/isAvailable/getFields/getError/send 메서드 정의.
DxNcpSmsDriver	NCP SENS API를 사용하는 드라이버 클래스.
DxCoolSmsDriver	CoolSMS API v4를 사용하는 드라이버 클래스.
DxKtBizmekaDriver	KT Bizmeka API를 사용하는 드라이버 클래스.
DxTwilioDriver	Twilio API를 사용하는 드라이버 클래스.
sms_driver	settings 테이블 저장 키. 선택된 드라이버 ID(ncp/coolsms/kt/twilio/auto).
sms_ncp_access_key	NCP API 액세스 키.
sms_ncp_secret_key	NCP API 시크릿 키. 비밀번호형: 빈 값 입력 시 기존 값 유지.
sms_ncp_service_id	NCP SENS 서비스 ID. "ncp:sms:kr:..." 형식.
sms_ncp_from / sms_coolsms_from / sms_kt_from / sms_twilio_from	각 서비스에 등록된 발신번호.
sms_coolsms_api_key / sms_coolsms_api_secret	CoolSMS API 키 및 시크릿.
sms_kt_apikey / sms_kt_userid	KT Bizmeka API 키 및 사용자 ID.
sms_twilio_account_sid / sms_twilio_auth_token	Twilio Account SID 및 Auth Token.
SMS	단문 메시지. 최대 90자.
LMS	장문 메시지. 최대 2,000자. 제목(40자) 설정 가능.
MMS	멀티미디어 메시지. 이미지 첨부 가능. 드라이버별 지원 여부 다름.
AUTO	문자 유형 자동 감지 모드. 내용 길이에 따라 SMS/LMS를 드라이버가 자체 판단.
to_type	수신 대상 유형. custom(직접 입력)/all(전체 회원)/role(역할별).
sms_logs	SMS 발송 이력 테이블. created_at/driver/to_count/ok_count/fail_count/content_preview 컬럼.
DxSms::send()	단건 문자 발송 메서드. bool 반환.
DxSms::sendBulk()	대량 문자 발송 메서드. {ok, fail, errors} 배열 반환.
DxSms::getLastError()	마지막 발송 오류 메시지 반환.
DxSms::flushCache()	드라이버 캐시 초기화 메서드.
dx_sms_drivers	커스텀 SMS 드라이버를 등록하는 DXCMS 훅 이름.
isAvailable()	드라이버의 필수 API 키가 설정된 경우 true를 반환. 자동 감지 시 이 값을 기준으로 드라이버 선택.