카카오톡 메시지

REST API

이 문서는 카카오 또는 공동체 서비스용 카카오톡 메시지 REST API 사용법을 안내합니다.

나에게 기본 템플릿으로 메시지 발송

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡으로, 기본 템플릿을 적용한 메시지를 사용자 자신에게 발송합니다. 이 기능으로는 다른 사용자에게 메시지를 보낼 수 없고, 로그인한 사용자 자신에게만 메시지를 보낼 수 있습니다.

기본 템플릿 구성 방법은 기본 템플릿을 참고합니다.

자세한 안내와 예제는 나에게 기본 템플릿으로 메시지 발송을 참고합니다.

나에게 사용자 정의 템플릿으로 메시지 발송

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡으로, 사용자 정의 템플릿을 적용한 메시지를 사용자 자신에게 발송합니다. 이 기능으로는 다른 사용자에게 메시지를 보낼 수 없고, 로그인한 사용자 자신에게만 메시지를 보낼 수 있습니다.

자세한 안내와 예제는 나에게 사용자 정의 템플릿으로 메시지 발송을 참고합니다.

나에게 스크랩 메시지 발송

현재 로그인한 사용자의 카카오계정에 연결된 카카오톡으로, 스크랩 메시지를 사용자 자신에게 발송합니다. 이 기능으로는 다른 사용자에게 메시지를 보낼 수 없고, 로그인한 사용자 자신에게만 메시지를 보낼 수 있습니다.

자세한 안내와 예제는 나에게 스크랩 메시지 발송을 참고합니다.

기본 템플릿으로 메시지 발송

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/default/send` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/default/send` 외부 `https://kapi.kakao.com/v2/api/talk/message/default/send`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 제품 링크 관리 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱	필요: 연결	필요: 카카오톡 메시지 전송

사용자 카카오계정에 연결된 카카오톡으로, 기본 템플릿을 적용한 메시지를 다른 사용자 또는 채팅방에 발송합니다. 이 API는 권한을 받기 전 멤버 대상으로 테스트 호출이 가능합니다.

헤더에 액세스 토큰을 담아 POST로 요청하고, 성공 시 result_code 0을 받습니다. 메시지를 보낼 대상은 회원번호(user_id), 고유 번호(uuid), 채팅방 ID(chat_id) 중에서 한 가지 타입의 ID로 지정 가능합니다. ID는 카카오톡 친구 목록 조회, 인하우스 앱: 카카오톡 친구 목록 조회 또는 인하우스 앱: 채팅방 목록 조회로 받습니다. 기본 템플릿을 참고해 template_object 파라미터에 메시지 템플릿 JSON 객체를 전달합니다.

요청 실패 시 에러 코드로 원인을 확인합니다.

이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.

샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
template_object	`JSON`	메시지 구성 요소를 담은 객체(Object) 피드, 리스트, 위치, 커머스, 텍스트, 캘린더 중 하나	O

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
template_object	`JSON`	메시지 구성 요소를 담은 객체(Object) 피드, 리스트, 위치, 커머스, 텍스트, 캘린더 중 하나	O

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

요청 대상 사용자와 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, sender_id, sender_id_type
- 서비스 앱 ID: target_app_id, sender_id, sender_id_type
- 발신자 액세스 토큰: sender_access_token

이름	타입	설명	필수
target_app_key	`String`	메시지를 보내려는 서비스 앱 키	O(Optional)
target_app_id	`String`	메시지를 보내려는 앱의 ID	O(Optional)
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O(Optional)
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	O(Optional)
sender_access_token	`String`	발신자의 액세스 토큰 값	O(Optional)
template_object	`JSON`	메시지 구성 요소를 담은 객체(Object) 피드, 리스트, 위치, 커머스, 텍스트, 캘린더 중 하나	O

응답

본문

이름	타입	설명	필수
result_code	`Integer`	전송 성공 시 0	O
successful_receiver_ids	`String[]`	메시지 전송에 성공한 사용자 ID 배열	X
failure_info	`FailureInfo[]`	실패 정보 메시지 수신자가 1명일 때 실패 시 `failure_info` 없이 에러 코드 전달 메시지 수신자가 2명 이상일 때 실패 시 HTTP 상태 코드(Status code) 200과 함께 실패한 사용자 정보를 `failure_info`로 전달	X

FailureInfo

이름	타입	설명	필수
code	`Integer`	에러 코드	O
msg	`String`	에러 메시지	O
receiver_ids	`String[]`	해당 에러 코드로 실패한 사용자 ID 배열	O

예제

요청: 액세스 토큰 방식

한 명의 다른 사용자에게 피드 메시지 전송
파라미터
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 메시지 템플릿(template_object)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/default/send" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "receiver_id_type=uuid" \
  -d "receiver_id=abcdef" \
  -d 'template_object={
        "object_type": "feed",
        "content": {
            "title": "피드 메시지",
            "description": "피드 메시지 기본 템플릿",
            "image_url": "http://api1-kage.kakao.com/dn/cerDB5/ZSb2iRugKx/M4nuZxX823tnK1Mk5yVcv0/kakaolink40_original.png",
            "link": {
                "web_url": "http://dev.kakao.com",
                "mobile_web_url": "http://dev.kakao.com"
            }
        },
        "social": {
            "like_count": 100,
            "comment_count": 200
        },
        "button_title": "바로 확인"
    }'

요청: 서비스 앱 어드민 키 방식

여러 명의 다른 사용자에게 리스트 메시지 전송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 회원번호(user_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 메시지 템플릿(template_object)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/default/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id_type=user_id" \
  -d "sender_id=106073" \
  -d "receiver_id_type=uuid" \
  -d 'receiver_id=["abcdefg0001","abcdefg0002"]' \
  -d 'template_object={
        "object_type": "list",
        "header_title": "카카오디벨로퍼스",
        "header_link": {
            "web_url": "https://dev.kakao.com",
            "mobile_web_url": "https://dev.kakao.com"
        },
        "contents": [
            {
            "title": "API 소개",
            "image_url": "http://api1-kage.kakao.com/dn/cerDB5/ZSb2iRugKx/M4nuZxX823tnK1Mk5yVcv0/kakaolink40_original.png",
            "link": {
                "web_url": "https://dev.kakao.com/features/platform",
                "mobile_web_url": "https://dev.kakao.com/features/platform"
            }
            },
            {
            "title": "개발자 가이드",
            "image_url": "http://api1-kage.kakao.com/dn/cerDB5/ZSb2iRugKx/M4nuZxX823tnK1Mk5yVcv0/kakaolink40_original.png",
            "link": {
                "web_url": "https://dev.kakao.com/docs",
                "mobile_web_url": "https://dev.kakao.com/docs"
            }
            },
            {
            "title": "개발자 포럼",
            "image_url": "http://api1-kage.kakao.com/dn/cerDB5/ZSb2iRugKx/M4nuZxX823tnK1Mk5yVcv0/kakaolink40_original.png",
            "link": {
                "web_url": "https://devtalk.kakao.com",
                "mobile_web_url": "https://devtalk.kakao.com"
            }
            }
        ],
        "button_title": "웹에서 보기"
    }'

요청: 위임 방식

한 명의 다른 사용자에게 위치 메시지 전송
파라미터
- 서비스 앱 키(target_app_key)
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 메시지 템플릿(template_object)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/default/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "sender_id_type=talk_id" \
  -d "sender_id=700003028" \
  -d "receiver_id_type=chat_id" \
  -d "receiver_id=89613112512119604" \
  -d 'template_object={
        "object_type": "location",
        "content": {
            "title": "위치 메시지",
            "description": "위치 메시지 기본 템플릿",
            "image_url": "http://api1-kage.kakao.com/dn/cerDB5/ZSb2iRugKx/M4nuZxX823tnK1Mk5yVcv0/kakaolink40_original.png",
            "link": {
                "web_url": "http://dev.kakao.com",
                "mobile_web_url": "http://dev.kakao.com"
            }
        },
        "social": {
            "like_count": 100,
            "comment_count": 200
        },
        "button_title": "바로 확인",
        "address": "경기 성남시 분당구 판교역로 235 에이치스퀘어 N동 7층",
        "address_title": "카카오"
    }'

응답: 1명의 수신자

{
  "result_code": 0
}

응답: 여러 명에게 메시지 전송, 일부 실패

// HTTP/1.1 200 OK
{
  "successful_receiver_ids": ["abcdefg0001", "abcdefg0002"],
  "failure_info": [
    {
      "code": -532,
      "msg": "daily message limit per sender has been exceeded.",
      "receiver_uuids": ["abcdefg0003"]
    }
  ]
}

사용자 정의 템플릿으로 메시지 발송

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/send` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/send` 외부 `https://kapi.kakao.com/v2/api/talk/message/send`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 제품 링크 관리 카카오 로그인 활성화 동의항목 메시지 템플릿 유료 API: 공동체 앱	필요: 연결	필요: 카카오톡 메시지 전송

사용자 카카오계정에 연결된 카카오톡으로, 사용자 정의 템플릿을 적용한 메시지를 다른 사용자 또는 채팅방에 발송합니다. 이 API는 권한을 받기 전 멤버 대상으로 테스트 호출이 가능합니다.

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 result_code 0을 받습니다. 메시지를 보낼 대상은 회원번호(user_id), 고유 번호(uuid), 채팅방 ID(chat_id) 중에서 한 가지 타입의 ID로 지정 가능합니다. ID는 카카오톡 친구 목록 조회, 인하우스 앱: 카카오톡 친구 목록 조회 또는 인하우스 앱: 채팅방 목록 조회로 받습니다. template_id 파라미터에는 사용자 정의 템플릿의 ID를, template_args 파라미터에는 해당 사용자 정의 템플릿에 정의해 둔 User Argument에 대입할 키와 값을 포함해야 합니다.

요청 실패 시 에러 코드로 원인을 확인합니다.

이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.

샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID (참고: 사용자 정의 템플릿)	O
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID (참고: 사용자 정의 템플릿)	O
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

요청 대상 사용자와 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, sender_id, sender_id_type
- 서비스 앱 ID: target_app_id, sender_id, sender_id_type
- 발신자 액세스 토큰: sender_access_token

이름	타입	설명	필수
target_app_key	`String`	메시지를 보내려는 서비스 앱 키	O(Optional)
target_app_id	`String`	메시지를 보내려는 앱의 ID	O(Optional)
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O(Optional)
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	O(Optional)
sender_access_token	`String`	발신자의 액세스 토큰 값	O(Optional)
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID (참고: 사용자 정의 템플릿)	O
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

응답

본문

이름	타입	설명	필수
result_code	`Integer`	전송 성공 시 0	O
successful_receiver_ids	`String[]`	메시지 전송에 성공한 사용자 ID 배열	X
failure_info	`FailureInfo[]`	실패 정보 메시지 수신자가 1명일 때 실패 시 `failure_info` 없이 에러 코드 전달 메시지 수신자가 2명 이상일 때 실패 시 HTTP 상태 코드(Status code) 200과 함께 실패한 사용자 정보를 `failure_info`로 전달	X

예제

요청: 액세스 토큰 방식

한 명의 사용자에게 사용자 정의 메시지 전송
파라미터
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 메시지 템플릿 ID(template_id)
- 사용자 정의 Argument에 대입할 키와 값(template_args)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/send" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "receiver_id=abcdef" \
  -d "receiver_id_type=uuid" \
  -d "template_id=123456"
-d 'template_args={"TITLE":"타이틀입니다."}'

요청: 서비스 앱 어드민 키 방식

한 명의 사용자에게 사용자 정의 메시지 전송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 메시지 템플릿 ID(template_id)
- 사용자 정의 Argument에 대입할 키와 값(template_args)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=88604424245226292" \
  -d "receiver_id_type=chat_id" \
  -d "template_id=123456"
-d 'template_args={"TITLE":"타이틀입니다."}'

요청: 위임 방식

여러 명의 사용자에게 사용자 정의 메시지 전송
파라미터
- 발신자 액세스 토큰(sender_access_token)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 메시지 템플릿 ID(template_id)
- 사용자 정의 Argument에 대입할 키와 값(template_args)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "sender_access_token=${ACCESS_TOKEN}" \
  -d 'receiver_id=["abcdefg0001","abcdefg0002"]' \
  -d "receiver_id_type=uuid" \
  -d "template_id=123456"
-d 'template_args={"TITLE":"타이틀입니다."}'

응답: 1명의 수신자

{
  "result_code": 0
}

응답: 여러 명에게 메시지 전송, 일부 실패

// HTTP/1.1 200 OK
{
  "successful_receiver_ids": ["abcdefg0001", "abcdefg0002"],
  "failure_info": [
    {
      "code": -532,
      "msg": "daily message limit per sender has been exceeded.",
      "receiver_uuids": ["abcdefg0003"]
    }
  ]
}

스크랩 메시지 발송

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/scrap/send` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/scrap/send` 외부 `https://kapi.kakao.com/v2/api/talk/message/scrap/send`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 제품 링크 관리 카카오 로그인 활성화 동의항목 유료 API: 공동체 앱	필요: 연결	필요: 카카오톡 메시지 전송

사용자 카카오계정에 연결된 카카오톡으로, 웹 페이지 스크랩 정보가 담긴 메시지를 다른 사용자 또는 채팅방에 발송합니다. 이 API는 권한을 받기 전 멤버 대상으로 테스트 호출이 가능합니다.

웹 페이지 URL을 스크랩하여 그 정보를 바탕으로 스크랩 메시지를 구성해 발송하는 API입니다. 기본 템플릿의 구성 요소는 스크랩 메시지 구성에 사용되는 기본 템플릿의 구성을 참고합니다.

서비스에서 정의한 메시지 템플릿을 기반으로 메시지를 보내고 싶으면 [도구] > [메시지 템플릿]에서 구성한 템플릿의 ID를 templateId 파라미터로 전달해야 합니다. 메시지에 변동되는 정보를 포함하려면 사용자 인자를 사용합니다. 이 경우, 반드시 templateArgs 파라미터로 키와 값을 전달해야 합니다. 자세한 내용은 아래 문서를 참고합니다.

실패 시 에러 코드로 원인을 확인합니다.

이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.

샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

스크랩 메시지 구성에 사용되는 기본 템플릿의 구성

{
  "P": {
    "TP": "Feed",
    "ME": "${ME}",
    "DID": "${REGI_DID}",
    "L": {
      "LCA": "${A_E}",
      "LCI": "${I_E}",
      "LMO": "${REGI_WEB_DOMAIN}"
    },
    "LA": "${A_M}",
    "LI": "${I_M}",
    "VA": "6.0.0",
    "VI": "5.9.8",
    "VW": "2.5.1",
    "VM": "2.2.0",
    "FW": true,
    "RF": "${REGI_REF}"
  },
  "C": {
    "THL": [
      {
        "TH": {
          "THU": "${SCRAP_IMAGE}",
          "W": "${SCRAP_IMAGE_WIDTH}",
          "H": "${SCRAP_IMAGE_HEIGHT}",
          "PT": "${SCRAP_IMAGE_DURATION}"
        },
        "L": {
          "LMO": "${SCRAP_REQUESTED_URL}",
          "LPC": "${SCRAP_REQUESTED_URL}"
        }
      }
    ],
    "TI": {
      "TD": {
        "T": "${SCRAP_TITLE}",
        "D": "${SCRAP_DESCRIPTION}"
      },
      "L": {
        "LMO": "${SCRAP_REQUESTED_URL}",
        "LPC": "${SCRAP_REQUESTED_URL}"
      }
    },
    "BUL": [
      {
        "BU": {
          "T": "${SCRAP_HOST}에서 확인"
        },
        "L": {
          "LPC": "${SCRAP_REQUESTED_URL}",
          "LMO": "${SCRAP_REQUESTED_URL}"
        }
      }
    ]
  }
}

위 기본 템플릿의 구성 요소는 아래와 같이 정의되어 있습니다.

${SCRAP_IMAGE}/${SCRAP_IMAGE_WIDTH}/${SCRAP_IMAGE_HEIGHT} : KAGE에 저장된 og:image의 덤프(Dump) 이미지
${SCRAP_IMAGE_DURATION} : og:duration, meta:duration 순으로 우선순위 가짐
${SCRAP_TITLE} : og:title, meta.title, tag.title 순으로 우선순위 가짐
${SCRAP_DESCRIPTION} : og:description, meta.description 순으로 우선순위 가짐
${SCRAP_HOST} : 요청 URL의 호스트(HOST) 정보
${SCRAP_REQUESTED_URL} : 요청 URL

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
request_url	`String`	스크랩할 웹페이지 URL	O
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID 서비스에서 정의한 템플릿을 기반으로 스크랩 메시지를 보낼 경우 사용 (참고: 사용자 정의 템플릿)	X
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
request_url	`String`	스크랩할 웹페이지 URL	O
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID 서비스에서 정의한 템플릿을 기반으로 스크랩 메시지를 보낼 경우 사용 (참고: 사용자 정의 템플릿)	X
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

요청 대상 사용자와 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, sender_id, sender_id_type
- 서비스 앱 ID: target_app_id, sender_id, sender_id_type
- 발신자 액세스 토큰: sender_access_token

이름	타입	설명	필수
target_app_key	`String`	메시지를 보내려는 서비스 앱 키	O(Optional)
target_app_id	`String`	메시지를 보내려는 앱의 ID	O(Optional)
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O(Optional)
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	O(Optional)
sender_access_token	`String`	발신자의 액세스 토큰 값	O(Optional)
request_url	`String`	스크랩할 웹페이지 URL	O
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID 서비스에서 정의한 템플릿을 기반으로 스크랩 메시지를 보낼 경우 사용 (참고: 사용자 정의 템플릿)	X
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

응답

본문

이름	타입	설명	필수
result_code	`Integer`	전송 성공 시 0	O
successful_receiver_ids	`String[]`	메시지 전송에 성공한 사용자 ID 배열	X
failure_info	`FailureInfo[]`	실패 정보 메시지 수신자가 1명일 때 실패 시 `failure_info` 없이 에러 코드 전달 메시지 수신자가 2명 이상일 때 실패 시 HTTP 상태 코드(Status code) 200과 함께 실패한 사용자 정보를 `failure_info`로 전달	X

예제

요청: 액세스 토큰 방식, 기본 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "receiver_id=abcdef" \
  -d "receiver_id_type=uuid" \
  -d "request_url=http://www.kakao.com"

요청: 서비스 앱 어드민 키 방식, 기본 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 회원번호(user_id)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=1260155078" \
  -d "receiver_id_type=user_id" \
  -d "request_url=http://www.kakao.com"

요청: 위임 방식, 기본 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 서비스 앱 ID(target_app_id)
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_id=362532" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=171976292125929" \
  -d "receiver_id_type=chat_id" \
  -d "request_url=http://www.kakao.com"

요청: 액세스 토큰 방식, 사용자 정의 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 고유 ID(uuid)
- 메시지 템플릿 ID(template_id)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "receiver_id=abcdef" \
  -d "receiver_id_type=uuid" \
  -d "template_id=123456" \
  -d "request_url=http://www.kakao.com"

요청: 서비스 앱 어드민 키 방식, 사용자 정의 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 회원번호(user_id)
- 메시지 템플릿 ID(template_id)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=1260155078" \
  -d "receiver_id_type=user_id" \
  -d "template_id=123456" \
  -d "request_url=http://www.kakao.com"

요청: 위임 방식, 사용자 정의 템플릿 사용

한 명의 다른 사용자에게 스크랩 메시지 전송
파라미터
- 서비스 앱 ID(target_app_id)
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 메시지 템플릿 ID(template_id)
- 스크랩할 웹페이지 URL(request_url)

curl -v -X POST "https://kapi.kakao.com/v2/api/talk/message/scrap/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_id=362532" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=171976292125929" \
  -d "receiver_id_type=chat_id" \
  -d "template_id=123456" \
  -d "request_url=http://www.kakao.com"

응답: 1명의 수신자

{
  "result_code": 0
}

응답: 여러 명에게 메시지 전송, 일부 실패

// HTTP/1.1 200 OK
{
  "successful_receiver_ids": ["abcdefg0001", "abcdefg0002"],
  "failure_info": [
    {
      "code": -532,
      "msg": "daily message limit per sender has been exceeded.",
      "receiver_uuids": ["abcdefg0003"]
    }
  ]
}

플레인 메시지 발송

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v3/internal/talk/message/send` 공동체 `https://kapi.kakao.com/v3/internal/talk/message/send`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키 제품 링크 관리 카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 메시지 전송

카카오톡으로 사용자 자신, 또는 다른 사용자나 채팅방에 플레인 메시지를 발송합니다.

서비스 앱 정보를 포함하는 형태의 레버리지 말풍선과 달리, 플레인 메시지는 사용자가 직접 카카오톡에서 입력해 보낸 메시지와 외관상 차이가 없습니다. 따라서 사용자에게 혼란을 주지 않도록 엄격한 심사를 거쳐 특정한 경우에만 권한(MESSAGE_TYPE_TEXT)을 받을 수 있으며, 사용자에게 혼란을 주지 않도록 말풍선 뱃지와 같은 추가적인 조치가 필요할 수 있습니다.

서비스 앱 어드민 키 방식 또는 위임 방식으로 요청할 경우, 발신자 ID는 아래 중 한 가지 타입을 선택해 사용할 수 있습니다.

카카오계정 ID(account_id)
카카오톡 회원번호(talk_id)
회원번호(user_id)

수신자 ID는 아래 중 한 가지 타입을 선택해 사용할 수 있습니다.

카카오톡 친구 목록 조회 또는 카카오톡 친구 목록 조회로 획득하는 고유 ID(uuid)
카카오계정 ID(account_id)
카카오톡 회원번호(talk_id)
회원번호(user_id)
채팅방 목록 조회로 획득하는 채팅방 ID(chat_id)

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 응답 코드 "0"을 받습니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

receiver_id는 나에게 발송 요청 시 생략할 수 있습니다.

이름	타입	설명	필수
receiver_id	`String`	수신자 ID, 나에게 발송 요청 시 생략	O(Optional)
receiver_id_type	`String`	`receiver_id` 타입, 나에게 발송 요청 시 생략, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	X
message	`MessageObject`	보낼 메시지 타입과 내용	O

MessageObject

이름	타입	설명	필수
message_type	`String`	메시지 타입, 아래 중 하나 `TEXT`: 텍스트 `IMAGE`: 이미지 `FILE`: 파일 `PROFILE`: 프로필 `LOCATION`: 위치 현재 TEXT만 지원	O
text	`String`	메시지 타입이 텍스트 타입인 경우 필수 메시지에 포함할 텍스트	X

요청: 서비스 앱 어드민 키 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

receiver_id는 나에게 발송 요청 시 생략할 수 있습니다.

이름	타입	설명	필수
sender_id	`String`	발신자 ID	O
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
receiver_id	`String`	수신자 ID, 나에게 발송 요청 시 생략	O(Optional)
receiver_id_type	`String`	`receiver_id` 타입, 나에게 발송 요청 시 생략, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	X
message	`MessageObject`	보낼 메시지 타입과 내용	O

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

receiver_id는 나에게 발송 요청 시 생략할 수 있습니다.
요청 대상 사용자와 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, sender_id, sender_id_type
- 서비스 앱 ID: target_app_id, sender_id, sender_id_type
- 발신자 액세스 토큰: sender_access_token

이름	타입	설명	필수
target_app_key	`String`	메시지를 보내려는 서비스 앱 키	O(Optional)
target_app_id	`String`	메시지를 보내려는 앱의 ID	O(Optional)
sender_id	`String`	발신자 ID	O(Optional)
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	O(Optional)
sender_access_token	`String`	발신자의 액세스 토큰 값	O(Optional)
receiver_id	`String`	수신자 ID, 나에게 발송 요청 시 생략	O(Optional)
receiver_id_type	`String`	`receiver_id` 타입, 나에게 발송 요청 시 생략, 아래 중 하나 `user_id`: 회원번호 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID	X
message	`MessageObject`	보낼 메시지 타입과 내용	O

응답

본문

이름	타입	설명	필수
result_code	`Integer`	전송 성공 시 0	O

예제

요청: 액세스 토큰 방식

나에게 텍스트 메시지 발송
파라미터
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d 'message={
      "message_type" : "TEXT",
      "text": "Hello! MyChat!"
    }'

요청: 서비스 앱 어드민 키 방식

나에게 텍스트 메시지 발송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d 'message={
        "message_type" : "TEXT",
        "text": "Hello! MyChat!"
    }'

요청: 서비스 앱 어드민 키 방식

다른 사용자에게 텍스트 메시지 발송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 카카오톡 회원번호(talk_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=700004532" \
  -d "receiver_id_type=talk_id" \
  -d 'message={
    "message_type" : "TEXT",
    "text": "Hello! MyFriend!"
    }'

요청: 서비스 앱 어드민 키 방식

채팅방에 텍스트 메시지 발송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=700009428" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=171976292125929" \
  -d "receiver_id_type=chat_id" \
  -d 'message={
    "message_type" : "TEXT",
    "text": "Hello! MyGroup!"
    }'

요청: 위임 방식

다른 사용자에게 텍스트 메시지 발송
파라미터
- 서비스 앱 키(target_app_key)
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 카카오톡 회원번호(talk_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "sender_id_type=talk_id" \
  -d "sender_id=700003028" \
  -d "receiver_id_type=talk_id" \
  -d "receiver_id=700002957" \
  -d 'message={
      "message_type" : "TEXT",
      "text": "Hello! MyFriend!"
    }'

요청: 위임 방식

다른 사용자에게 텍스트 메시지 발송
파라미터
- 서비스 앱 ID(target_app_id)
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 카카오톡 회원번호(talk_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_id=23456" \
  -d "sender_id_type=talk_id" \
  -d "sender_id=700003028" \
  -d "receiver_id_type=talk_id" \
  -d "receiver_id=700002957" \
  -d 'message={
      "message_type" : "TEXT",
      "text": "Hello! MyFriend!"
    }'

요청: 위임 방식

다른 사용자에게 텍스트 메시지 발송
파라미터
- 발신자 액세스 토큰(sender_access_token)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 카카오톡 회원번호(talk_id)
- 보낼 메시지 타입과 내용(message)

curl -v -X POST "http://kapi.kakao.com/v3/internal/talk/message/send" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "sender_access_token=${ACCESS_TOKEN}" \
  -d "receiver_id_type=talk_id" \
  -d "receiver_id=700002957" \
  -d 'message={
      "message_type" : "TEXT",
      "text": "Hello! MyFriend!"
    }'

응답

{
  "result_code": 0
}

프로필 공개 설정 화면 요청

기본 정보

메서드	URL	인증 방식
`GET`	외부 `https://apps.kakao.com/feedblock`	액세스 토큰

권한	사전 설정	카카오 로그인	동의항목
-	카카오 로그인 활성화 동의항목	필요: 연결	필요: 카카오톡 메시지 전송

사용자가 현재 로그인한 앱의 친구 목록에 자신을 노출할 것인지 공개 여부를 설정할 수 있는 프로필 공개 설정 페이지를 불러옵니다.

헤더에 액세스 토큰을 담아 GET으로 요청합니다. 요청 시 lang 파라미터로 프로필 공개 설정 화면 UI의 언어를 지정할 수 있습니다. 요청 성공 시 프로필 공개 설정 페이지를 불러옵니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
lang	`String`	사용자 언어 정보, KA 헤더와 동일한 규격을 따름 (기본값: `en`)	X

응답

본문

Content-Type: text/html;charset=utf-8의 프로필 공개 설정 페이지 HTML 전문
프로필 공개 설정 페이지는 처리 결과를 반환하지 않으므로, 사용자의 현재 설정 상태는 초대 프로필 공개 상태 조회 또는 프로필 공개 상태 조회 API로 별도 확인해야 함

예제

요청: 액세스 토큰 방식

curl -v -G GET "https://apps.kakao.com/feedblock?lang=ko" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

초대 프로필 공개 상태 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/message/invite/blocked` 공동체 `https://kapi.kakao.com/v1/internal/talk/message/invite/blocked`	서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키	-	-

특정 사용자의 프로필 공개 설정 중 초대 프로필 공개 상태를 확인합니다. 프로필 공개 설정을 비공개로 설정한 수신자에게 카카오톡 메시지 API로 메시지 발송 시 에러가 발생하므로, 메시지 발송 전 이 API를 사용해 프로필 공개 설정을 확인할 수 있습니다. 이 API는 조회 대상 사용자의 앱 연결 상태와 무관하게 요청 가능합니다.

헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 헤더에 "KA: lang/ko-KR" 값을 추가 전달하면 응답의 결과 메시지를 국문으로 받을 수 있습니다. KA 헤더에 대한 자세한 내용은 KA 헤더 정보를 참고합니다.

요청 성공 시 요청 수행 결과 코드와 메시지를 받습니다.

요청: 서비스 앱 어드민 키 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type

이름	타입	설명	필수
target_app_key	`String`	서비스 앱의 키	O(Optional)
target_app_id	`String`	서비스 앱 ID	O(Optional)
target_id	`String`	사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O

응답

본문

이름	타입	설명	필수
code	`Integer`	아래 중 하나 0: 비공개 1: 공개 -1: 조회 실패	O
msg	`String`	결과 메시지, 요청 시 전달된 KA 헤더의 언어 설정에 따라 국문 메시지 지원(기본 언어: 영어)	O

예제

요청: 서비스 앱 어드민 키 방식

파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/invite/blocked" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=talk_id" \
  -d "target_id=30173"

요청: 위임 방식

결과 메시지를 국문으로 받도록 요청
파라미터
- 서비스 앱 ID(target_app_Id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/invite/blocked" \
  -H "KA: lang/ko-KR" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "target_id_type=talk_id" \
  -d "target_id=179404701" \
  -d "target_app_Id=18564"

응답

{
  "code": 1,
  "msg": "공개 상태입니다."
}

프로필 공개 상태 조회

기본 정보

메서드	URL	인증 방식
`GET`	카카오 `http://kapi.kakao.com/v1/internal/talk/message/feed/blocked` 공동체 `https://kapi.kakao.com/v1/internal/talk/message/feed/blocked`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
필요	어드민 키 카카오 로그인 활성화	필요: 연결	-

특정 사용자의 프로필 공개 상태를 확인합니다. 프로필 공개 설정을 비공개로 설정한 수신자에게 카카오톡 메시지 API로 메시지 발송 시 에러가 발생하므로, 메시지 발송 전 이 API를 사용해 프로필 공개 설정을 확인할 수 있습니다. 초대 프로필 공개 상태 조회와 달리, 이 API는 앱과 연결되어 있는 사용자를 대상으로만 요청할 수 있습니다.

헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 사용자의 프로필 공개 상태를 받습니다. 헤더에 "KA: lang/ko-KR" 값을 추가 전달하면 응답의 결과 메시지를 한국어로 받을 수 있습니다. 이 밖에 KA 헤더가 지원하는 정보들을 추가 전달할 수 있습니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

요청: 서비스 앱 어드민 키 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

이름	타입	설명	필수
target_id	`String`	사용자 ID	O
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O

요청: 위임 방식

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, target_id, target_id_type
- 서비스 앱 ID: target_app_id, target_id, target_id_type
- 액세스 토큰: target_access_token

이름	타입	설명	필수
target_app_key	`String`	서비스 앱 키	O(Optional)
target_app_id	`String`	서비스 앱 ID	O(Optional)
target_access_token	`String`	사용자의 액세스 토큰 값	O(Optional)
target_id	`String`	사용자 ID	O(Optional)
target_id_type	`String`	`target_id` 타입, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O(Optional)

응답

본문

이름	타입	설명	필수
code	`Integer`	아래 중 하나 0: 비공개 1: 공개 -1: 조회 실패	O
msg	`String`	결과 메시지, 요청 시 전달된 KA 헤더의 언어 설정에 따라 한국어 메시지 지원(기본 언어: 영어)	O

예제

요청: 액세스 토큰 방식

결과 메시지를 국문으로 받도록 요청
파라미터: 없음

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/feed/blocked" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "KA: lang/ko-KR"

요청: 서비스 앱 어드민 키 방식

결과 메시지를 국문으로 받도록 요청
파라미터
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/feed/blocked" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -H "KA: lang/ko-KR" \
  -d "target_id_type=talk_id" \
  -d "target_id=30173"

요청: 위임 방식

결과 메시지를 국문으로 받도록 요청
파라미터
- 서비스 앱 키(target_app_key)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/feed/blocked" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -H "KA: lang/ko-KR" \
  -d "target_id_type=talk_id" \
  -d "target_id=30173" \
  -d "target_app_key=${SERVICE_APP_KEY}"

요청: 위임 방식

결과 메시지를 국문으로 받도록 요청
파라미터
- 서비스 앱 ID(target_app_id)
- 사용자 ID(target_id)
- 사용자 ID 타입(target_id_type): 카카오톡 회원번호(talk_id)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/feed/blocked" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -H "KA: lang/ko-KR" \
  -d "target_id_type=talk_id" \
  -d "target_id=30173" \
  -d "target_app_id=23456"

요청: 위임 방식

결과 메시지를 국문으로 받도록 요청
파라미터
- 액세스 토큰(target_access_token)

curl -v -G GET "http://kapi.kakao.com/v1/internal/talk/message/feed/blocked" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -H "KA: lang/ko-KR" \
  -d "target_access_token=${ACCESS_TOKEN}"

응답

{
  "code": 1,
  "msg": "공개 상태입니다."
}

이미지 업로드

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/image/upload` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/image/upload` 외부 `https://kapi.kakao.com/v2/api/talk/message/image/upload`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키 카카오 로그인 활성화	필요: 연결*	-

* 액세스토큰 방식으로 요청 시 연결된 사용자여야 하며, 이 외 연결 상태 무관

KAGE 분산 스토리지로 메시지 발송 API에 사용할 이미지를 업로드합니다. KAGE는 동영상, 오디오, 사진, 일반 파일 등 멀티미디어 파일을 업로드해 저장하고, 다운로드나 스트리밍으로 제공하는 파일 저장 솔루션입니다.

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 JSON 객체로 업로드된 이미지 정보를 받습니다. 업로드 가능한 이미지 파일의 크기는 최대 5MB입니다. 업로드된 이미지는 최대 100일까지 보관되며, 이후 자동으로 삭제됩니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
file	`binary`	업로드할 파일의 바이너리(Binary), `Content-Disposition` 헤더에 `filename`을 함께 전달해야 함	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: false)	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
file	`binary`	업로드할 파일의 바이너리(Binary), `Content-Disposition` 헤더에 `filename`을 함께 전달해야 함	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: false)	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, file
- 서비스 앱 ID: target_app_id, file

이름	타입	설명	필수
target_app_key	`String`	이미지를 업로드하려는 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	이미지를 업로드하려는 서비스 앱의 ID	O(Optional)
file	`binary`	업로드할 파일의 바이너리(Binary), `Content-Disposition` 헤더에 `filename`을 함께 전달해야 함	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: `false`)	X

응답

본문

이름	타입	설명	필수
infos	`Infos`	이미지 크기(Size), 이미지 정보의 키와 값 쌍으로 이뤄진 이미지 업로드 결과	O

Infos

이름	타입	설명	필수
url	`String`	업로드된 이미지의 전체 URL	O
length	`int`	업로드된 이미지의 용량(단위: byte)	O
content_type	`String`	업로드된 이미지의 포맷(Format)	O
width	`int`	업로드된 이미지의 가로 크기	O
height	`int`	업로드된 이미지 세로 크기	O

예제

요청: 액세스 토큰 방식

파라미터
- 파일 바이너리(file)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/message/image/upload?secure_resource=false" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F "file=@/aaaa/bbbb/cccc/0.gif"

요청: 서비스 앱 어드민 키 방식

파라미터
- 파일 바이너리(file)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/message/image/upload?secure_resource=false" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -F "file=@/aaaa/bbbb/cccc/0.gif"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 파일 바이너리(file)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/message/image/upload?secure_resource=false&target_app_key=${SERVICE_APP_KEY}" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -F "file=@/aaaa/bbbb/cccc/0.gif"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 파일 바이너리(file)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/message/image/upload?secure_resource=false&target_app_id=392974" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -F "file=@/aaaa/bbbb/cccc/0.jpg"

응답

{
  "infos": {
    "original": {
      "url": "http://api1-kage.kakao.com/dn/bNlCQN/bPAbYyGnYmP/bQoCi8UDxCULM9YHt55cgk/kakaolink40_original.gif",
      "length": 84171,
      "content_type": "image/gif",
      "width": 240,
      "height": 240
    }
  }
}

이미지 스크랩

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/image/scrap` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/image/scrap` 외부 `https://kapi.kakao.com/v2/api/talk/message/image/scrap`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키 카카오 로그인 활성화	필요: 연결*	-

* 액세스토큰 방식으로 요청 시 연결된 사용자여야 하며, 이 외 연결 상태 무관

카카오 내부 또는 외부에 존재하는 웹 URL의 이미지 정보를 KAGE에 스크랩합니다.

헤더에 원하는 인증 정보를 담아 POST로 요청하고, 성공 시 JSON 객체로 스크랩한 이미지 정보를 받습니다. 스크랩한 이미지는 최대 14일까지 보관되며, 이후 자동으로 삭제됩니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
image_url	`String`	스크랩할 이미지 URL	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: false)	X

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
image_url	`String`	스크랩할 이미지 URL	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: false)	X

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

본문

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, image_url
- 서비스 앱 ID: target_app_id, image_url

이름	타입	설명	필수
target_app_key	`String`	이미지를 스크랩하려는 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	이미지를 스크랩하려는 서비스 앱의 ID	O(Optional)
image_url	`String`	스크랩할 이미지 URL	O
secure_resource	`Boolean`	이미지 URL 값의 HTTPS 반환 여부 (기본값: false)	X

응답

본문

이름	타입	설명	필수
infos	`Infos`	이미지 크기(Size), 이미지 정보의 키와 값 쌍으로 이뤄진 이미지 업로드 결과	O

예제

요청: 액세스 토큰 방식

파라미터
- 스크랩할 이미지 URL(image_url)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "https://kapi.kakao.com/v2/internal/talk/message/image/scrap?secure_resource=false" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "image_url=http://t1.daumcdn.net/news/201604/12/womenjoongang/20160412114308246nifw.gif"

요청: 서비스 앱 어드민 키 방식

파라미터
- 스크랩할 이미지 URL(image_url)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "https://kapi.kakao.com/v2/internal/talk/message/image/scrap?secure_resource=false" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "image_url=http://t1.daumcdn.net/news/201604/12/womenjoongang/20160412114308246nifw.gif"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 스크랩할 이미지 URL(image_url)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "https://kapi.kakao.com/v2/internal/talk/message/image/scrap?secure_resource=false" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_key=${SERVICE_APP_KEY}" \
  -d "image_url=http://t1.daumcdn.net/news/201604/12/womenjoongang/20160412114308246nifw.gif"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 스크랩할 이미지 URL(image_url)
- 이미지 URL HTTPS 반환 여부(secure_resource): 사용하지 않음(false)

curl -v -X POST "https://kapi.kakao.com/v2/internal/talk/message/image/scrap?secure_resource=false" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "target_app_id=392974"
-d "image_url=http://t1.daumcdn.net/news/201604/12/womenjoongang/20160412114308246nifw.gif"

응답

{
  "infos": {
    "original": {
      "url": "http://api1-kage.kakao.com/dn/bNlCQN/bPAbYyGnYmP/bQoCi8UDxCULM9YHt55cgk/kakaolink40_original.gif",
      "length": 84171,
      "content_type": "image/gif",
      "width": 240,
      "height": 240
    }
  }
}

이미지 삭제

기본 정보

메서드	URL	인증 방식
`DELETE`	카카오 `http://kapi.kakao.com/v2/internal/talk/message/image/delete` 공동체 `https://kapi.kakao.com/v2/internal/talk/message/image/delete` 외부 `https://kapi.kakao.com/v2/api/talk/message/image/delete`	액세스 토큰 서비스 앱 어드민 키 위임

권한	사전 설정	카카오 로그인	동의항목
-	어드민 키 카카오 로그인 활성화	필요: 연결*	-

* 액세스토큰 방식으로 요청 시 연결된 사용자여야 하며, 이 외 연결 상태 무관

KAGE에 업로드한 이미지를 삭제합니다. KAGE에 업로드된 이미지의 URL이나 이미지 토큰(Image token) 값으로 요청할 수 있습니다. 요청 시 이미지 URL(image_url)과 이미지 토큰(image_token) 파라미터 중 하나는 반드시 전달해야 합니다.

헤더에 원하는 인증 정보를 담아 DELETE로 요청하고, 성공 시 응답 본문(Body)는 없습니다.

요청: 액세스 토큰 방식

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${ACCESS_TOKEN}` 인증 방식, 액세스 토큰으로 인증 요청	O

쿼리 파라미터

image_url과 image_token 중 하나의 파라미터는 필수 전달해야 합니다.

이름	타입	설명	필수
image_url	`String`	KAGE에서 삭제할 이미지 URL `image_url`로 요청 시, KAGE에서 `image_token` 값을 확인해 이미지 삭제 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)
image_token	`String`	KAGE에서 삭제할 이미지 토큰 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)

요청: 서비스 앱 어드민 키 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

쿼리 파라미터

image_url과 image_token 중 하나의 파라미터는 필수 전달해야 합니다.

이름	타입	설명	필수
image_url	`String`	KAGE에서 삭제할 이미지 URL `image_url`로 요청 시, KAGE에서 `image_token` 값을 확인해 이미지 삭제 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)
image_token	`String`	KAGE에서 삭제할 이미지 토큰 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)

요청: 위임 방식

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}` 인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요	O

쿼리 파라미터

요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키: target_app_key, image_url 또는 image_token
- 서비스 앱 ID: target_app_id, image_url 또는 image_token

이름	타입	설명	필수
target_app_key	`String`	이미지를 삭제하려는 서비스 앱의 키	O(Optional)
target_app_id	`Integer`	이미지를 삭제하려는 서비스 앱의 ID	O(Optional)
image_url	`String`	KAGE에서 삭제할 이미지 URL `image_url`로 요청 시, KAGE에서 `image_token` 값을 확인해 이미지 삭제 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)
image_token	`String`	KAGE에서 삭제할 이미지 토큰 `image_url`과 `image_token` 중 하나는 요청 시 필수로 전달되어야 함	O(Optional)

응답

응답 본문 없음

예제

요청: 액세스 토큰 방식

파라미터
- 이미지 토큰(image_token)

curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/talk/message/image/delete" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "image_token=cfgf4R/ZSbxYlxQEF/5O7z0liXAMz9UuC2bERe5k"

요청: 서비스 앱 어드민 키 방식

파라미터
- 이미지 토큰(image_token)

curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/talk/message/image/delete" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "image_token=cfgf4R/ZSbxYlxQEF/5O7z0liXAMz9UuC2bERe5k"

요청: 위임 방식

파라미터
- 서비스 앱 키(target_app_key)
- 이미지 토큰(image_token)

curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/talk/message/image/delete" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "image_token=cfgf4R/ZSbxYlxQEF/5O7z0liXAMz9UuC2bERe5k" \
  -d "target_app_key=${SERVICE_APP_KEY}"

요청: 위임 방식

파라미터
- 서비스 앱 ID(target_app_id)
- 이미지 토큰(image_token)

curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/talk/message/image/delete?" \
  -H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \
  -d "image_token=cfgf4R/ZSbxYlxQEF/5O7z0liXAMz9UuC2bERe5k" \
  -d "target_app_id=392974"

응답

HTTP/1.1 200 OK

사용처 제한 API

사용 협의 필요

사용처 제한 API는 지정된 사용처에만 제공하는 카카오 API입니다. 지정된 사용처 이외의 서비스에서 사용처 제한 API를 사용하려면 [서비스] API플랫폼 아지트에서 별도 협의가 필요합니다.

인하우스 앱: 비연결된 사용자에게 메시지 발송

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/talk/express/message/send` 공동체 `https://kapi.kakao.com/v2/internal/talk/express/message/send`	서비스 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
인하우스 앱: 필요	어드민 키 제품 링크 관리	-	-

연결 상태에 대한 제약 없이 사용자 ID만으로 원하는 대상에게 메시지를 발송합니다. 인하우스 전용 API로 아래 사용 조건을 지켜야 합니다.

메시지 발송 주체: 가입 또는 탈퇴가 없는 플랫폼 형태 인하우스 앱의 특정 사용자
발송 가능 메시지: 사용자가 수신거부 할 필요 없는 정보성 내용으로 한정
- 홍보 또는 이벤트성 메시지를 발송하려는 경우 [서비스] 안녕,톡안티어뷰징파트 및 [서비스] API플랫폼 아지트와 사전 협의 필요

기존의 메시지 발송 API와 차이점은 아래를 참고합니다.

구분	메시지 발송	비연결된 사용자에게 메시지 발송
연결되지 않은 사용자 전송	불가능	가능
수신자 연결(가입) 여부 확인	가능	불가능
수신자의 수신 설정 여부	노출	비노출
프로필 비공개 사용자 대상 전송	불가능	가능
카카오톡 메시지 전송 동의항목 동의	필요	불필요

헤더에 서비스 앱 어드민 키를 담아 POST로 요청합니다.

template_id 파라미터에는 사용자 정의 템플릿의 ID를, template_args 파라미터에는 해당 사용자 정의 템플릿에 정의해 둔 User Argument에 대입할 키와 값을 포함해야 합니다. 사용 목적이 [가입여부 무관]인 메시지 템플릿만 사용 가능합니다. 메시지 템플릿을 참고합니다.

요청 성공 시 응답은 result_code: 0을 포함한 JSON 객체입니다. 요청 실패 시 에러 코드로 원인을 확인합니다.

요청

내부 API 요청 시에만 사용 가능합니다.

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}` 인증 방식, 서비스 앱 어드민 키로 인증 요청	O

본문

이름	타입	설명	필수
receiver_id	`String`	한 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID	O(Optional)
receiver_ids	`String[]`	여러 사용자나 채팅방에 메시지를 보낼 때 사용 메시지 수신자 또는 채팅방 ID 목록	O(Optional)
receiver_id_type	`String`	`receiver_id` 또는 `receiver_ids`의 타입, 아래 중 하나 `uuid`: 고유 ID `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호 `chat_id`: 채팅방 ID (기본값: `uuid`)	X
sender_id	`String`	발신자 ID	O
sender_id_type	`String`	`sender_id` 타입, 아래 중 하나 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호	O
template_id	`String`	[도구] > [메시지 템플릿]에서 구성한 메시지 템플릿 ID (참고: 사용자 정의 템플릿)	O
template_args	`Map<String,String>`	`template_id`로 지정한 메시지 템플릿에 사용자 인자를 사용한 경우, 전달 필수 `key:value` 형식으로 전달 (참고: 사용자 인자) 중요: 사용자 정의 템플릿에 포함된 사용자 인자를 이 파라미터에 포함하지 않은 경우, 사용자 인자로 지정된 부분이 `${KEY}` 형식으로 메시지에 그대로 노출 중요: URL 쿼리 파라미터에 사용자 인자 사용 시, `value`에 해당하는 값에 폼 URL 인코딩(application/x-www-form-urlencoded) 적용 필요	X

응답

본문

이름	타입	설명	필수
result_code	`Integer`	전송 성공 시 0	O
successful_receiver_ids	`String[]`	메시지 전송에 성공한 사용자 ID 배열	X
failure_info	`FailureInfo[]`	실패 정보 메시지 수신자가 1명일 때 실패 시 `failure_info` 없이 에러 코드 전달 메시지 수신자가 2명 이상일 때 실패 시 HTTP 상태 코드(Status code) 200과 함께 실패한 사용자 정보를 `failure_info`로 전달	X

예제

요청: 서비스 앱 어드민 키 방식

한 명의 사용자에게 사용자 정의 메시지 전송
파라미터
- 발신자 ID(sender_id)
- 발신자 ID 타입(sender_id_type): 카카오톡 회원번호(talk_id)
- 수신자 ID(receiver_id)
- 수신자 ID 타입(receiver_id_type): 채팅방 ID(chat_id)
- 메시지 템플릿 ID(template_id)
- 사용자 정의 Argument에 대입할 키와 값(template_args)

curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/express/message/send" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  -d "sender_id=${TALK_ID}" \
  -d "sender_id_type=talk_id" \
  -d "receiver_id=${CHAT_ID}" \
  -d "receiver_id_type=chat_id" \
  -d "template_id=${TEMPLATE_ID}"
-d 'template_args={"TITLE":"타이틀입니다."}'

응답: 1명의 수신자

{
  "result_code": 0
}

응답: 여러 명에게 메시지 전송, 일부 실패

// HTTP/1.1 200 OK
{
  "successful_receiver_ids": ["abcdefg0001", "abcdefg0002"],
  "failure_info": [
    {
      "code": -532,
      "msg": "daily message limit per sender has been exceeded.",
      "receiver_ids": ["abcdefg0003"]
    }
  ]
}

사이드 메뉴

오픈 문서

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

인공지능

플랫폼 API

API 제공

전용 API

어드민 API

더 보기

REST API

나에게 기본 템플릿으로 메시지 발송

나에게 사용자 정의 템플릿으로 메시지 발송

나에게 스크랩 메시지 발송

기본 템플릿으로 메시지 발송

기본 정보

요청: 액세스 토큰 방식

헤더

본문

요청: 서비스 앱 어드민 키 방식

헤더

본문

요청: 위임 방식

헤더

본문

응답

본문

FailureInfo

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

요청: 위임 방식

응답: 1명의 수신자

응답: 여러 명에게 메시지 전송, 일부 실패

사용자 정의 템플릿으로 메시지 발송

기본 정보

요청: 액세스 토큰 방식

헤더

본문

요청: 서비스 앱 어드민 키 방식

헤더

본문

요청: 위임 방식

헤더

본문

응답

본문

예제

요청: 액세스 토큰 방식

요청: 서비스 앱 어드민 키 방식

요청: 위임 방식

응답: 1명의 수신자

응답: 여러 명에게 메시지 전송, 일부 실패

스크랩 메시지 발송

기본 정보

스크랩 메시지 구성에 사용되는 기본 템플릿의 구성

요청: 액세스 토큰 방식

헤더

본문

요청: 서비스 앱 어드민 키 방식

헤더

본문

요청: 위임 방식

헤더

본문

응답

본문

예제

요청: 액세스 토큰 방식, 기본 템플릿 사용

요청: 서비스 앱 어드민 키 방식, 기본 템플릿 사용

요청: 위임 방식, 기본 템플릿 사용

요청: 액세스 토큰 방식, 사용자 정의 템플릿 사용

요청: 서비스 앱 어드민 키 방식, 사용자 정의 템플릿 사용

요청: 위임 방식, 사용자 정의 템플릿 사용

응답: 1명의 수신자

응답: 여러 명에게 메시지 전송, 일부 실패

플레인 메시지 발송

기본 정보