본문으로 건너뛰기

음성 메시지

기본 설정​

API 엔드포인트​

POST /messages/v4/send-many/detail
Base URL: https://api.solapi.com

voiceOptions 파라미터​

파라미터 타입 설명 제한사항
voiceType String 음성 타입 MALE, FEMALE
headerMessage String 통화 시작 메시지 최대 135자
tailMessage String 통화 종료 메시지 최대 135자, headerMessage 필수
replyRange Number DTMF 입력 범위 1~9
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️⃣ 0번 누르면 고객센터 연결
❌ 다른 버튼: "잘못 누르셨습니다" 안내

headerMessage + counselorNumber​

📢 헤더 메시지
→
⌨️ 아무 버튼 입력
→
📞 본문 내용
→
0️⃣ 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> 사용
  • 태그는 메시지 중간에 배치

잘못된 사용법​

1. 중첩 구조 사용 (지원하지 않음)

<!-- S3는 기본값으로 합성됨 -->
<speed="150">S1<speed="80">S2</speed>S3</speed>

2. 메시지 마지막에 태그 배치

안녕하세요. <emphasis>감사합니다.</emphasis>

3. 잘못된 따옴표 사용

<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 상세