이 튜토리얼에서는 사용자가 같은 서비스의 친구를 직접 선택해 메시지를 보내는 기능을 단계별로 설명합니다.

카카오에서 제공하는 메시지 발송 기능은 발송 주체와 목적에 따라 다릅니다. 메시지 발송 기능 안내를 참고해 카카오톡 메시지 API가 서비스의 목적에 맞는지 확인합니다.

카카오톡 메시지 API는 사용자가 같은 서비스에 가입한 카카오톡 친구에게 메시지를 보내는 기능입니다. 사용자가 친구를 선택해 보내는 흐름이며, 카카오톡 메시지 API로 서비스가 사용자에게 메시지를 자동 발송할 수 없습니다. 서비스가 주문, 배송 등의 정보를 사용자에게 일방적으로 안내하려는 경우에는 알림톡을 사용합니다.

친구에게 메시지를 보내려면 나에게 사용자 정의 메시지 발송과 달리 수신자 정보가 필요합니다.

1. 카카오톡 친구 목록 조회 API 또는 친구 피커로 수신자의 uuid를 확인합니다.
2. 확인한 uuid와 사용자 정의 템플릿의 템플릿 ID를 사용자 정의 템플릿으로 메시지 발송 API에 전달합니다.

이 튜토리얼에서는 REST API 테스트 도구로 액세스 토큰을 발급하고, 친구 목록과 uuid를 확인합니다. 카카오 로그인 버튼·친구 목록·메시지 발송 UI는 샘플 코드로 테스트와 카카오 로그인 구현을 참고합니다.

친구에게 메시지를 보내려면 나에게 사용자 정의 메시지 발송에서 완료한 카카오 로그인, talk_message 동의항목, 웹 도메인, 메시지 템플릿 설정에 더해 아래 설정을 추가합니다. 같은 앱을 사용합니다.

나에게 사용자 정의 메시지 발송에서 사용한 앱을 이 튜토리얼에서도 사용합니다. 사용할 앱을 새로 만들어야 한다면 카카오디벨로퍼스 앱 만들기를 참고합니다.

친구에게 메시지를 보내려면 두 가지 동의항목 설정이 필요합니다.

나에게 사용자 정의 메시지 발송 > 동의항목 설정하기를 참고해 [카카오톡 메시지 전송 / (talk_message)] 동의항목을 설정합니다.

이 튜토리얼에서는 이미 나에게 사용자 정의 메시지 발송을 완료했다는 가정하에, 친구 목록 조회를 위한 설정부터 안내합니다.

카카오톡 친구 목록을 조회하려면 [카카오 서비스 내 친구목록 / (friends)] 동의항목을 설정해야 합니다.

친구 목록 동의항목 설정 화면

1. 앱 관리 페이지의 [카카오 로그인] > [동의항목]을 선택합니다.
2. [개인정보] > [카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)] 항목에서 [설정]을 선택합니다.
3. 동의 단계를 [이용 중 동의]로 선택하고 [동의 목적]을 입력합니다.
4. [저장]을 선택합니다.

친구에게 메시지를 보내는 기능을 심사 승인 전에 테스트하려면 발신자와 수신자를 카카오디벨로퍼스 앱 멤버로 등록해야 합니다.

1. 앱 관리 페이지에서 [앱] > [멤버]를 선택합니다.
2. 앱 오너 계정으로 [멤버 추가]를 선택합니다.
3. 발신자와 수신자로 사용할 카카오계정을 모두 추가하고, 역할은 [에디터] 또는 [뷰어]로 지정합니다.
   • 카카오계정은 로그인 시 사용되는 이메일로만 초대 가능

친구에게 메시지를 보내려면 메시지 템플릿의 [사용 목적]이 [카카오톡 메시지 API]여야 합니다.

1. [도구] > [메시지 템플릿]에서 나에게 사용자 정의 메시지 발송에서 만든 템플릿을 엽니다.
2. 공통 설정의 [사용 목적]이 [카카오톡 메시지 API]인지 확인합니다. [카카오톡 공유 API]로 설정되어 있다면 [카카오톡 메시지 API]로 변경합니다.
3. [저장]을 선택합니다.

REST API 테스트 도구로 카카오톡 친구 목록 조회 API를 호출해 메시지를 받을 친구의 uuid를 확인합니다.

추가 기능 신청 심사 승인 전에는 아래 조건을 만족한 앱 멤버만 응답에 포함됩니다. 혼자 테스트하기 어렵다면 카카오계정 2개(둘 다 멤버, 친구, 앱 연결, 동의)로 진행합니다.

친구 목록 API로 카카오톡 친구 정보를 얻으려면 아래 조건을 만족해야 합니다.

• 발신자와 수신자는 카카오톡 친구여야 합니다. 친구가 아니라면 카카오톡 친구로 추가합니다.
• 발신자와 수신자 모두 앱에 연결된 상태여야 하며, [카카오 서비스 내 친구목록]과 [카카오톡 메시지 전송] 동의항목에 동의해야 합니다.
  • 수신자를 앱과 연결하려면 2-1. 앱과 앱 멤버 연결하기를 수행합니다.
  • 발신자는 [2-2. 앱 멤버 조회하기]과정에서 앱과 연결합니다.

메시지를 받을 앱 멤버(수신자)는 아래 과정을 거쳐 앱과 연결합니다.

1. REST API 테스트 도구의 사용자 정보 조회 API를 선택합니다.
2. [인증 앱]에서 이 튜토리얼에 사용되는 앱을 선택합니다.
3. [액세스 토큰]의 [토큰 발급]을 선택합니다.
4. 사용자 정보 조회 범위에서 friends, talk_message를 선택한 후 [확인]을 선택합니다.
5. 카카오계정으로 로그인하고, 카카오 로그인 동의 화면에서 [카카오 서비스 내 친구목록], [카카오톡 메시지 전송] 항목에 동의합니다. 이렇게 하면 수신자 카카오계정이 앱과 연결됩니다.

1. REST API 테스트 도구의 카카오톡 친구 목록 조회를 선택합니다.
2. [인증 앱]에서 템플릿을 만든 앱을 선택합니다.
3. [액세스 토큰]의 [토큰 발급]을 선택합니다.
4. 사용자 정보 조회 범위에서 friends, talk_message를 선택한 후 [확인]을 선택합니다.
   • 이 항목이 비활성화되어 있다면 1-2. 동의항목 설정하기에서 안내한 대로 동의항목을 설정해야 합니다.
5. 발신자 카카오계정으로 로그인하고 동의 화면이 나타나면 [카카오 서비스 내 친구목록], [카카오톡 메시지 전송] 항목을 선택해 동의합니다.
6. [전송]을 선택하면 입력한 값으로 API를 호출합니다.
7. 응답 본문의 elements 배열에서 메시지를 받을 친구를 찾고 uuid 값을 복사합니다.

{
  "elements": [
    {
      "profile_nickname": "테스트 친구",
      "uuid": "abcdefg0001"
    }
  ],
  "total_count": 1
}

{
  "msg": "There are no team members except the caller for App(id=215508). In order to call unreviewed api, invite testers as a team member, first.",
  "code": -5
}

{
  "elements": [],
  "total_count": 0,
  "after_url": null,
  "favorite_count": 0
}

친구 목록에는 친구 정보 제공 조건을 모두 만족하는 사용자만 포함됩니다. 앱 멤버를 추가했는데 친구가 보이지 않는다면 Q. 친구에게 카카오톡 메시지를 보내려고 하는데, 친구가 보이지 않아요를 참고합니다.

REST API 테스트 도구로 사용자 정의 템플릿으로 메시지 발송 API를 호출해, 나에게 사용자 정의 메시지 발송에서 저장한 템플릿이 친구에게 정상적으로 발송되는지 확인합니다.

1. [인증 앱]에서 템플릿을 만든 앱을 선택합니다.
2. receiver_uuids에 복사한 친구의 uuid를 JSON 배열로 입력합니다.
   • 예: ["abcdefg0001"]
3. 메시지 템플릿 생성하기에서 확인한 템플릿 ID를 template_id에 입력합니다.
   • 예: 5595
4. 메시지 구성 요소 설정하기에서 설정한 사용자 인자 값을 template_args에 JSON 형식으로 입력합니다.
   • 예: {"NAME":"춘식이"}
5. [전송]을 선택하면 입력한 값으로 API를 호출합니다.
6. 정상적으로 발송되었는지 확인합니다.
   • 응답 본문의 successful_receiver_uuids에 입력한 uuid가 포함됐는지 확인(참고: 사용자 정의 템플릿으로 메시지 발송 API 응답 예시)
   • 수신자의 카카오톡에서 구성한 메시지가 발송되었는지 확인
   • 메시지 헤더에 사용자 인자값이 제대로 표시되었는지 확인

한 번에 최대 5명의 친구에게 메시지를 보낼 수 있습니다. 심사 승인 전에는 앱 기준 일 30건까지 발송할 수 있습니다. 자세한 제한은 쿼터를 참고합니다.

테스트가 끝나면 서비스 코드에서 아래 순서로 메시지를 발송 시나리오를 개발합니다.

1. 서비스의 웹 또는 앱 환경에서 카카오 로그인을 구현합니다. 카카오 로그인으로 friends, talk_message 동의항목에 동의한 사용자의 액세스 토큰을 발급받습니다. 인가 코드 요청 시 scope에 friends, talk_message를 포함합니다.
   • 참고: 인가 코드 요청, 튜토리얼: 카카오 로그인을 구현, 튜토리얼: 샘플 코드로 테스트
2. 카카오톡 친구 목록 조회 API 또는 친구 피커로 사용자가 수신자를 직접 선택할 수 있는 화면을 개발합니다.
   • 참고: 튜토리얼: 샘플 코드로 테스트
3. 메시지 템플릿 도구에서 만든 템플릿 ID를 코드에 적용합니다.
4. 사용자별로 바뀌는 값이 있다면 template_args에 사용자 인자 값을 전달합니다.
5. 선택한 친구의 uuid와 함께 사용자 정의 템플릿으로 메시지 발송 API를 호출합니다.

curl -v -X POST "https://kapi.kakao.com/v1/api/talk/friends/message/send" \
  -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "template_id=5595" \
  -d 'template_args={"NAME":"춘식이"}' \
  --data-urlencode 'receiver_uuids=["abcdefg0001"]'

앱 멤버를 대상으로 테스트를 완료한 뒤 실제 서비스 사용자에게 기능을 제공하려면 카카오톡 친구 목록 / 메시지 추가 기능을 신청해야 합니다.

1. 앱을 비즈 앱으로 전환합니다.
2. [앱] > [추가 기능 신청]에서 신청 자격 확인을 완료합니다.
3. 필요한 경우 비즈니스 정보 심사를 완료합니다.
4. [추가 기능]의 카카오톡 친구 목록 / 메시지 항목에서 [신청]을 선택합니다.
5. 신청 조건에서 카카오톡 친구 목록 / 메시지를 선택합니다.
6. 서비스 URL, 실제 메시지 발송 화면, 신청 사유와 활용 시나리오를 입력합니다.
7. 개인정보를 마스킹한 화면 자료를 첨부하고 신청합니다.

카카오톡 친구 목록과 메시지 추가 기능 신청 화면

신청 자료에는 사용자가 카카오 로그인한 뒤 친구를 직접 선택하고 메시지를 보내는 전체 흐름이 드러나야 합니다. 필요한 신청 정보와 심사 기준은 카카오톡 소셜 > 사용 방법을 참고합니다.

자세한 오류 원인은 REST API 에러 코드, 카카오톡 메시지 에러 코드, 카카오톡 메시지 FAQ, 메시지 템플릿 FAQ를 참고합니다.

• 서비스 사용자간 카카오톡 메시지 발송
• JavaScript SDK로 카카오톡 공유 메시지 발송