음성 메시지
API 엔드포인트
POST
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 상세