음성 메시지

텍스트를 음성으로 변환(TTS)하여 수신자에게 전화로 전달하는 음성 메시지 API입니다.

입력한 텍스트를 남성 또는 여성 음성으로 자동 변환하여 수신자에게 전화를 걸고 내용을 읽어줍니다. 통화 시작 전 머리말, 통화 종료 후 맺음말을 추가할 수 있으며, 수신자의 버튼 입력을 받거나 상담원 연결 기능도 지원합니다.

발송 방법

음성 메시지는 별도의 전용 API가 아닌, 기존 그룹 메시지 API를 통해 발송합니다. 메시지의 type을 VOICE로 지정하면 음성 메시지로 처리됩니다.

발송 흐름은 다른 메시지 타입과 동일합니다

1. 그룹 생성 — POST /messages/v4/groups

2. 메시지 추가 — PUT /messages/v4/groups/:groupId/messages (type: VOICE)

3. 발송 요청 — POST /messages/v4/groups/:groupId/send

그룹 메시지 API의 전체 사용법은 그룹 메시지 API 문서를 참조하세요.

메시지 구조

음성 메시지를 그룹에 추가할 때 사용하는 메시지 객체 구조입니다.

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "안녕하세요. 예약하신 시간은 3월 15일 오후 2시입니다.",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "headerMessage": "솔라피 안내 전화입니다.",
        "tailMessage": "감사합니다. 좋은 하루 되세요."
      }
    }
  ]
}

필수 필드

선택 필드

주의: 발신번호(from)와 수신번호(to)는 동일할 수 없습니다.

voiceOptions 상세

음성 메시지의 동작을 세부적으로 제어하는 옵션입니다. 모든 필드는 선택 사항입니다.

{
  "voiceOptions": {
    "voiceType": "FEMALE",
    "headerMessage": "머리말 메시지",
    "tailMessage": "맺음말 메시지",
    "replyRange": 3,
    "counselorNumber": "0212345678",
    "variables": {
      "#{이름}": "홍길동",
      "#{시간}": "오후 2시"
    }
  }
}

필드 설명

통화 재생 순서

1. headerMessage (머리말)  →  설정된 경우에만 재생
2. text (본문)             →  항상 재생
3. tailMessage (맺음말)    →  설정된 경우에만 재생 (상담원 연결 시 재생되지 않음)
4. replyRange 또는 counselorNumber에 따른 입력 대기

대체 문구 (변수 치환)

text, headerMessage, tailMessage에 #{변수명} 형태의 변수를 포함하고, voiceOptions.variables에 치환할 값을 지정할 수 있습니다.

{
  "to": "01012345678",
  "from": "0212345678",
  "type": "VOICE",
  "text": "#{이름}님, 예약하신 #{날짜} #{시간}에 방문 예정입니다.",
  "voiceOptions": {
    "voiceType": "FEMALE",
    "headerMessage": "#{이름}님께 안내 전화 드립니다.",
    "variables": {
      "#{이름}": "홍길동",
      "#{날짜}": "3월 15일",
      "#{시간}": "오후 2시"
    }
  }
}

치환 후 재생되는 내용

• 머리말: "홍길동님께 안내 전화 드립니다."

• 본문: "홍길동님, 예약하신 3월 15일 오후 2시에 방문 예정입니다."

유효성 검증 규칙

음성 메시지 추가 시 아래 규칙에 따라 유효성 검증이 수행됩니다. 검증에 실패하면 해당 메시지는 추가되지 않습니다.

발송 예시

기본 음성 메시지

가장 간단한 형태의 음성 메시지입니다. 기본 음성 설정으로 본문만 재생됩니다.

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "안녕하세요. 내일 오전 10시에 미팅이 예정되어 있습니다."
    }
  ]
}

머리말/맺음말 포함

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "주문하신 상품이 발송되었습니다. 배송 예정일은 3월 12일입니다.",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "headerMessage": "솔라피 쇼핑몰 안내 전화입니다.",
        "tailMessage": "감사합니다. 좋은 하루 되세요."
      }
    }
  ]
}

수신자 응답 받기 (replyRange)

통화 내용 재생 후 수신자에게 1~3번 버튼 입력을 받습니다.

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "3월 15일 오후 2시 예약을 확인합니다. 확인은 1번, 변경은 2번, 취소는 3번을 눌러주세요.",
      "voiceOptions": {
        "voiceType": "MALE",
        "headerMessage": "솔라피 병원 예약 안내입니다.",
        "replyRange": 3
      }
    }
  ]
}

상담원 연결 (counselorNumber)

통화 내용 재생 후 수신자가 0번을 누르면 상담원 번호로 연결됩니다.

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "카드 결제 이상 거래가 감지되었습니다. 본인이 아닌 경우 상담원 연결을 위해 0번을 눌러주세요.",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "headerMessage": "솔라피 카드 보안 안내입니다.",
        "counselorNumber": "0215551234"
      }
    }
  ]
}

대량 발송 (변수 치환 활용)

수신자별로 다른 내용을 발송할 때 변수 치화늘 활용합니다.

{
  "messages": [
    {
      "to": "01012345678",
      "from": "0212345678",
      "type": "VOICE",
      "text": "#{이름}님, #{날짜} #{시간}에 예약이 확인되었습니다.",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "variables": {
          "#{이름}": "홍길동",
          "#{날짜}": "3월 15일",
          "#{시간}": "오후 2시"
        }
      }
    },
    {
      "to": "01098765432",
      "from": "0212345678",
      "type": "VOICE",
      "text": "#{이름}님, #{날짜} #{시간}에 예약이 확인되었습니다.",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "variables": {
          "#{이름}": "김철수",
          "#{날짜}": "3월 16일",
          "#{시간}": "오전 10시"
        }
      }
    }
  ]
}

응답에서의 음성 메시지 필드

메시지 목록 조회 API에서 음성 메시지를 조회하면 일반 메시지 필드 외에 아래 추가 필드가 포함됩니다.

음성 전용 필드

응답 예시

{
  "messageList": {
    "M4V20260310143025ABCDEFGHIJKLMNO": {
      "messageId": "M4V20260310143025ABCDEFGHIJKLMNO",
      "groupId": "G4V20260310143020ABCDEFGHIJKLMNO",
      "accountId": "24010100001234",
      "to": "01012345678",
      "from": "0212345678",
      "text": "안녕하세요. 예약하신 시간은 3월 15일 오후 2시입니다.",
      "type": "VOICE",
      "country": "82",
      "status": "COMPLETE",
      "statusCode": "4000",
      "reason": "정상 처리",
      "dateCreated": "2026-03-10T05:30:25.000Z",
      "dateUpdated": "2026-03-10T05:31:00.000Z",
      "voiceOptions": {
        "voiceType": "FEMALE",
        "headerMessage": "솔라피 안내 전화입니다.",
        "tailMessage": "감사합니다."
      },
      "voiceReplied": 0,
      "voiceDuration": 15
    }
  },
  "limit": 20,
  "startKey": null,
  "nextKey": null
}