친구톡 발송

Prev Next

Classic/VPC 환경에서 이용 가능합니다.

친구 맺은 사용자를 대상으로 하는 친구톡 메시지를 발송합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드 URI
POST /friendtalk/v2/services/{serviceId}/messages

요청 헤더

Simple & Easy Notification Service API에서 공통으로 사용하는 헤더에 대한 정보는 Simple & Easy Notification Service 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
serviceId String Required Biz Message 서비스 아이디

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
plusFriendId String Required 채널 아이디
messages Array Required 메시지 정보
  • 최대 100건 입력 가능
reserveTime String Optional 예약 일시
  • YYYY-MM-DD HH:mm 형식
  • 예약 발송할 경우, 입력
reserveTimeZone String Optional 예약 타임존

messages

messages에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
isAd Boolean Optional 광고 메시지 여부
  • true (기본값) | false
    • true: 광고 메시지
    • false: 광고 메시지 아님
  • SMS 대체 발송 실행 시 광고 메시지 전송 표기 의무를 준수해야 함
countryCode String Optional 국가 코드
to String Required 수신 번호
  • 숫자만 입력 가능
content String Required 메시지 내용
buttons Array Optional 메시지 버튼 정보
image Object Optional 이미지 정보
image.imageId String Conditional 이미지 아이디
  • 이미지를 추가하는 경우, 필수 입력
image.imageLink String Conditional 이미지 URL
  • 이미지를 추가하는 경우, 필수 입력
useSmsFailover Boolean Optional SMS 대체 발송 사용 여부
  • true | false
    • true: 사용
    • false: 사용 안 함
  • 기본값: 카카오톡 채널의 설정을 따름
  • 대체 발송이 설정된 카카오톡 채널에서만 사용 가능
failoverConfig Object Optional 대체 발송 설정
failoverConfig.type String Optional 메시지 타입
  • SMS | LMS
    • SMS: SMS 메시지
    • LMS: LMS 메시지
  • 미입력 시 메시지 내용 길이에 따라 자동 적용
    • 90 bytes 이하: SMS
    • 90 bytes 초과: LMS
failoverConfig.from String Optional 발신 번호
failoverConfig.subject String Optional 메시지 제목
  • 미입력 시 채널 이름으로 적용
  • LMS에서만 사용 가능
failoverConfig.content String Optional 메시지 내용
  • 미입력 시 친구톡 메시지 내용으로 적용(버튼 제외)
참고
  • SMS 대체 발송 기능은 Biz Message 수신 결과 코드를 기준으로 성공하지 않은 경우에 동작하며, 'B' 접두어가 붙은 코드일 경우에는 동작하지 않습니다.
  • 광고 메시지 발송 시 SMS 대체 발송에 설정된 SMS 서비스의 080수신거부 서비스를 사용합니다.
    • 설정된 SMS 서비스에 080수신거부 서비스가 사용 가능한 상태가 아니라면, SMS 대체 발송은 실패합니다.
    • failoverConfig.content를 별도로 지정하지 않고 사용하는 경우, SMS 대체 발송 시 자동으로 광고 표기 문구가 삽입됩니다.
    • failoverConfig.content를 별도로 직접 지정하는 경우, 광고 표기 문구가 자동으로 삽입되지 않으므로 직접 추가해 주십시오.
    • 광고 표기 의무를 준수하지 않은 SMS 메시지 발송 시, 추후 소명이 필요할 수 있습니다.
  • 와이드 이미지 발송 시, 텍스트 + 링크 버튼(1개) + 이미지 발송이 가능합니다.
    • 2개 이상의 버튼 추가시, 메시지 발송에 실패합니다. (잘못된 파라미터 요청)
    • 텍스트 문구는 76자로 제한됩니다.

buttons

buttons에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
type String Required 버튼 유형
  • WL | AL | BK | MD | AC
    • WL: 웹 링크
    • AL: 앱 링크
    • BK: 봇 키워드
    • MD: 메시지 전달
    • AC: 채널 추가
name String Required 버튼 이름
  • 최대 20자
  • type이 AC인 경우, 채널 추가로 입력
linkMobile String Optional 모바일 웹 링크
  • type이 WL인 경우, 필수 입력
linkPc String Optional PC 웹 링크
  • type이 WL인 경우, 필수 입력
schemeIos String Optional iOS 앱 링크
  • type이 AL인 경우, 필수 입력
schemeAndroid String Optional Android 앱 링크
  • type이 AL인 경우, 필수 입력

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://sens.apigw.ntruss.com/friendtalk/v2/services/ncp:kkobizmsg:kr:27*********6:sens/messages' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
    "plusFriendId": "@******",
    "messages": [
        {
            "countryCode": "82",
            "to": "010********",
            "content": "2025년 12월 1일부터 10일까지 페스티벌이 열립니다. 많은 참여와 관심 부탁드립니다.",
            "buttons": [
                {
                    "type": "AC",
                    "name": "채널 추가"
                }
            ],
            "image": {
                "imageId": "a15c7206-****-****-****-57adec9e48f9",
                "imageLink": "https://mud-kage.kakao.com/dn/dccjAa/***********/**********************/img_l.jpg"
            },
            "useSmsFailover": true,
            "failoverConfig": {
                "type": "LMS",
                "from": "010********"
            }
        }
    ]
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
requestId String - 요청 아이디
requestTime String - 요청 일시
  • YYYY-MM-DDTHH:mm:ss.sss 형식
statusCode String - 상태 코드
  • HTTP 상태 코드 규칙을 따름
statusName String - 상태
  • success | processing | reserved | fail
    • success: 성공
    • processing: 처리중
    • reserved: 예약
    • fail: 실패
messages Array - 메시지 정보
  • 즉시 발송인 경우, 표시

messages

messages에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
messageId String - 메시지 아이디
countryCode String - 국가 코드
to String - 수신 번호
content String - 메시지 내용
requestStatusCode String - 요청 상태 코드
  • A000: 성공
  • 그 외: 실패
requestStatusName String - 요청 상태
  • success | fail
    • success: 성공
    • fail: 실패
requestStatusDesc String - 요청 상태 설명
useSmsFailover Boolean - SMS 대체 발송 사용 여부
  • true | false
    • true: 사용
    • false: 사용 안 함

응답 상태 코드

Simple & Easy Notification Service API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Simple & Easy Notification Service 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "requestId": "RBFA-*************-****-********-oTlbUtlO",
    "requestTime": "2025-11-25T15:32:07.826",
    "statusCode": "202",
    "statusName": "processing",
    "messages": [
        {
            "messageId": "ace5ea34-****-****-****-56ddbe21b384",
            "countryCode": "82",
            "to": "010********",
            "content": "2025년 12월 1일부터 10일까지 페스티벌이 열립니다. 많은 참여와 관심 부탁드립니다.",
            "requestStatusCode": "A000",
            "requestStatusName": "success",
            "requestStatusDesc": "성공",
            "useSmsFailover": true
        }
    ]
}