페이지 이동경로
  • 문서>
  • 메시지>
  • 카카오톡 메시지: Flutter

메시지

카카오톡 메시지: Flutter

이 문서는 Kakao SDK for Flutter(이하 Flutter SDK)를 사용한 카카오톡 메시지 API 구현 방법을 안내합니다.

시작하기 전에

구현 방식 선택

1. 메시지 API 선택하기

메시지 API는 카카오톡 공유와 카카오톡 메시지 두 가지입니다. 이해하기를 참고해 어떤 API로 메시지 보내기를 구현할 것인지 결정합니다. 카카오톡 메시지를 사용하려는 경우, Step 2 이후의 내용을 확인합니다.

2. 메시지 종류 및 구성 방법 선택하기

메시지 템플릿을 참고하여 어떤 메시지 템플릿을 사용할지 결정합니다.

보낼 메시지는 기본 템플릿을 바탕으로 객체 형태로 구성하거나, 서비스에 맞게 직접 구성한 사용자 정의 템플릿을 사용하여 구성할 수 있습니다. 자세한 정보는 사용 방법에서 확인할 수 있습니다.

3. 메시지 전송 대상 선택하기

카카오톡 메시지의 경우, 수신 대상에 따라 나에게 보내기, 친구에게 보내기로 API가 구분되어 있다는 점에 유의합니다.

전송 대상 설명
나에게 보내기 현재 로그인한 사용자의 카카오톡 나와의 채팅에 메시지를 보냅니다. 이 기능으로는 다른 사용자에게 메시지를 보낼 수 없고, 로그인한 사용자 본인에게만 메시지를 보낼 수 있습니다.
친구에게 보내기 현재 로그인한 사용자의 카카오톡 친구에게 메시지를 보냅니다. 친구 목록 가져오기 API를 통해 수신 대상 정보를 받는 과정을 추가 구현해야 합니다. 한 번에 최대 5명의 친구에게 메시지를 보낼 수 있습니다. 일간 및 월간 제공량이 정해져 있으므로 쿼터를 참고합니다.
주의: 사용 권한

친구에게 보내기를 사용하려는 경우, 카카오톡 메시지 사용 권한 신청을 참고하여 테스트 및 사용 권한 신청을 진행합니다. 이용 정책을 함께 참고합니다.


참고: 선택 조건별 필요한 메서드
전송 대상 메시지 종류 사용 방법 메서드
나에게 보내기 피드, 리스트, 위치, 커머스, 텍스트 기본 템플릿 sendDefaultMemo()
피드, 리스트, 커머스 사용자 정의 템플릿 sendCustomMemo()
스크랩 기본 템플릿 sendScrapMemo()
사용자 정의 템플릿 sendScrapMemo()
친구에게 보내기 피드, 리스트, 위치, 커머스, 텍스트 기본 템플릿 friends()
sendDefaultMessage()
피드, 리스트, 커머스 사용자 정의 템플릿 friends()
sendCustomMessage()
스크랩 기본 템플릿 friends()
sendScrapMessage()
사용자 정의 템플릿 friends()
sendScrapMessage()

프로젝트 설정

네이티브 앱 서비스에서 카카오톡 메시지 API를 사용하려면 커스텀 URL 스킴(Custom URL Scheme)을 설정해야 합니다. 아래의 디바이스 환경별 프로젝트 설정 방법을 참고합니다.

메시지 만들기

카카오톡 메시지를 사용하기 위해 기본 템플릿을 만드는 방법은 카카오톡 공유와 동일합니다. 카카오톡 공유: Flutter에서 기본 템플릿 생성 안내와 예제를 확인할 수 있습니다.

기본 템플릿으로 메시지 보내기

기본 정보
레퍼런스 앱 설정
sendDefaultMemo()
sendDefaultMessage()
FeedTemplate
ListTemplate
LocationTemplate
CommerceTemplate
TextTemplate
MessageSendResult
MessageFailureInfo		 설치
초기화
프로젝트 설정
권한 사전 설정 카카오 로그인 동의항목
- 플랫폼 등록
카카오 로그인 활성화
동의항목		 필요 필요:
카카오톡 메시지 전송(talk_message)

기본 템플릿을 사용해 현재 로그인한 사용자의 카카오톡으로 메시지를 보냅니다. 메시지 전송 대상에 따라 호출해야 할 메서드가 다릅니다.

요청 성공 시, 메시지 전송 결과를 담은 MessageSendResult 객체가 반환됩니다. 일부 친구에게는 메시지 전송이 실패한 경우, failureInfos 값인 MessageFailureInfo에서 메시지 전송에 실패한 친구의 uuid 목록과 에러 코드를 확인할 수 있습니다. 응답 코드에서 원인을 확인합니다.

나에게 보내기

요청

TalkApi의 sendDefaultMemo()를 호출합니다. 요청 시 기본 템플릿 객체를 template 파라미터로 전달해야 합니다.

예제

try {
  await TalkApi.instance.sendDefaultMemo(defaultFeed);
  print('나에게 보내기 성공');
} catch (error) {
  print('나에게 보내기 실패 $error');
}

친구에게 보내기

요청

TalkApi의 sendDefaultMessage()를 호출합니다. 먼저 친구 목록 가져오기를 통해 메시지를 보낼 친구의 uuid를 구한 뒤, sendDefaultMessage() 호출 시 receiverUuids 파라미터로 전달해야 합니다. 기본 템플릿 객체는 template 파라미터로 전달합니다.

예제

// 카카오톡 친구 목록 가져오기
Friends friends;
try {
  friends = await TalkApi.instance.friends();
} catch (error) {
  print('카카오톡 친구 목록 가져오기 실패 $error');
  // 메시지를 보낼 수 있는 친구 정보 가져오기에 실패한 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements == null) {
  // 메시지를 보낼 수 있는 친구가 없는 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements!.isEmpty) {
  print('메시지를 보낼 친구가 없습니다');
} else {
  // 서비스에 상황에 맞게 메시지 보낼 친구의 UUID를 가져옵니다.
  // 이 예제에서는 친구 목록을 화면에 보여주고 체크박스로 선택된 친구들의 UUID를 수집하도록 구현했습니다.
  List<String> selectedItems = await Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => FriendPage(
        items: friends.elements!
            .map((friend) => PickerItem(
                friend.uuid,
                friend.profileNickname ?? '',
                friend.profileThumbnailImage))
            .toList(),
      ),
    ),
  );

  if (selectedItems.isEmpty) {
    // 메시지를 보낼 친구를 선택하지 않은 경우에 대한 예외 처리 필요
    return;
  }
  print('선택된 친구:\n${selectedItems.join('\n')}');

  // 메시지를 보낼 친구의 UUID 목록
  List<String> receiverUuids = selectedItems;

  // 피드 메시지, 메시지 만들기 참고
  FeedTemplate template = defaultFeed;

  // 기본 템플릿으로 메시지 보내기
  try {
    MessageSendResult result =
        await TalkApi.instance.sendDefaultMessage(
      receiverUuids: receiverUuids,
      template: template,
    );
    print('메시지 보내기 성공 ${result.successfulReceiverUuids}');

    if (result.failureInfos != null) {
      print('일부 대상에게 메시지 보내기 실패'
            '\n${result.failureInfos}');
    }
  } catch (error) {
    print('메시지 보내기 실패 $error');
  }
}

사용자 정의 템플릿으로 메시지 보내기

기본 정보
레퍼런스 앱 설정
sendCustomMemo()
sendCustomMessage()
MessageSendResult
MessageFailureInfo		 설치
초기화
프로젝트 설정
권한 사전 설정 카카오 로그인 동의항목
- 플랫폼 등록
카카오 로그인 활성화
동의항목
메시지 템플릿		 필요 필요:
카카오톡 메시지 전송(talk_message)

[도구] > [메시지 템플릿]에서 직접 구성한 사용자 정의 템플릿을 사용하여 현재 로그인한 사용자의 카카오톡으로 메시지를 보냅니다. 메시지 전송 대상에 따라 호출해야 할 메서드가 다릅니다.

메시지에 변동되는 정보를 포함하려면 해당 사용자 정의 템플릿에 사용자 인자를 추가한 후, templateArgs 파라미터를 통해 키와 값을 전달합니다. 사용자 정의 템플릿에 사용자 인자가 포함되었음에도 해당 파라미터를 사용하지 않을 경우, 사용자 인자로 지정된 부분이 ${KEY} 형식으로 메시지에 그대로 노출됩니다.

요청 성공 시, 메시지 전송 결과를 담은 MessageSendResult 객체가 반환됩니다. 일부 친구에게는 메시지 전송이 실패한 경우, failureInfos 값인 MessageFailureInfo에서 메시지 전송에 실패한 친구의 uuid 목록과 에러 코드를 확인할 수 있습니다. 응답 코드에서 원인을 확인합니다.

나에게 보내기

요청

TalkApi의 sendCustomMemo()를 호출합니다. 요청 시 사용자 정의 템플릿 ID를 templateId 파라미터로 전달해야 합니다.

예제

// 사용자 정의 템플릿 ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';

try {
  await TalkApi.instance.sendCustomMemo(templateId: templateId);
  print('나에게 보내기 성공');
} catch (error) {
  print('나에게 보내기 실패 $error');
}

친구에게 보내기

요청

TalkApi의 sendCustomMessage()를 호출합니다. 먼저 친구 목록 가져오기를 통해 메시지를 보낼 친구의 uuid를 구한 뒤, sendCustomMessage() 호출 시 receiverUuids 파라미터로 전달해야 합니다. 사용자 정의 템플릿 ID는 templateId 파라미터로 전달합니다.

예제

// 카카오톡 친구 목록 가져오기
Friends friends;
try {
  friends = await TalkApi.instance.friends();
} catch (error) {
  print('카카오톡 친구 목록 가져오기 실패 $error');
  // 메시지를 보낼 수 있는 친구 정보 가져오기에 실패한 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements == null) {
  // 메시지를 보낼 수 있는 친구가 없는 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements!.isEmpty) {
  print('메시지를 보낼 친구가 없습니다');
} else {
  // 서비스에 상황에 맞게 메시지 보낼 친구의 UUID를 가져옵니다.
  // 이 예제에서는 친구 목록을 화면에 보여주고 체크박스로 선택된 친구들의 UUID를 수집하도록 구현했습니다.
  List<String> selectedItems = await Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => FriendPage(
        items: friends.elements!
            .map((friend) => PickerItem(
                friend.uuid,
                friend.profileNickname ?? '',
                friend.profileThumbnailImage))
            .toList(),
      ),
    ),
  );

  if (selectedItems.isEmpty) {
    // 메시지를 보낼 친구를 선택하지 않은 경우에 대한 예외 처리 필요
    return;
  }
  print('선택된 친구:\n${selectedItems.join('\n')}');

  // 메시지를 보낼 친구의 UUID 목록
  List<String> receiverUuids = selectedItems;

  // 사용자 정의 템플릿 ID
  int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';

  // 사용자 정의 템플릿으로 메시지 보내기
  try {
    MessageSendResult result = await TalkApi.instance.sendCustomMessage(
      receiverUuids: receiverUuids,
      templateId: templateId,
    );
    print('메시지 보내기 성공 ${result.successfulReceiverUuids}');

    if (result.failureInfos != null) {
      print('일부 대상에게 메시지 보내기 실패'
            '\n${result.failureInfos}');
    }
  } catch (error) {
    print('메시지 보내기 실패 $error');
  }
}

기본 템플릿으로 스크랩 메시지 보내기

기본 정보
레퍼런스 앱 설정
sendScrapMemo()
sendScrapMessage()
FeedTemplate
ListTemplate
LocationTemplate
CommerceTemplate
TextTemplate
MessageSendResult
MessageFailureInfo		 설치
초기화
프로젝트 설정
권한 사전 설정 카카오 로그인 동의항목
- 플랫폼 등록
카카오 로그인 활성화
동의항목		 필요 필요:
카카오톡 메시지 전송(talk_message)

지정한 웹 페이지를 스크랩한 정보로 스크랩 메시지를 구성하고, 현재 로그인한 사용자의 카카오톡으로 메시지를 보냅니다. 메시지 전송 대상에 따라 호출해야 할 메서드가 다릅니다.

요청 성공 시, 메시지 전송 결과를 담은 MessageSendResult 객체가 반환됩니다. 일부 친구에게는 메시지 전송이 실패한 경우, failureInfos 값인 MessageFailureInfo에서 메시지 전송에 실패한 친구의 uuid 목록과 에러 코드를 확인할 수 있습니다. 응답 코드에서 원인을 확인합니다.

나에게 보내기

요청

TalkApi의 sendScrapMemo()를 호출합니다. 요청 시 스크랩할 웹 페이지 URL을 url 파라미터로 전달해야 합니다.

예제

// 스크랩할 웹 페이지 URL
String url = 'https://developers.kakao.com';

try {
  await TalkApi.instance.sendScrapMemo(url: url);
  print('나에게 보내기 성공');
} catch (error) {
  print('나에게 보내기 실패 $error');
}

친구에게 보내기

요청

TalkApi의 sendScrapMessage()를 호출합니다. 먼저 친구 목록 가져오기를 통해 메시지를 보낼 친구의 uuid를 구한 뒤, sendScrapMessage() 호출 시 receiverUuids 파라미터로 전달해야 합니다. 스크랩할 웹 페이지 URL은 url 파라미터로 전달합니다.

예제

// 카카오톡 친구 목록 가져오기
Friends friends;
try {
  friends = await TalkApi.instance.friends();
} catch (error) {
  print('카카오톡 친구 목록 가져오기 실패 $error');
  // 메시지를 보낼 수 있는 친구 정보 가져오기에 실패한 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements == null) {
  // 메시지를 보낼 수 있는 친구가 없는 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements!.isEmpty) {
  print('메시지를 보낼 친구가 없습니다');
} else {
  // 서비스에 상황에 맞게 메시지 보낼 친구의 UUID를 가져옵니다.
  // 이 예제에서는 친구 목록을 화면에 보여주고 체크박스로 선택된 친구들의 UUID를 수집하도록 구현했습니다.
  List<String> selectedItems = await Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => FriendPage(
        items: friends.elements!
            .map((friend) => PickerItem(
                friend.uuid,
                friend.profileNickname ?? '',
                friend.profileThumbnailImage))
            .toList(),
      ),
    ),
  );

  if (selectedItems.isEmpty) {
    // 메시지를 보낼 친구를 선택하지 않은 경우에 대한 예외 처리 필요
    return;
  }
  print('선택된 친구:\n${selectedItems.join('\n')}');

  // 메시지를 보낼 친구의 UUID 목록
  List<String> receiverUuids = selectedItems;

  // 피드 메시지, 메시지 만들기 참고
  FeedTemplate template = defaultFeed;

  // 기본 템플릿으로 스크랩 메시지 보내기
  try {
    MessageSendResult result = await TalkApi.instance.sendScrapMessage(
      receiverUuids: receiverUuids,
      url: url,
    );
    
    print('메시지 보내기 성공 ${result.successfulReceiverUuids}');

    if (result.failureInfos != null) {
      print('일부 대상에게 메시지 보내기 실패'
            '\n${result.failureInfos}');
    }
  } catch (error) {
    print('메시지 보내기 실패 $error');
  }
}

사용자 정의 템플릿으로 스크랩 메시지 보내기

기본 정보
레퍼런스 앱 설정
sendScrapMemo()
sendScrapMessage()
MessageSendResult
MessageFailureInfo		 설치
초기화
프로젝트 설정
권한 사전 설정 카카오 로그인 동의항목
- 플랫폼 등록
카카오 로그인 활성화
동의항목
메시지 템플릿		 필요 필요:
카카오톡 메시지 전송(talk_message)

[도구] > [메시지 템플릿]에서 직접 구성한 사용자 정의 템플릿에 지정한 웹 페이지의 스크랩 정보를 대입해 스크랩 메시지를 구성하고, 현재 로그인한 사용자의 카카오톡으로 메시지를 보냅니다. 메시지 전송 대상에 따라 호출해야 할 메서드가 다릅니다.

메시지에 변동되는 정보를 포함하려면 해당 사용자 정의 템플릿에 사용자 인자를 추가한 후, templateArgs 파라미터를 통해 키와 값을 전달합니다. 사용자 정의 템플릿에 사용자 인자가 포함되었음에도 해당 파라미터를 사용하지 않을 경우, 사용자 인자로 지정된 부분이 ${KEY} 형식으로 메시지에 그대로 노출됩니다.

친구에게 메시지를 보내려면 메시지 전송 요청 시 누구에게 메시지를 보낼 것인지 지정해야 합니다. 친구 목록 가져오기를 통해 메시지를 보낼 친구의 uuid 정보를 확인할 수 있습니다. 친구 목록을 만들어 사용자에게 보여주고, 사용자가 선택한 친구들의 uuid 목록은 receiverUuids 파라미터에 리스트(List)로 담아 전달합니다. 한 번에 최대 5명의 친구에게 메시지를 보낼 수 있습니다.

요청 성공 시, 메시지 전송 결과를 담은 MessageSendResult 객체가 반환됩니다. 일부 친구에게는 메시지 전송이 실패한 경우, failureInfos 값인 MessageFailureInfo에서 메시지 전송에 실패한 친구의 uuid 목록과 에러 코드를 확인할 수 있습니다. 응답 코드에서 원인을 확인합니다.

나에게 보내기

요청

TalkApi의 sendScrapMemo()를 호출합니다. 요청 시 스크랩할 웹 페이지 URL을 url 파라미터로 전달해야 합니다. 웹 페이지 스크랩 결과를 대입할 사용자 정의 템플릿의 ID는 templateId 파라미터로 전달합니다.

예제

// 사용자 정의 템플릿 ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';

try {
  await TalkApi.instance.sendScrapMemo(url: url);
  print('나에게 보내기 성공');
} catch (error) {
  print('나에게 보내기 실패 $error');
}

친구에게 보내기

요청

TalkApi의 sendScrapMessage()를 호출합니다. 먼저 친구 목록 가져오기를 통해 메시지를 보낼 친구의 uuid를 구한 뒤, sendScrapMessage() 호출 시 receiverUuids 파라미터로 전달해야 합니다.

스크랩할 웹 페이지 URL은 url 파라미터로, 웹 페이지 스크랩 결과를 대입할 사용자 정의 템플릿의 ID는 templateId 파라미터로 각각 전달합니다.

예제

// 카카오톡 친구 목록 가져오기
Friends friends;
try {
  friends = await TalkApi.instance.friends();
} catch (error) {
  print('카카오톡 친구 목록 가져오기 실패 $error');
  // 메시지를 보낼 수 있는 친구 정보 가져오기에 실패한 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements == null) {
  // 메시지를 보낼 수 있는 친구가 없는 경우에 대한 예외 처리 필요
  return;
}

if (friends.elements!.isEmpty) {
  print('메시지를 보낼 친구가 없습니다');
} else {
  // 서비스에 상황에 맞게 메시지 보낼 친구의 UUID를 가져옵니다.
  // 이 예제에서는 친구 목록을 화면에 보여주고 체크박스로 선택된 친구들의 UUID를 수집하도록 구현했습니다.
  List<String> selectedItems = await Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => FriendPage(
        items: friends.elements!
            .map((friend) => PickerItem(
                friend.uuid,
                friend.profileNickname ?? '',
                friend.profileThumbnailImage))
            .toList(),
      ),
    ),
  );

  if (selectedItems.isEmpty) {
    // 메시지를 보낼 친구를 선택하지 않은 경우에 대한 예외 처리 필요
    return;
  }
  print('선택된 친구:\n${selectedItems.join('\n')}');

  // 메시지를 보낼 친구의 UUID 목록
  List<String> receiverUuids = selectedItems;

  // 사용자 정의 템플릿 ID
  int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';

  // 
  try {
    MessageSendResult result = await TalkApi.instance.sendScrapMessage(
      receiverUuids: receiverUuids,
      url: url,
    );
    
    print('메시지 보내기 성공 ${result.successfulReceiverUuids}');

    if (result.failureInfos != null) {
      print('일부 대상에게 메시지 보내기 실패'
            '\n${result.failureInfos}');
    }
  } catch (error) {
    print('메시지 보내기 실패 $error');
  }
}

이미지 업로드하기

메시지에 넣을 이미지는 URL 형태로 메시지 템플릿 구성 시에 첨부하거나, 메시지 템플릿 도구에서 미리 업로드할 수 있습니다. 기기에 저장된 이미지 파일은 카카오 서버에 업로드하거나 스크랩해야 메시지 전송에 사용할 수 있습니다.자세한 안내와 예제는 이미지 업로드하기에서 확인할 수 있습니다.

더 보기

메시지> 카카오톡 메시지: Flutter