본문으로 건너뛰기

보이스 옵션

메시지 발송 참고

// [POST] https://api.solapi.com/messages/v4/send-many/detail
{
  messages: [{
    to: '01000000000',
    from: '020000000',
    text: '음성 메시지 입니다. 최대 1, 최대 980byte(한글 490자)까지 입력가능니다.', 
    voiceOptions: {
      voiceType: `'MALE', 'FEMALE' (보이스 타입 '남자', '여자')`,
      headerMessage: `머리말, 통화 시작시 나오는 메시지 (최대 135자까지)`,
      tailMessage: `맺음말, 통화가 끝나고 나오는 메시지, 상담원 연결 시 나오지 않음, 머리말이 있어야 적용됨 (최대 135자까지)`,
      replyRange: `통화 내용이 나온 후 1~9번까지의 버튼으로 받는 답변 (수신자에게서 입력받을 숫자, 1~9)
EX) 안녕하십니까. 쇼핑몰 사이트를 이용해주셔서 감사합니다. 제공해드리는 상품에 대한 만족도를 선택해주세요.
1번 만족. 2번 보통. 3번 불만족`,
      counselorNumber: `상담원번호, 번호 입력 시 통화 내용이 나온 후 0번을 누르면 상담원 연결 (replyRange와 병행 불가능)`
    }
  }]
}

보이스 메시지 시나리오

  • replyRange만 사용

    • 본문 내용 → DTMF 수집 → 종료

  • headerMessage, replyRange 사용

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

  • headerMessage, tailMessage, replyRange 사용

    • 헤더 메시지 → 아무 버튼이나 입력 → 본문 내용 → DTMF 수집 → 테일 메시지 → 종료

  • counselorNumber만 사용

    • 본문 내용 → 0번 누르면 고객센터 연결
      (이외의 버튼 누를 시 ‘잘못 누르셨습니다’ 멘트 나옴)

  • headerMessage, counselorNumber 사용 (tailMessage 같이 사용해도 동일)

    • 헤더 메시지 → 아무 버튼이나 입력 → 본문 내용 → 0번 누르면 고객센터 연결
      (이외의 버튼 누를 시 ‘잘못 누르셨습니다’ 멘트 나옴)

참고: 버튼을 잘못 입력하면 세 번째에 멘트가 나오고 통화 종료됩니다.

보이스 태그 사용 가이드

1. 태그 형식 (Tag Format)​

1.1 값 없이 사용되는 태그​

<tag>text</tag>

예시:

<spell>apple</spell>

1.2 값을 직접 지정하는 태그​

<tag="tag_value"/>
<tag="tag_value">text</tag>

예시:

<speed="150">apple</speed>

1.3 속성을 사용하는 태그​

<tag attribute="tag_value">text</tag>

예시:

<date format="yyyymmdd">20150624</date>

1.4 별도의 속성값을 적용하는 경우​

<tag attribute="tag_value">text</tag>

예시:

<date format="yyyymmdd">20150624</date>

2. 태그 입력 시 주의사항​

  • 대소문자 구분 없음
  • 모든 tag_value는 쌍따옴표(" ")로 감싸야 함
  • </tag>는 범위 지정 시에만 사용
  • 중첩(nested) 구조는 지원하지 않음
  • 태그는 메시지 마지막에 두지 말 것
    예) <emphasis>감사합니다.</emphasis>

비권장 예시:

<speed="150">S1<speed="80">S2</speed>S3</speed>

S3는 기본값으로 합성됨

3. 태그 상세 설명​

태그는 음성 메시지에서 특정 단어나 문장의 **읽는 방식(속도, 높낮이, 멈춤 등)**을 조절하는 도구입니다.
자연스럽고 듣기 좋은 음성을 만들기 위해 사용됩니다.

사용 예시 코드​

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

3.1 <speed>​

음성의 속도를 조절합니다.

값 형식​

패턴설명
50~200절대값을 설정합니다. 기본값은 100입니다.
-50%~+100%기본값(100)을 기준으로 -50%에서 +100% 범위로 값을 설정합니다.

예시:​

<speed="150">빠르게</speed>
<speed="-50%">느리게</speed>

3.2 <volume>​

음성의 음량을 조절합니다.

값 형식​

패턴설명
50~200절대값을 설정합니다. 기본값은 100입니다.
-100%~+100%기본값(100)을 기준으로 -100%에서 +100% 범위로 값을 설정합니다.

예시:​

<volume="200">크게</volume>
<volume="-50%">작게</volume>

3.3 <pitch>​

음성의 높이를 조절합니다.

값 형식​

패턴설명
50~200절대값을 설정합니다. 기본값은 100입니다.
-20%~+20%기본값(100)을 기준으로 -20%에서 +20% 범위로 값을 설정합니다.

예시:​

<pitch="120">높게</pitch>
<pitch="-20%">낮게</pitch>

3.4 <emphasis>​

지정된 범위의 단어 및 구문을 강조해서 읽습니다.

값 형식​

패턴설명
strong강하게 읽습니다.
moderate적절한 강세로 읽습니다. 'level'에 값이 없으면 이 값을 기본으로 사용합니다.

예시:​

<emphasis level="strong">강조된 단어</emphasis>
<emphasis>기본 강조</emphasis>

3.5 <pause>​

설정된 시간만큼 묵음 처리를 합니다.

값 형식​

패턴설명
100~10000100(ms) ~ 10000(ms) 사이의 시간을 설정할 수 있습니다.

예시:​

안녕하세요.<pause="1000"> 반갑습니다.

3.6 <syll>​

알파벳/숫자/한자/한글 등을 한 자씩 끊어 읽습니다.

예시:​

<syll>ABC123</syll>

3.7 <date>​

숫자를 지정한 형식에 맞춰 날짜로 읽습니다. 구분자(':','-','/')로 분리된 숫자 형태도 지원합니다.
숫자는 ','(콤마)나 '.'(온점)이 없어야 하며, 월과 일의 범위를 벗어나면 안됩니다.

값 형식​

패턴설명
<date>150624</date>숫자의 자리수에 따라서 읽는 방법이 달라집니다.
8자리 숫자 → yyyymmdd
6자리 숫자 → yymmdd
4자리 숫자 → mmdd

예시:​

<date>20150624</date> // 2015년 6월 4일
<date>0624</date> // 6월 4일

3.8 <time>​

숫자를 지정한 형식에 맞춰 시간으로 읽습니다. 기본적으로 24시간 스타일로 읽습니다.
구분자(':')로 분리된 숫자 형태도 지웝합니다.
숫자는 ','(콤마)나 '.'(온점)이 없어야 합니다.

값 형식​

패턴설명
<time>125353</time>숫자의 자리수에 따라서 읽는 방법이 달라집니다.
6자리 숫자 → 24시간 스타일로 시간, 분, 초 순서로 읽습니다.
4자리 숫자 → 24시간 스타일로 시간, 분 순서로 읽습니다.
format="hhmm"어떤 형태로 읽을 건지 설정할 수 있습니다.
h=hour, m=minute, s=second를 사용합니다.
format과 숫자의 길이가 다르면 처리하지 않습니다.
format값 뒤에 12나 24를 붙여 읽는 형식을 바꿀 수 있습니다.

예시:​

<time>122530</time> // 12시 25분 30초
<time format="hhmmss12">122530</time> // 오후 12시 25분 30초
<time format="hhmm24">1225</time> // 12시 25분

3.9 <digit>​

숫자를 읽는 방법을 지정합니다.
한 자리씩 끊어 읽거나 지정된 자리에서 끊어 읽도록 지정할 수 있습니다.

값 형식​

패턴설명
format="64"숫자를 읽을 때 정의된 형태로 끊어읽습니다.
값이 64라면 뒤에서부터 4번째 자리에서 끊어 읽습니다.
값이 64라면 6+4인 10자리가 아닌 숫자를 입력하면 각 자리마다 끊어 읽습니다.
pause="1000"끊어 읽을 때 사이에 쉬는 값의 범위입니다.
10(ms) ~ 3000(ms) 사이의 시간을 설정할 수 있습니다.
기본 값은 200(ms)입니다.

예시:​

<digit format="64" pause="600">1234567890</digit>

3.10 <money>​

숫자를 지정한 형식에 맞춰 금액으로 읽습니다. 지정된 자리마다 끊어 읽습니다.
type은 1,3,4값이 있으며 1은 각 자리마다, 3은 뒤에서 부터 세번째 자리마다, 4는 뒤에서 부터 네번째 자리마다 끊어 읽습니다.
숫자에는 ','(콤마)나 '.'(온점)은 없어야 합니다.

값 형식​

패턴설명
type="1"1 → 각 자리마다 끊어 읽습니다.
3 → 숫자의 뒤에서부터 세 자리마다 끊어 읽습니다.
4 → 숫자의 뒤에서부터 네 자리마다 끊어 읽습니다.
pause="1000"끊어 읽을 때 사이에 쉬는 값의 범위입니다.
10(ms) ~ 3000(ms) 사이의 시간을 설정할 수 있습니다.
기본 값은 200(ms)입니다.

예시:​

<money type="3" pause="80">12345원</money>

참고사항 🔖

  • 전원이 꺼져 있거나 비행기 모드일 경우, 수신자가 음성사서함으로 연결되면서 **추가 요금(시간/초 단위 과금)**이 발생할 수 있습니다.
    이러한 상황을 원치 않으실 경우, 관련 부가서비스를 비활성화(해제) 해주시기 바랍니다.

  • 음성 메시지가 정상적으로 전달된 이후, 수신자가 직접 수신을 거부한 경우에는
    이미 발생한 기본 요금은 환급되지 않습니다.

  • 음성 발신 시, 수신 측에서는 기본적으로 약 30~40초 동안 전화벨이 울리며,
    응답이 없을 경우 자동으로 종료됩니다.

  • 수신 번호가 유효하지만 통화 연결이 실패할 경우, 시스템은 1분 간격으로 최대 3회까지 자동 재시도를 진행합니다.

  • 모든 음성 메시지는 통화 연결 시, 기본 요금 외에 초당 추가 요금이 부과됩니다.

  • 고객센터 연결 기능을 통해 통화하는 시간 역시 초당 추가 요금이 부과됩니다.