iOS

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

Before you begin

Choose an 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 a 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. Send a message

Call the message sending API. If the request is successful, the iOS SDK launches Kakao Talk or lets a user log in with Kakao Account on a web page, and then shows a list of friends or chatrooms. When a user selects friends or a chatroom to send the message to, the messages are sent to the selected targets.

Set custom URL scheme

To make your app launch when a user clicks a button in the Kakao Talk Share message, you need to set App execution allowlist. When using Kakao Talk Share and Kakao Talk Message, you need "kakaolink" value in the LSApplicationQueriesSchemes setting. This setting is used to create a custom URL scheme (Custom URL Scheme) in the form of "kakao${YOUR_NATIVE_APP_KEY}://kakaolink" for app execution.

Note: Pass additional information when launching app

For native apps, you can pass additional information according to service needs when launching the app through custom URL scheme. You can set keys and values to pass when launching the app using androidExecutionParams and iosExecutionParams parameters. When using these parameters, clicking the app execution button in Kakao Talk Share message calls the following scheme.

kakao${YOUR_NATIVE_APP_KEY}://kakaolink?${androidExecutionParams}
kakao${YOUR_NATIVE_APP_KEY}://kakaolink?${iosExecutionParams}
// Example
kakao${YOUR_NATIVE_APP_KEY}://kakaolink?key1=value1&key2=value2&key3=value3

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 shareDefault() to receive a SharingResult object. Use the intent of that object to launch an activity and implement sharing the message through Kakao Talk.
   • If Kakao Talk is not installed: Generate a web sharing URL using makeDefaultUrl() in WebSharerClient, then implement to open that URL in a default browser or webview.
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. Or refer to Advanced: Create a message using constructor to create a templateObject object for use when sending messages.
   • 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 templatable parameter.

Sample

//in ViewController
var safariViewController : SFSafariViewController? // to keep instance
//...

guard let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) else {
    return
}

// Check if Kakao Talk has been installed.
if ShareApi.isKakaoTalkSharingAvailable() {
    // Kakao Talk Share is available.
    // For 'templatable' examples, refer to the documentation: https://developers.kakao.com/docs/latest/ko/message-template/default
    ShareApi.shared.shareDefault(templatable: templatable) {(sharingResult, error) in
    if let error = error {
        print(error)
    }
    else {
        print("shareDefault() success.")

        if let sharingResult = sharingResult {
            UIApplication.shared.open(sharingResult.url, 
                            options: [:], completionHandler: nil)
        }
    }
}
else {
    // If Kakao Talk is not installed, it is recommended to share URI via web.
    // You can use custom webView or default browser.
    // Example of sharing URI via web
    if let url = ShareApi.shared.makeDefaultUrl(templatable: templatable) {
        self.safariViewController = SFSafariViewController(url: url)
        self.safariViewController?.modalTransitionStyle = .crossDissolve
        self.safariViewController?.modalPresentationStyle = .overCurrentContext
        self.present(self.safariViewController!, animated: true) {
            print("Web present success")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

// For 'templatable' examples, refer to the documentation: https://developers.kakao.com/docs/latest/ko/message-template/default
if let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) {
    ShareApi.shared.rx.shareDefault(templatable:templatable)
        .subscribe(onSuccess: { (sharingResult) in
            print("shareDefault() success.")
            
            UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
        }, onFailure: {error in
            print(error)
        })
        .disposed(by: disposeBag)
}

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 shareCustom() to receive a SharingResult object. Use the requestUrl of that object to open and share the message through Kakao Talk.
   • If Kakao Talk is not installed: Generate a web sharing URL using makeCustomUrl(), then implement to open that URL in a default browser or webview.
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.

Calling shareCustom() launches the Kakao Talk application and shows the list of user's Kakao Talk friends or chatrooms. When a user selects friends or a chatroom to send the message to, the messages are sent to the selected targets.

shareCustom() returns SharingResult. Because the Kakao Talk Share API does not inform the result of message delivery, implement the Kakao Talk Share webhook function.

Sample

let templateId = 12345

// Check if Kakao Talk has been installed.
if ShareApi.isKakaoTalkSharingAvailable() {
    // Kakao Talk Share is available.
    ShareApi.shared.shareCustom(templateId: templateId, templateArgs:["title":"This is title.", "description":"This is description."]) {(sharingResult, error) in
        if let error = error {
            print(error)
        }
        else {
            print("shareCustom() success.")
            if let sharingResult = sharingResult {
                UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
            }
        }
    }
}
else {
    // If Kakao Talk is not installed, it is recommended to share URI via web.
    // You can use custom webView or default browser.
    // Example of sharing URI via web
    if let url = ShareApi.shared.makeCustomUrl(templateId: templateId, templateArgs:["title":"This is title.", "description":"This is description."]) {
        self.safariViewController = SFSafariViewController(url: url)
        self.safariViewController?.modalTransitionStyle = .crossDissolve
        self.safariViewController?.modalPresentationStyle = .overCurrentContext
        self.present(self.safariViewController!, animated: true) {
            print("Web present success")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

let templateId = 12345

ShareApi.shared.rx.shareCustom(templateId:templateId, templateArgs:["title":"This is title.", "description":"This is description."])
    .subscribe(onSuccess: { (sharingResult) in
        print("shareCustom() success.")
        
        UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

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 shareScrap() to receive a SharingResult object. Use the intent of that object to launch an activity and implement sharing the message through Kakao Talk.
   • If Kakao Talk is not installed: Generate a web sharing URL using makeScrapUrl() in WebSharerClient, then implement to open that URL in a default browser or webview.
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 requestUrl 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

let requestUrl = "https://developers.kakao.com"

// Check if Kakao Talk has been installed.
if ShareApi.isKakaoTalkSharingAvailable() {
    // Kakao Talk Share is available.
    ShareApi.shared.shareScrap(requestUrl: requestUrl) {(sharingResult, error) in
        if let error = error {
            print(error)
        }
        else {
            print("shareScrap() success.")
            if let sharingResult = sharingResult {
                UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
            }
        }
    }
}
else {
    // If Kakao Talk is not installed, it is recommended to share URI via web.
    // You can use custom webView or default browser.
    // Example of sharing URI via web
    if let url = ShareApi.shared.makeScrapUrl(requestUrl: requestUrl) {
        self.safariViewController = SFSafariViewController(url: url)
        self.safariViewController?.modalTransitionStyle = .crossDissolve
        self.safariViewController?.modalPresentationStyle = .overCurrentContext
        self.present(self.safariViewController!, animated: true) {
            print("Web present success")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

let requestUrl = "https://developers.kakao.com"

ShareApi.shared.rx.shareScrap(requestUrl: requestUrl)
    .subscribe(onSuccess: { (sharingResult) in
        print("shareScrap() success.")
        
        UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

Sample: Using custom template

let requestUrl = "https://developers.kakao.com"
let templateId = 12345

// Check if Kakao Talk has been installed.
if ShareApi.isKakaoTalkSharingAvailable() {
    // Kakao Talk Share is available.
    ShareApi.shared.shareScrap(requestUrl: requestUrl, templateId: templateId) {(sharingResult, error) in
    if let error = error {
        print(error)
    }
    else {
        print("shareScrap() success.")
        if let sharingResult = sharingResult {
            UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
        }
    }
}
else {
    // If Kakao Talk is not installed, it is recommended to share URI via web.
    // You can use custom webView or default browser.
    // Example of sharing URI via web
    if let url = ShareApi.shared.makeScrapUrl(requestUrl: requestUrl, templateId: templateId) {
        self.safariViewController = SFSafariViewController(url: url)
        self.safariViewController?.modalTransitionStyle = .crossDissolve
        self.safariViewController?.modalPresentationStyle = .overCurrentContext
        self.present(self.safariViewController!, animated: true) {
            print("Web present success")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

let requestUrl = "https://developers.kakao.com"
let templateId = 12345


ShareApi.shared.rx.shareScrap(requestUrl: requestUrl, templateId: templateId)
    .subscribe(onSuccess: { (sharingResult) in
        print("shareScrap() success.")
        
        UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)

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. This function is only available for Kakao Talk Share API, not for Kakao Talk Message API. 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 Prerequisites > Set Kakao Talk Share webhook.
2. Build a server to receive a Kakao Talk Share webhook.
3. Set a custom parameter to pass additional information when requesting the Kakao Talk Share API.
4. Implement a process to handle the webhook delivered to your service server's webhook URL.

When your service server receives a Kakao Talk Share webhook, you can figure out additional information through the predefined custom parameters, such as what content the user has shared. The notification sent to the service server does not include detailed message transmission information, so you need to configure parameters with additional information needed by the service, such as which message's transmission result it is and what information the user shared. Even if you set up a Kakao Talk Share webhook in the app management page, the webhook will not be delivered if there are no custom parameters.

To use the Kakao Talk Share webhook function, you must specify a custom parameter through serverCallbackArgs. Otherwise, you cannot receive Kakao Talk Share webhooks even though you registered a webhook URL for Kakao Talk Share in [App] > [Webhook] > [Kakao Talk Share webhook] on the app management page. When your service server receives a Kakao Talk Share webhook, you can figure out additional information through the predefined custom parameters, such as what content the user has shared.

To pass additional information when requesting the Kakao Talk Share API, declare serverCallbackArgs, and pass keys and values as a Dictionary. You cannot use the system reserved words CHAT_TYPE, HASH_CHAT_ID and TEMPLATE_ID as keys for the serverCallbackArgs. The key is included in the notification with the value defined in the specification of Kakao Talk Share webhook.

Below is an example of setting Kakao Talk Share webhook parameters.

// Template ID
let templateId = 12345;
// Template Arguments
let templateArgs = ["title": "This is the title area.", "description": "This is the description area."]
// Information to receive from server through webhook
let serverCallbackArgs = ["user_id": "abcd", "product_id": "1234"]

// Check if Kakao Talk has been installed.
if ShareApi.isKakaoTalkSharingAvailable() {
    // Kakao Talk Share is available.
    ShareApi.shared.shareCustom(templateId:templateId,
                            templateArgs:templateArgs,
                            serverCallbackArgs: serverCallbackArgs) { (sharingResult, error) in
        if let error = error {
            print(error)
        }
        else {
            print("shareCustom() success.")
            if let sharingResult = sharingResult {
                UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
            }
        }
    }
}
else {
    // If Kakao Talk is not installed, it is recommended to share URI via web.
    // You can use custom webView or default browser.
    // Example of sharing URI via web
    if let url = ShareApi.shared.makeCustomUrl(templateId:templateId,
                                                    templateArgs:templateArgs,
                                                    serverCallbackArgs: serverCallbackArgs) {
        self.safariViewController = SFSafariViewController(url: url)
        self.safariViewController?.modalTransitionStyle = .crossDissolve
        self.safariViewController?.modalPresentationStyle = .overCurrentContext
        self.present(self.safariViewController!, animated: true) {
            print("Succeeded in presenting web.")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

// Template ID
let templateId = 12345;
// Template arguments
let templateArgs = ["title": "This is the title area.", "description": "This is the description area."]
// Information passed from Kakao server.
let serverCallbackArgs = ["user_id": "abcd", "product_id": "1234"]

ShareApi.shared.rx.shareCustom(templateId:templateId,
                            templateArgs:templateArgs,
                            serverCallbackArgs: serverCallbackArgs)
    .subscribe(onSuccess: { (sharingResult) in
        print("shareCustom() success.")
        
        UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
    }, onFailure: {error in
        print(error)
    })
    .disposed(by: disposeBag)
}

If the Kakao Talk Share message is successfully sent, Kakao sends a Kakao Talk Share webhook including the specified parameters to the webhook URL of your service server. For more information on the webhook request, refer to Kakao Talk Share webhook.

Upload image

Basic information

You can attach images to a Kakao Talk message by passing an image URL when configuring a message template or uploading images in the Message Template Tool in advance. To use the image file stored on your device for a message, you must upload the image file to the server first to obtain its URL value.

If it is difficult to obtain the image file URL, you can either upload an image file to the Kakao server or scrape it. You can only upload an image 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.

When the request is successful, you receive the URL information of the uploaded image as a string value. You can use this URL when configuring messages.

You can also scrape information about image files already uploaded to your service server and store them on the Kakao server for use in message transmission. Use the imageScrap() API for image file scraping.

Sample

Upload image

if let image = UIImage(named: "sample1") {
    ShareApi.shared.imageUpload(image:image) { [weak self] (imageUploadResult, error) in
        if let error = error {
            print(error)
        }
        else {
            print("imageUpload() success.")
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

if let image = UIImage(named: "sample1") {
    ShareApi.shared.rx.imageUpload(image:image)
        .subscribe(onSuccess: { (imageUploadResult) in
            print("imageUpload() success.")
            
        }, onFailure: {error in
            print(error)
        })
        .disposed(by: disposeBag)
}

Scrape image

if let url = URL(string:"https://t1.kakaocdn.net/kakaocorp/Service/KakaoTalk/pc/slide/talkpc_theme_01.jpg") {
    ShareApi.shared.imageScrap(imageUrl: url, completion: { [weak self] (imageUploadResult, error) in
        if let error = error {
            print(error)
        }
        else {
            print("imageUpload() success.")
        }
    })
}

// Class member property
let disposeBag = DisposeBag()

if let url = URL(string:"https://t1.kakaocdn.net/kakaocorp/Service/KakaoTalk/pc/slide/talkpc_theme_01.jpg") {
    ShareApi.shared.rx.imageScrap(imageUrl: url)
        .subscribe(onSuccess: { (imageUploadResult) in
            print(String(describing:imageUploadResult))            
        }, onFailure: {error in
            print(error)
        })
        .disposed(by: disposeBag)
}

Advanced: Create a message using constructor

You can also create a message by using a constructor for a template class, as well as configuring a message in JSON format according to message types. With the method using a constructor, you can identify and define components more explicitly. However, you cannot use a template class for each message type directly when requesting to send a message. Instead, you should use it to create the templateObject object to be passed as a parameter (or argument).

let link = Link(webUrl: URL(string:"https://developers.kakao.com"),
                mobileWebUrl: URL(string:"https://developers.kakao.com"))
let appLink = Link(androidExecutionParams: ["key1": "value1", "key2": "value2"],
                    iosExecutionParams: ["key1": "value1", "key2": "value2"])
let button1 = Button(title: "View on Web", link: link)
let button2 = Button(title: "View on App", link: appLink)

let social = Social(likeCount: 286,
                    commentCount: 45,
                    sharedCount: 845)
let content = Content(title: "Strawberry Cheese Cake",
                        imageUrl: URL(string:"https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png")!,
                        description: "#Cake #Strawberry #Sampyeong-dong #Cafe #Vibe #BlindDate",
                        link: link)
let feedTemplate = FeedTemplate(content: content, social: social, buttons: [button1, button2])

//Encode message template
if let feedTemplateJsonData = (try? SdkJSONEncoder.custom.encode(feedTemplate)) {

//Convert the created message template object to a json object.
    if let templateJsonObject = SdkUtils.toJsonObject(feedTemplateJsonData) {
        ShareApi.shared.shareDefault(templateObject:templateJsonObject) {(sharingResult, error) in
            if let error = error {
                errorHandler(error)
            }
            else {
                print("shareDefault(templateObject:templateJsonObject) success.")
                
                //Do something
                guard let sharingResult = sharingResult else { return }
                UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
            }
        }
    }
}

// Class member property
let disposeBag = DisposeBag()

let link = Link(webUrl: URL(string:"https://developers.kakao.com"),
                mobileWebUrl: URL(string:"https://developers.kakao.com"))
let appLink = Link(androidExecutionParams: ["key1": "value1", "key2": "value2"],
                    iosExecutionParams: ["key1": "value1", "key2": "value2"])
let button1 = Button(title: "View on Web", link: link)
let button2 = Button(title: "View on App", link: appLink)

let social = Social(likeCount: 286,
                    commentCount: 45,
                    sharedCount: 845)
let content = Content(title: "Strawberry Cheese Cake",
                        imageUrl: URL(string:"https://mud-kage.kakao.com/dn/Q2iNx/btqgeRgV54P/VLdBs9cvyn8BJXB3o7N8UK/kakaolink40_original.png")!,
                        description: "#Cake #Strawberry #Sampyeong-dong #Cafe #Vibe #BlindDate",
                        link: link)
let feedTemplate = FeedTemplate(content: content, social: social, buttons: [button1, button2])

//Encode message template
if let feedTemplateJsonData = (try? SdkJSONDecoder.custom.encode(feedTemplate)) {

//Convert the created message template object to a json object.
    if let templateJsonObject = SdkUtils.toJsonObject(feedTemplateJsonData) {
        ShareApi.shared.rx.shareDefault(templateObject:templateJsonObject)
            .subscribe(onSuccess: { (sharingResult) in
                print("success.")
                
                //Do something
                UIApplication.shared.open(sharingResult.url, options: [:], completionHandler: nil)
                
            }, onFailure: {error in
                print(error)
            })
            .disposed(by: disposeBag)
    }
}

See more

Message Template Tooloutlink ```