Flutter

This document describes how to integrate Kakao Talk Share APIs into your service with the Kakao SDK for Flutter ("Flutter SDK").

Before you begin

Choose implementation method

1. Select message sending feature

Kakao Developers provides two types of message sending features: Kakao Talk Share and Kakao Talk Message. Select the feature to use by referring to Message sending features. If you want to use Kakao Talk Share, check the content after Step 2.

2. Select message type and configuration method

Decide which message template to use by referring to Template types.

Decide how to configure a message by referring to Configuration method comparison. You can configure a message in object format based on predefined default templates or use custom templates configured directly for your service.

3. Check message sharing method

Kakao Talk Share basically provides functionality to share messages through Kakao Talk, but it also supports web sharing functionality, so it can be used regardless of whether Kakao Talk is installed on the device.

If you want to support sharing only through Kakao Talk according to your service needs, you can check whether Kakao Talk execution is possible using ShareClient's isKakaoTalkSharingAvailable(). The meaning of the method call result is as follows.

• true: One of the following
  • Requested from a native app on a mobile device and Kakao Talk is installed
  • Requested from a web browser (webview) on a mobile device
• false
  • Requested from a native app on a mobile device and Kakao Talk is not installed
  • Not a mobile device

To support Kakao Talk Share on devices where Kakao Talk is not installed or in web browser environments, use the web sharing functionality. Refer to the example below.

bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  print('Sharing through Kakao Talk available');
} else {
  print('Kakao Talk not installed: Web sharing functionality recommended');
}

Project configuration

To use Kakao Talk Share APIs in native app services, you need to set up Custom URL Scheme. Refer to the device environment-specific project configuration methods below.

• Android: Custom URL scheme
• iOS: Custom URL scheme

Send message with default template

Basic information

This API enables you to share messages through Kakao Talk using predefined default templates.

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareDefault(). When the request is successful, a Uri is returned that allows you to navigate to the screen for sharing messages with default templates in Kakao Talk. Execute sharing by calling ShareClient's launchKakaoTalk() method with the returned Uri.
   • If Kakao Talk is not installed: Call WebSharerClient's makeDefaultUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowserTab() method with the returned Uri. In web environments, you can open the Kakao Talk Share page as a popup by setting the popupOpen parameter value to true when calling launchBrowserTab().
2. Configure message template: For message creation, implement the DefaultTemplate interface, then use one of the classes below according to the desired template type to configure template objects.
   • Feed template: FeedTemplate
   • List template: ListTemplate
   • Location template: LocationTemplate
   • Commerce template: CommerceTemplate
   • Text template: TextTemplate
   • Calendar template: CalendarTemplate
3. Pass template object: When calling shareDefault() or makeDefaultUrl(), pass the previously configured template object as the template parameter.

Sample

// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri =
        await ShareClient.instance.shareDefault(template: defaultFeed);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
}
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeDefaultUrl(template: defaultFeed);
    await launchBrowserTab(shareUrl, popupOpen: true);
} catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Send message with custom template

Basic information

This API enables you to customize a template in [Tools] > [Message Template] and send a message through Kakao Talk. For message configuration methods, refer to Custom template.

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareCustom(). When the request is successful, a Uri is returned that allows you to navigate to the screen for sharing messages with default templates in Kakao Talk. Execute sharing by calling ShareClient's launchKakaoTalk() method with the returned Uri.
   • If Kakao Talk is not installed: Call WebSharerClient's makeCustomUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowserTab() method with the returned Uri. In web environments, you can open the Kakao Talk Share page as a popup by setting the popupOpen parameter value to true when calling launchBrowserTab().
2. Configure message template: Configure the message template in [Tools] > [Message Template]. For template configuration methods, refer to Custom template.
3. Specify template: When calling shareCustom() or makeCustomUrl(), pass the template ID configured in the message template tool as the templateId parameter.
4. Pass user arguments (optional): To include variable information in messages, add user arguments to the corresponding custom template, then pass keys and values as the templateArgs parameter. If you do not use this parameter even though the custom template includes user arguments, the part specified as user arguments will be exposed in the message as ${KEY} format.

Sample

// Custom template ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri =
        await ShareClient.instance.shareCustom(templateId: templateId);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance.makeCustomUrl(
        templateId: templateId, templateArgs: {'key1': 'value1'});    
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Send scrape message

Basic information

This API enables you to share a Kakao Talk message by scraping the specified web page and configuring a scrap message with the scraped information.

Request

1. Check if Kakao Talk is installed: To check if it is possible to share a message through Kakao Talk, first call isKakaoTalkSharingAvailable() to check if Kakao Talk is installed on the user's device.
   • If Kakao Talk is installed: Call ShareClient's shareScrap(). When the request is successful, a Uri is returned that allows you to navigate to the screen for sharing messages with default templates in Kakao Talk. Execute sharing by calling ShareClient's launchKakaoTalk() method with the returned Uri.
   • If Kakao Talk is not installed: Call WebSharerClient's makeScrapUrl(). When the request is successful, a Uri is returned that executes web sharing functionality. Execute sharing by calling the launchBrowserTab() method with the returned Uri. In web environments, you can open the Kakao Talk Share page as a popup by setting the popupOpen parameter value to true when calling launchBrowserTab().
2. Specify web page URL for scraping: When calling shareScrap() or makeScrapUrl(), you must pass the URL of the web page to be scraped as the url parameter. The domain of the web page to be scraped must be registered in [App] > [General] > [Platform] > [Web] on the app management page.
3. Apply custom template (optional): If you want to send scrape messages based on service-defined message templates, you must pass the ID of the template configured in [Tools] > [Message Template] as the templateId parameter. For template configuration methods, refer to Custom template. To include variable information in messages, use user arguments. In this case, you must pass keys and values as the templateArgs parameter.

Sample: Using default template

// Web page URL to be scraped
  String url = "https://developers.kakao.com";
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri = await ShareClient.instance.shareScrap(url: url);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeScrapUrl(url: url, templateArgs: {'key1': 'value1'});
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Sample: Using custom template

// Custom template ID
int templateId = '${YOUR_CUSTOM_TEMPLATE_ID}';
// Web page URL to be scraped
String url = "https://developers.kakao.com";
// Check if Kakao Talk execution is available
bool isKakaoTalkSharingAvailable = await ShareClient.instance.isKakaoTalkSharingAvailable();

if (isKakaoTalkSharingAvailable) {
  try {
    Uri uri = await ShareClient.instance.shareScrap(url: url, templateId: templateId);
    await ShareClient.instance.launchKakaoTalk(uri);
    print('Kakao Talk Share completed');
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }  
} else {
  try {
    Uri shareUrl = await WebSharerClient.instance
        .makeScrapUrl(url: url, templateId: templateId, templateArgs: {'key1': 'value1'});
    await launchBrowserTab(shareUrl, popupOpen: true);
  } catch (error) {
    print('Kakao Talk Share failed $error');
  }
}

Set Kakao Talk Share webhook custom parameters

Kakao Talk Share webhook is a function to send a webhook request to the URL specified on Kakao Developers when a Kakao Talk Share message is successfully sent to friends or a chatroom selected by a user.

Kakao Talk Share webhook can only be used when sending Kakao Talk Share messages and is not supported for Kakao Talk Message transmission. Kakao Talk Share is sent by users through Kakao Talk, so services cannot directly confirm whether the message was sent successfully. Therefore, a webhook function is provided to notify when message transmission is successful.

To use this feature, you need to:

1. Set the webhook URL and request method by referring to Kakao Talk Share webhook setting.
2. Build a server to receive a Kakao Talk Share webhook.
3. Pass custom (Custom) parameters when calling the Kakao Talk Share API.
4. Implement a process to handle the notification delivered to the webhook URL of your service server.

The Kakao Talk Share webhook sent to your service server does not include detailed message transmission information. To figure out additional information needed by the service, such as which message's transmission result it is and what content the user shared, you must use custom (Custom) parameters. Also, Kakao Talk Share messages without custom parameters will not deliver Kakao Talk Share webhooks.

Custom parameters must be passed as the serverCallbackArgs parameter when making Kakao Talk Share requests, and you cannot use system reserved words CHAT_TYPE, HASH_CHAT_ID, and TEMPLATE_ID as keys. These keys are included in the notification with the values defined in the specification of Kakao Talk Share webhook.

Below is an example of a Kakao Talk Share request including custom parameters.

try {
  // Pass custom parameters through serverCallbackArgs parameter
  // If this parameter is not used, Kakao Talk Share webhook will not be delivered
  Uri uri =
      await ShareClient.instance.defaultTemplate(template: defaultFeed, serverCallbackArgs: {'key1': 'value1'});
    await ShareClient.instance.launchKakaoTalk(uri);
  print('Kakao Talk Share completed');
  } catch (error) {
  print('Kakao Talk Share failed $error');
}

Upload image

Basic information

You can attach images to a message by passing an image URL when configuring a message template or uploading images in the Message Template Tool in advance. Image files must be uploaded to the Kakao server or scraped to be used for message transmission.

You can upload or scrape images to the Kakao server using methods provided by ShareClient. You can only upload images with a file size of 5 MB or less. The images uploaded to the Kakao server are stored for up to 100 days and automatically deleted after the period.

To upload an image file to the Kakao server, call uploadImage(). Pass the image file to upload using one of the following parameters.

• image: Pass image as File format to upload
• byteData: Pass image as ByteData format to upload

To scrape an image on the web to the Kakao server, call scrapImage().

When the request is successful, an ImageUploadResult object is returned. You can check the uploaded image information, such as the image URL to use for message transmission, from the ImageInfo inside that object.

Sample

Upload image

// Local image file
// This example uses an image file added as a project resource.
// Prepare photo files needed for your service, such as from gallery.
ByteData byteData = await rootBundle.load('assets/images/cat1.png');

// This example saves project resources as image files using path_provider.
File tempFile =
  File('${(await getTemporaryDirectory()).path}/cat1.png');
File file = await tempFile.writeAsBytes(byteData.buffer
  .asUint8List(byteData.offsetInBytes, byteData.lengthInBytes));

try {
  // Upload to Kakao image server
  ImageUploadResult imageUploadResult =
    await ShareClient.instance.uploadImage(image: file);
  print('Image upload successful'
        '\n${imageUploadResult.infos.original}');
} catch (error) {
  print('Image upload failed $error');
}

// This sample uses file_picker to get image files.
var filePickerResult = await FilePicker.platform.pickFiles();

if (filePickerResult != null) {
  var byteData = filePickerResult.files.first.bytes;

  try {
    // Upload to Kakao image server
    ImageUploadResult imageUploadResult =
        await ShareClient.instance.uploadImage(byteData: byteData);
    Log.i(context, tag,
        'Image upload successful\n${imageUploadResult.infos.original}');
  } catch (e) {
    Log.e(context, tag, 'Image upload failed', e);
  }
}

Scrape image

// Original image URL
String url =
    'https://t1.kakaocdn.net/kakaocorp/Service/KakaoTalk/pc/slide/talkpc_theme_01.jpg';

try {
  // Scrape image to Kakao server
  ImageUploadResult imageUploadResult =
    await ShareClient.instance.scrapImage(imageUrl: url);
  print('Image scraping successful'
        '\n${imageUploadResult.infos.original}');
} catch (error) {
  print('Image scraping failed $error');
}

See more

Message Template Tooloutlink ```