본문으로 건너뛰기

음성 메시지

API 엔드포인트​

POST
/messages/v4/send-many/detail

voiceOptions 파라미터​

파라미터타입제한사항설명
voiceType
String
MALE, FEMALE
음성 타입
headerMessage
String
최대 135자
통화 시작 메시지
tailMessage
String
최대 135자, headerMessage 필수
통화 종료 메시지
replyRange
Number
1~9
DTMF 입력 범위
counselorNumber
String
replyRange와 병행 불가
상담원 연결 번호

기본 요청 예시
{
  messages: [{
    to: '01000000000',
    from: '0200000000',
    text: '음성 메시지입니다. 최대 1, 980byte(한글 490자)까지 입력 가능합니다.',
    type: 'VOICE',
    voiceOptions: {
      voiceType: 'FEMALE',
      headerMessage: '안녕하세요. 솔라피 쇼핑몰입니다.',
      tailMessage: '감사합니다. 좋은 하루 되세요.',
      replyRange: 3
    }
  }]
}

시나리오별 동작​

replyRange만 사용​

본문 내용
DTMF 수집
종료

headerMessage + replyRange​

헤더 메시지
아무 버튼 입력
본문 내용
DTMF 수집
종료

headerMessage + tailMessage + replyRange​

헤더
버튼
본문
DTMF
테일
종료

counselorNumber만 사용​

본문 내용
0번 누르면 고객센터 연결
다른 버튼: "잘못 누르셨습니다" 안내

headerMessage + counselorNumber​

헤더 메시지
아무 버튼 입력
본문 내용
0번 누르면 고객센터 연결
다른 버튼: "잘못 누르셨습니다" 안내
주의

3번 잘못 입력하면 안내 후 통화가 종료됩니다.

음성 태그 가이드​

음성 태그는 텍스트를 음성으로 변환할 때 특정 단어나 문장의 읽는 방식을 세밀하게 조절하는 기능입니다. 읽기 속도, 음량, 강조, 발음 등을 제어하여 더욱 자연스럽고 듣기 좋은 음성 메시지를 만들 수 있습니다.

태그 기본 규칙​

항목지원설명
대소문자
O
구분하지 않음
값 형식
O
모든 값은 쌍따옴표(" ") 필수
중첩 구조
-
지원하지 않음
메시지 끝
-
태그를 마지막에 두지 말 것

태그 형식​

형식구조예시
값 없음
<tag>text</tag>
<spell>apple</spell>
<emphasis>중요한 내용</emphasis>
값 직접 지정
<tag="value">text</tag>
<speed="150">빠르게 읽을 텍스트</speed>
<volume="80">조용히 말할 부분</volume>
속성 사용
<tag attribute="value">text</tag>
<date format="yyyymmdd">20150624</date>

주의사항 및 제한사항​

중요

올바른 사용법​

  • 대소문자 구분하지 않음: <Speed>, <SPEED>, <speed> 모두 동일
  • 쌍따옴표 필수: <speed="150">
  • 범위 지정 시에만 </tag> 사용
  • 태그는 메시지 중간에 배치

잘못된 사용법​

중첩 구조 사용 (지원하지 않음)
// S3는 기본값으로 합성됩니다
<speed="150">S1<speed="80">S2</speed>S3</speed>
메시지 마지막에 태그 배치
안녕하세요. <emphasis>감사합니다.</emphasis>
잘못된 따옴표 사용
// 작은따옴표
<speed='150'>텍스트</speed>

// 따옴표 없음
<speed=150>텍스트</speed>
팁

자주 사용되는 태그 예시​

태그용도예시
<speed>
읽기 속도 조절
<speed="120">천천히</speed>
<volume>
음량 조절
<volume="80">작은 소리로</volume>
<emphasis>
강조
<emphasis>중요한 부분</emphasis>
<spell>
철자 읽기
<spell>Solapi</spell>
<date>
날짜 형식
<date format="yyyymmdd">20240101</date>
<number>
숫자 형식
<number type="cardinal">1000</number>

음성 제어 태그​

<speed> - 속도 조절​

설정 방식범위예시
절대값
50~200 (기본값: 100)
<speed="150">빠르게</speed>
상대값
-50%~+100%
<speed="-50%">느리게</speed>

<volume> - 음량 조절​

설정 방식범위예시
절대값
50~200 (기본값: 100)
<volume="200">크게</volume>
상대값
-100%~+100%
<volume="-50%">작게</volume>

<pitch> - 음높이 조절​

설정 방식범위예시
절대값
50~200 (기본값: 100)
<pitch="120">높게</pitch>
상대값
-20%~+20%
<pitch="-20%">낮게</pitch>

<emphasis> - 강조​

레벨설명예시
strong
강하게 강조
<emphasis level="strong">중요한 내용</emphasis>
moderate
적당히 강조 (기본값)
<emphasis>기본 강조</emphasis>

<pause> - 묵음​

범위단위예시
100~10000
밀리초(ms)
안녕하세요.<pause="1000">반갑습니다.

데이터 형식 태그​

<date> - 날짜 읽기​

자릿수형식예시읽는 방법
8자리
yyyymmdd
<date>20150624</date>
2015년 6월 24일
6자리
yymmdd
<date>150624</date>
15년 6월 24일
4자리
mmdd
<date>0624</date>
6월 24일

<time> - 시간 읽기​

자릿수기본 형식예시읽는 방법
6자리
hhmmss
<time>125353</time>
12시 25분 53초
4자리
hhmm
<time>1225</time>
12시 25분

<digit> - 숫자 끊어 읽기​

속성설명예시범위
format
끊어 읽을 자릿수
<digit format="64" pause="600">1234567890</digit>
예: "64" = 뒤에서 4번째 자리에서 끊기
pause
간격 시간
-
10~3000ms (기본값: 200ms)

<money> - 금액 읽기​

type 값끊어 읽는 방식예시설명
1
각 자리마다
<money type="1" pause="80">12345원</money>
1|2|3|4|5
3
뒤에서 3자리마다
<money type="3" pause="80">12345원</money>
12|345
4
뒤에서 4자리마다
<money type="4" pause="80">12345원</money>
1|2345

<syll> - 한 글자씩 읽기​

태그설명예시결과
<syll>
알파벳/숫자/한자/한글을 한 글자씩 끊어 읽기
<syll>ABC123</syll>
A-B-C-1-2-3

팁

활용 예시
{
  to: '01012345678',
  from: '0212345678',
  text: `최근 저희 쇼핑몰을 이용하신 경험은 어떠셨나요?<pause="800">
<emphasis level="moderate">1번, 매우 만족</emphasis><pause="800">
<emphasis level="moderate">2번, 보통이에요</emphasis><pause="800">
<emphasis level="moderate">3번, 아쉬웠어요</emphasis><pause="800">
해당하는 번호를 눌러주세요.`,
  type: 'VOICE',
  voiceOptions: {
    voiceType: 'FEMALE',
    replyRange: 3,
    headerMessage: `안녕하세요. <emphasis>ABC 쇼핑몰</emphasis>입니다.<pause="800">
더 나은 서비스 제공을 위해 잠시 설문을 부탁드립니다.<pause="800">
계속하시려면 아무 버튼이나 눌러주세요.`,
    tailMessage: `참여해주셔서 진심으로 감사합니다.<pause="800">오늘도 행복한 하루 되세요.`
  }
}

요금 및 주의사항​

통화 요금 정책​

상황요금설명
기본 연결
기본 요금
통화 연결 시 발생
통화 시간
초당 추가 요금
연결 후 시간당 과금
상담원 연결
초당 추가 요금
counselorNumber 기능 사용 시
음성사서함
시간당 과금
전원 꺼짐/비행기 모드 시
주의

전원 꺼짐/비행기 모드: 음성사서함 연결 시 추가 요금 발생 → 원치 않으면 관련 부가서비스 비활성화 필요

수신 거부: 정상 전달 후 수신자가 거부한 경우 기본 요금 환급 불가

통화 시도: 30~40초간 전화벨 후 자동 종료

재시도 정책: 연결 실패 시 1분 간격으로 최대 3회 자동 재시도

링크

참고 문서: 메시지 발송 API 상세