개발자 가이드
Start typing to search…

카카오 메시지(친구톡) 발송하기

친구톡은 카카오톡 비즈니스 채널과 친구 관계를 맺은 사용자에게 발송할 수 있는 메시지 서비스입니다. 알림톡과 달리 자유로운 메시지 내용 작성이 가능하며, 이미지와 버튼 등을 포함한 풍부한 콘텐츠 전달이 가능합니다.

친구톡의 주요 특징

친구톡은 다음과 같은 특징을 가지고 있습니다:

  • 알림톡과 달리 사전 템플릿 검수가 필요하지 않습니다.
  • 광고성 메시지만 발송 가능합니다.
  • 야간 시간(20시~익일 08시)에는 발송이 불가능합니다.
  • 카카오톡 채널을 친구로 추가한 사용자에게만 발송 가능합니다.
  • 수신자가 채널 알림을 차단한 경우에는 발송되지 않습니다.

친구톡 메시지 유형

친구톡은 다음과 같은 세 가지 유형으로 발송할 수 있습니다:

  1. 텍스트형 (FT)

    • 한/영 구분 없이 띄어쓰기 포함 1,000자 텍스트
    • 링크 버튼 최대 5개 (세로 배열)

  2. 이미지형 (FI)

    • 한/영 구분 없이 띄어쓰기 포함 400자 텍스트
    • 이미지 1장
    • 링크 버튼 최대 5개 (세로 배열)

  3. 와이드형 (FW)

    • 한/영 구분 없이 띄어쓰기 포함 76자 텍스트
    • 와이드 이미지 1장
    • 링크 버튼 1개

이미지 업로드하기

이미지를 포함한 친구톡을 발송하려면 먼저 이미지를 업로드해야 합니다.

1. 일반 친구톡 이미지 업로드하기

const imageFile = new File(
  [fs.readFileSync(path.resolve(__dirname, './resources/sendon_image.png'))],
  'sendon_image.png',
  {
    type: 'image/png',
  },
)
const uploadedImages = await sendon.kakao.uploadFriendTalkImage(imageFile)
// 성공 시 result.data.imageUrl에 업로드된 이미지 URL이 포함됩니다
File file = new File("./resources/sendon_image.png");

UploadAlimtalkImage uploadAlimtalkImage = sendon.kakao.uploadAlimtalkImage(file);

이미지 사양:

  • 권장 사이즈: 720px × 720px
  • 제한 사항: 가로 500px 미만이거나 가로:세로 비율이 2:1 미만 또는 3:4 초과 시 업로드 불가
  • 파일 형식: jpg, png
  • 최대 파일 크기: 500KB

2. 와이드형 친구톡 이미지 업로드하기

const imageFile = new File(
  [fs.readFileSync(path.resolve(__dirname, '../../../resources/sendon_wide_image.png'))],
  'sendon_wide_image.png',
  {
    type: 'image/png',
  },
)
const uploadedImages = await sendon.kakao.uploadFriendTalkWideImage(imageFile)
// 성공 시 result.data.imageUrl에 업로드된 이미지 URL이 포함됩니다
File file = new File("./resources/sendon_image.png");

UploadFriendtalkWideImage uploadFriendtalkWideImage = sendon.kakao.uploadFriendtalkWideImage(file);

와이드 이미지 사양:

  • 제한 사이즈: 800px × 600px
  • 파일 형식: jpg, png
  • 최대 파일 크기: 2MB

기본 친구톡 발송하기 (텍스트형)

가장 기본적인 텍스트형 친구톡 발송 방법입니다.

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FT', // FT: 텍스트형
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  message: '안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.',
  buttons: [
    {
      name: '자세히 보기',
      type: 'WL',
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
  ],
})
List<Button> buttons = new ArrayList<Button>();
Button button = new WlButton()
  .setName("자세히 보기")
  .setType(ButtonType.WL)
  .setUrlMobile("https://example.com/promotion")
  .setUrlPc("https://example.com/promotion");
buttons.add(button);

SendFriendtalk friendtalk = sendon.kakao.sendFriendtalk(new FriendtalkBuilder()
  .setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
  .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
  .setMessage("안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.")
  .setIsAd(true)
  .setButtons(button));

이미지형 친구톡 발송하기

이미지를 포함한 친구톡을 발송합니다. 이미지는 먼저 업로드 후 URL을 사용합니다.

const imageFile = new File(
  [fs.readFileSync(path.resolve(__dirname, '../../../resources/sendon_wide_image.png'))],
  'sendon_wide_image.png',
  {
    type: 'image/png',
  },
)
const uploadedImages = await sendon.kakao.uploadFriendTalkWideImage(imageFile)

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FI', // FI: 이미지형
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  message: '안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.',
  image: {
    url: uploadedImages.data.imageUrl,
    link: 'https://example.com/promotion', // 이미지 클릭 시 이동할 링크
  },
  buttons: [
    {
      name: '자세히 보기',
      type: 'WL',
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
  ],
})
File file = new File("./resources/sendon_image.png");
UploadAlimtalkImage uploadAlimtalkImage = sendon.kakao.uploadAlimtalkImage(file);
Image image = new Image(uploadAlimtalkImage.data.imageUrl, "https://example.com/promotion");

List<Button> buttons = new ArrayList<Button>();
Button button = new WlButton()
  .setName("자세히 보기")
  .setType(ButtonType.WL)
  .setUrlMobile("https://example.com/promotion")
  .setUrlPc("https://example.com/promotion");
buttons.add(button);

SendFriendtalk friendtalk = sendon.kakao.sendFriendtalk(new FriendtalkBuilder()
		.setMessageType(FriendtalkMessageType.FI)
    .setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
    .setMessage("안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.")
    .setButtons(buttons)
    .setImage(image));

와이드형 친구톡 발송하기

와이드 이미지를 포함한 친구톡을 발송합니다. 와이드 이미지용 별도 업로드 API를 사용합니다.

const imageFile = new File(
  [fs.readFileSync(path.resolve(__dirname, '../../../resources/sendon_image.png'))],
  'sendon_image.png',
  {
    type: 'image/png',
  },
)
const uploadedImages = await sendon.kakao.uploadFriendTalkImage(imageFile)

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FW', // FW: 와이드형
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  message: '안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다.',
  image: {
    url: uploadedImages.data.imageUrl,
    link: 'https://example.com/promotion', // 이미지 클릭 시 이동할 링크
  },
  buttons: [
    {
      name: '자세히 보기',
      type: 'WL',
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
  ],
})
File file = new File("./resources/sendon_image.png");
UploadAlimtalkImage uploadAlimtalkImage = sendon.kakao.uploadAlimtalkImage(file);
Image image = new Image(uploadAlimtalkImage.data.imageUrl, "https://example.com/promotion");

List<Button> buttons = new ArrayList<Button>();
Button button = new WlButton()
  .setName("자세히 보기")
  .setType(ButtonType.WL)
  .setUrlMobile("https://example.com/promotion")
  .setUrlPc("https://example.com/promotion");
buttons.add(button);

SendFriendtalk friendtalk = sendon.kakao.sendFriendtalk(new FriendtalkBuilder()
		.setMessageType(FriendtalkMessageType.FW) // 와이드형 이미지 
    .setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
    .setMessage("안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.")
    .setButtons(buttons)
    .setImage(image));

변수가 포함된 친구톡 발송하기

친구톡에서도 알림톡과 마찬가지로 변수를 활용한 개인화된 메시지 발송이 가능합니다.

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FT', // FT: 텍스트형
  to: [
    {
      phone: SENDON_EXAM_KAKAO_TO_PHONE,
      variables: {
        '#{고객명}': '홍길동',
        '#{할인율}': '15%',
        '#{유효기간}': '2023년 12월 31일',
      },
    },
    {
      phone: SENDON_EXAM_KAKAO_TO_PHONE,
      variables: {
        '#{고객명}': '김철수',
        '#{할인율}': '10%',
        '#{유효기간}': '2023년 12월 31일',
      },
    },
  ],
  message: `안녕하세요 #{고객명}님.
        센드온의 특별 프로모션을 안내해 드립니다.
        지금 구매 시 #{할인율} 할인 혜택을 받으실 수 있습니다.
        이 혜택은 #{유효기간}까지 유효합니다.`,
  buttons: [
    {
      name: '자세히 보기',
      type: 'WL',
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
  ],
})
JsonObject to1 = new JsonObject();
to1.addProperty("phone", SENDON_EXAM_KAKAO_TO_PHONE1);

JsonObject variables1 = new JsonObject();
variables1.addProperty("#{고객명}", "홍길동");
variables1.addProperty("#{할인율}", "15%");
variables1.addProperty("#{유효기간}", "2025년 12월 31일");
to1.add("variables", variables1);

JsonObject to2 = new JsonObject();
to2.addProperty("phone", SENDON_EXAM_KAKAO_TO_PHONE2);

JsonObject variables2 = new JsonObject();
variables2.addProperty("#{고객명}", "김철수");
variables2.addProperty("#{할인율}", "10%");
variables2.addProperty("#{유효기간}", "2027년 12월 31일");
to2.add("variables", variables2);

List<Button> buttons = new ArrayList<Button>();
Button button = new WlButton()
  .setName("자세히 보기")
  .setType(ButtonType.WL)
  .setUrlMobile("https://example.com/promotion")
  .setUrlPc("https://example.com/promotion");
buttons.add(button);

SendFriendtalk friendtalk = sendon.kakao.sendFriendtalk(new FriendtalkBuilder()
		.setMessageType(FriendtalkMessageType.FT)
    .setProfileId(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTo(Arrays.asList(to))
		.setMessage("안녕하세요 #{고객명}님. \n" +
    		"센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 #{할인율} 할인 혜택을 받으실 수 있습니다. \n" +
        "이 혜택은 #{유효기간}까지 유효합니다.")
    .setButtons(buttons));

다양한 버튼 유형을 포함한 친구톡 발송하기

친구톡은 웹링크, 앱링크, 봇키워드 등 다양한 유형의 버튼을 추가할 수 있습니다.

const result = await sendon.kakao.sendFriendTalk({
  sendProfileId: SENDON_EXAM_KAKAO_PROFILE_ID,
  messageType: 'FT', // FT: 텍스트형
  to: [SENDON_EXAM_KAKAO_TO_PHONE],
  message: '안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.',
  buttons: [
    {
      name: '웹사이트 방문',
      type: 'WL', // 웹 링크
      urlMobile: 'https://example.com/promotion',
      urlPc: 'https://example.com/promotion',
    },
    {
      name: '앱에서 보기',
      type: 'AL', // 앱 링크
      urlMobile: 'https://example.com/promotion',
      schemeIos: 'exampleapp://promotion',
      schemeAndroid: 'exampleapp://promotion',
    },
    {
      name: '봇 명령어',
      type: 'BK', // 봇키워드 - 버튼 텍스트가 전송됨
    },
    {
      name: '메시지 전달',
      type: 'MD', // 메시지전달 - 버튼 텍스트와 메시지 본문이 전송됨
    },
    {
      name: '채널 추가하기',
      type: 'AC', // 채널 추가
    },
  ],
})
List<Button> buttons = new ArrayList<Button>();
Button button1 = new WlButton()
  .setName("자세히 보기")
  .setType(ButtonType.WL)
  .setUrlMobile("https://example.com/promotion")
  .setUrlPc("https://example.com/promotion");
buttons.add(button1);

Button button2 = new AlButton()
  .setName("앱에서 보기")
  .setType(ButtonType.AL)
  .setUrlMobile("https://example.com'/promotion")
  .setSchemeIos("https://example.com/promotion")
  .setSchemeAndroid("https://example.com/promotion");
buttons.add(button2);

Button button3 = new Button()
  .setName("봇 명령어")
  .setType(ButtonType.BK);
buttons.add(button3);

Button button4 = new Button()
  .setName("메시지 전달")
  .setType(ButtonType.MD);
buttons.add(button4);

Button button5 = new Button()
  .setName("채널 추가")
  .setType(ButtonType.AC);
buttons.add(button5);

SendFriendtalk friendtalk2 = sendon.kakao.sendFriendtalk(new FriendtalkBuilder()
		.setMessageType(FriendtalkMessageType.FT)
    .setProfile(SENDON_EXAM_KAKAO_PROFILE_ID)
    .setTo(Arrays.asList(SENDON_EXAM_KAKAO_TO_PHONE))
    .setMessage("안녕하세요. 센드온의 특별 프로모션을 안내해 드립니다. 지금 구매 시 15% 할인 혜택을 받으실 수 있습니다.")
    .setButton(buttons));

파라미터 상세 설명

필수 파라미터

파라미터타입설명
sendProfileIdstring카카오 비즈니스 채널의 발신 프로필 ID
messageTypestring메시지 유형 ('FT': 텍스트형, 'FI': 이미지형, 'FW': 와이드형)
tostring[] 또는 object[]수신자 정보 (전화번호 또는 전화번호와 변수값)
messagestring발송할 메시지 내용

선택 파라미터

파라미터타입설명
buttonsobject[]버튼 정보 배열
buttons[].namestring버튼 이름
buttons[].typestring버튼 유형
imageobject이미지 정보 (이미지형, 와이드형에서 필수)
image.urlstring업로드된 이미지 URL
image.linkstring이미지 클릭 시 이동할 링크 URL
reservation.dateTimestring예약 발송 시간 (ISO 8601 날짜 형식)

버튼 유형별 필수 파라미터

버튼 유형설명필수 파라미터
WL웹 링크urlMobile, urlPc
AL앱 링크linkMobile, schemeAndroid, schemeIos 중 2개 이상
BK봇키워드없음 (버튼 텍스트가 자동 전송됨)
MD메시지전달없음 (버튼 텍스트와 메시지 본문이 전송됨)
DS배송조회알림톡 전용
AC채널 추가알림톡 전용 (카카오톡 채널 추가 기능)

응답 형식

성공적으로 요청이 처리되면 다음과 같은 응답을 받습니다:

{
  "code": 200,
  "message": "성공",
  "data": {
    "groupId": "84db8cbb-db70-4e68-8ee7-c37704787e0d"
  }
}

이 groupId는 발송 요청의 고유 식별자로, 발송 결과 조회 시 활용할 수 있습니다.

주의사항

  1. 친구톡은 채널 친구로 추가한 사용자에게만 발송 가능합니다
  2. 야간 시간(20시~익일 08시)에는 발송이 제한됩니다
  3. 광고성 메시지로 분류되며, 관련 법규를 준수해야 합니다
  4. 이미지 첨부 시 카카오에서 지정한 이미지 규격을 준수해야 합니다
    • 일반 이미지: 권장 720px x 720px, 최소 500px x 500px, 최대 500KB
    • 와이드 이미지: 800px x 600px, 최대 2MB
  5. 메시지 유형별 글자수 제한을 준수해야 합니다
    • 텍스트형(FT): 최대 1,000자
    • 이미지형(FI): 최대 400자
    • 와이드형(FW): 최대 76자
  6. 전화번호는 하이픈(-) 없이 제공해야 합니다 (예: 01012345678)

관련 링크

Updated 4 days ago