This document describes how to integrate the Kakao Talk messaging API into your service with the Kakao SDK for iOS (hereinafter referred to as 'iOS SDK').
Tag | Description |
---|---|
Login required | The API marked with this tag requires Kakao Login. You must implement the Kakao Login function first, and then call the corresponding API by using the access token issued when a user logs in. |
Consent required | To use the API marked with this tag, you must enable the 'Send message in KakaoTalk' scope. In addition, a user must also consent to the scope. Otherwise, an error occurs. |
To use the iOS SDK, you must register the iOS platform in advance. Go to [My Application] > [Platform] and register the iOS platform by specifying the Bundle ID.
KakaoSDKAuth
(Authentication and token management module), KakaoSDKUser
(Kakao Login module) and KakaoSDKTalk
(Kakao Talk module) in the Podfile by referring to Install SDK.import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKTalk
import KakaoSDKAuth
import RxKakaoSDKAuth
import KakaoSDKUser
import RxKakaoSDKUser
import KakaoSDKTalk
import RxKakaoSDKTalk
According to your service's purpose and requirements, you need to decide which API to use first by considering their characteristics and difference.
Step 1. Select a type of Messaging APIThere are two types of messaging APIs: Kakao Talk sharing API and Kakao Talk messaging API. You need to understand the differences between the two messaging APIs completely by referring to Concepts, and decide which API to use to implement the function to send a message.
Decide which message template to use by referring to Message template > Types.
You can configure a message according to the default template in JSON format or create a custom template in person for your service. Refer to Message configuration method for more details.
Note that the Kakao Talk messaging APIs are categorized according to the message targets:
To send a Kakao Talk message to friends, 1. Get permission. Before permission is granted to your app, you can only retrieve the list of the team members. 2. Enable the 'Send message in KakaoTalk' scope in [My Application] > [Kakao Login] > [Consent items]. A user must also consent to the scope. To see more about the conditions for providing friend information, refer to Usage policy.
According to the desired message type, the required components of the message and the method to call are different. Refer to Message template components and samples.
Message type | Configuration method | Target | Method |
---|---|---|---|
Feed, List, Location, Commerce, Text, Calendar | Default template | Me (MyChatroom) | sendDefaultMemo() |
Feed, List, Location, Commerce, Text, Calendar | Default template | Friends | sendDefaultMessage() |
Feed, List, Commerce | Custom template | Me (MyChatroom) | sendCustomMemo() |
Feed, List, Commerce | Custom template | Friends | sendCustomMessage() |
Scrap | Default template | Me (MyChatroom) | sendScrapMemo() |
Scrap | Default template | Friends | sendScrapMessage() |
Scrap | Custom template | Me (MyChatroom) | sendScrapMemo() |
Scrap | Custom template | Friends | sendScrapMessage() |
To make your app launch when a user clicks a button in the Kakao Talk message, you need to set LSApplicationQueriesSchemes
to "kakaolink" in the Configure build settings step. Refer to Kakao Talk Sharing: iOS > Set Custom URL Scheme.
The method of configuring a message to use the Kakao Talk messaging API is the same as the Kakao Talk sharing API. Refer to Kakao Talk Sharing: iOS > Configure a message.
This API enables you to configure a message as an object type according to the default template type to use.
After creating the templatable
object in JSON format by referring to Configure a message, pass the object by calling SdkJSONDecoder.custom.decode()
when calling the Kakao Talk messaging API.
To send a message to friends, obtain the receiving users' uuid
s through the Friends picker or the Retrieving list of friends API, and then pass the uuid
s as the receiverUuids
parameter. You can send a message to up to five friends at once.
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.
If the request is failed, it returns MessageFailureInfo
that contains the failure result. Find out the cause of the failure using receiverUuids
, code
, and msg
in MessageFailureInfo
by referring to REST API Reference.
Name | Type | Description | Required |
---|---|---|---|
templatable | Templatable |
Object of the message template to be sent. Use one of the following templates: FeedTemplate ListTemplate LocationTemplate CommerceTemplate TextTemplate CalendarTemplate You must create an object of the class for the desired template by referring to Kakao Talk Sharing: iOS > Configure a message. |
O |
// For 'templatable', refer to the 'Configure a message' guide.
if let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) {
TalkApi.shared.sendDefaultMemo(templatable: templatable) {(error) in
if let error = error {
print(error)
}
else {
print("success.")
}
}
}
// Class member property
let disposeBag = DisposeBag()
// For 'templatable', refer to the 'Configure a message' guide.
if let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) {
TalkApi.shared.rx.sendDefaultMemo(templatable:templatable)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onCompleted:{
print("success.")
}, onError: {error in
print(error)
})
.disposed(by: disposeBag)
}
Name | Type | Description | Required |
---|---|---|---|
receiverUuids | [String] |
uuid obtained through the Friends picker or the Retrieving list of friends API. Up to five uuids are allowed. |
O |
templatable | Templatable |
Object of the message template to be sent. Use one of the following templates: FeedTemplate ListTemplate LocationTemplate CommerceTemplate TextTemplate CalendarTemplate You must create an object of the class for the desired template by referring to Kakao Talk Sharing: iOS > Configure a message. |
O |
// For 'templatable', refer to the 'Configure a message' guide.
if let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) {
// Retrieve a list of friends.
TalkApi.shared.friends {(friends, error) in
if let error = error {
print(error)
} else {
print("friends() success.")
guard let friends = friends else {
print(error)
return
}
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.sendDefaultMessage(templatable: templatable, receiverUuids: friendUuids) { (messageSendResult, error) in
if let error = error {
print(error)
} else {
print("sendDefaultMessage() success.")
//Do something
_ = messageSendResult
}
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
// For 'templatable', refer to the 'Configure a message' guide.
if let templatable = try? SdkJSONDecoder.custom.decode(FeedTemplate.self, from: feedTemplateJsonStringData) {
// Retrieve a list of friends.
TalkApi.shared.rx.friends()
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess: { (friends) in
print("friends() success.")
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.rx.sendDefaultMessage(templatable:templatable, receiverUuids:friendUuids)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess:{ (messageSendResult) in
print("sendDefaultMessage() success.")
//Do something
_ = messageSendResult
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
}
Unlike the Sending message with default template, you can customize a template in [Tools] > [Message Template Builder] to send a message.
Set templateId
to the template ID of the custom template registered in [Message Template Builder]. If you use user arguments for some components when you configure a custom message to input variable information, you must also pass key and value pairs as the value of templateArgs
. Otherwise, the defined argument is displayed to users as raw data, such as ${key}
.
To send a message to friends, obtain the receiving users' uuid
s through the Friends picker or the Retrieving list of friends API, and then pass the uuid
s as the receiverUuids
parameter. You can send a message to up to five friends at once.
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.
If the request is failed, it returns MessageFailureInfo
that contains the failure result. Find out the cause of the failure using receiverUuids
, code
, and msg
in MessageFailureInfo
by referring to REST API Reference.
Name | Type | Description | Required |
---|---|---|---|
templateId | Int64 |
Template ID of the custom template registered in [Tools] > [Message Template Builder]. Refer to Message template builder. |
O |
templateArgs | [String:String]? |
If the specified template contains a user argument, use this parameter to pass key-value pairs. You cannot overwrite the scrap result. |
X |
let templateId : Int64 = 12345
TalkApi.shared.sendCustomMemo(templateId: templateId, templateArgs: ["msg":"메세지 파라미터"]) {(error) in
if let error = error {
print(error)
}
else {
print("success.")
}
}
// Class member property
let disposeBag = DisposeBag()
let templateId : Int64 = 12345
TalkApi.shared.rx.sendCustomMemo(templateId: templateId, templateArgs: ["msg":"메세지 파라미터"])
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onCompleted:{
print("success.")
}, onError: {error in
print(error)
})
.disposed(by: disposeBag)
Name | Type | Description | Required |
---|---|---|---|
receiverUuids | [String] |
uuid obtained through the Friends picker or the Retrieving list of friends API. Up to five uuids are allowed. |
O |
templateId | Int64 |
Template ID of the custom template registered in [Tools] > [Message Template Builder]. Used when you want to use a custom message registered in the [Tools] > [Message Template Builder] by passing the template ID of your custom message. |
O |
templateArgs | [String:String]? |
If the specified template contains a user argument, use this parameter to pass key-value pairs. You cannot overwrite the scrap result. |
X |
let templateId : Int64 = 12345
// Retrieve a list of friends.
TalkApi.shared.friends {(friends, error) in
if let error = error {
print(error)
} else {
print("friends() success.")
guard let friends = friends else {
print(error)
return
}
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.sendCustomMessage(templateId:templateId, templateArgs:["title":"This is title.", "description":"This is description."], receiverUuids:friendUuids) { (messageSendResult, error) in
if let error = error {
print(error)
} else {
print("sendCustomMessage() success.")
//Do something
_ = messageSendResult
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
let templateId : Int64 = 12345
// Retrieve a list of friends.
TalkApi.shared.rx.friends()
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess: { (friends) in
print("friends() success.")
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.rx.sendCustomMessage(templateId:templateId, templateArgs:["title":"This is title.", "description":"This is description."], receiverUuids:friendUuids)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess:{ (messageSendResult) in
print("sendCustomMessage() success.")
//Do something
_ = messageSendResult
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
This API scraps a web page, and then configures a message based on the scraped web page information to send a message. Thus, when you request to send a scrap message, you must pass requestUrl
, a web page to be scraped. Make sure that you have registered the domain of the web page to be scraped as a site domain in [My Application] > [Platform] > [Web] in advance.
To send a message to friends, obtain the receiving users' uuid
s through the Friends picker or the Retrieving list of friends API, and then pass the uuid
s as the receiverUuids
parameter. You can send a message to up to five friends at once.
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.
If the request is failed, it returns MessageFailureInfo
that contains the failure result. Find out the cause of the failure using receiverUuids
, code
, and msg
in MessageFailureInfo
by referring to REST API Reference.
Name | Type | Description | Required |
---|---|---|---|
requestUrl | String |
Web page URL to be scraped. | O |
let requestUrl = "https://developers.kakao.com"
TalkApi.shared.sendScrapMemo(requestUrl: requestUrl) {(error) in
if let error = error {
print(error)
}
else {
print("success.")
}
}
// Class member property
let disposeBag = DisposeBag()
let requestUrl = "https://developers.kakao.com"
TalkApi.shared.rx.sendScrapMemo(requestUrl: requestUrl)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onCompleted:{
print("success.")
}, onError: {error in
print(error)
})
.disposed(by: disposeBag)
Name | Type | Description | Required |
---|---|---|---|
receiverUuids | [String] |
uuid obtained through the Friends picker or the Retrieving list of friends API. Up to five uuids are allowed. |
O |
requestUrl | String |
Web page URL to be scraped. | O |
let requestUrl = "https://developers.kakao.com"
let templateId : Int64 = 12345
// Retrieve a list of friends.
TalkApi.shared.friends {(friends, error) in
if let error = error {
print(error)
} else {
print("friends() success.")
guard let friends = friends else {
print(error)
return
}
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.sendScrapMessage(requestUrl:requestUrl, receiverUuids:friendUuids) { (messageSendResult, error) in
if let error = error {
print(error)
}
else {
print("sendScrapMessage() success.")
//Do something
_ = messageSendResult
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
let requestUrl = "https://developers.kakao.com"
TalkApi.shared.rx.friends()
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess: { (friends) in
print("friends() success.")
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
TalkApi.shared.rx.sendScrapMessage(requestUrl:requestUrl, receiverUuids:friendUuids)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess:{ (messageSendResult) in
print("sendScrapMessage() success.")
//Do something
_ = messageSendResult
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
This API scraps a web page, and then configures a message based on the scraped web page information to send a message. Unlike the Sending scrap message with default template, you can use a custom template registered in [Tools] > [Message Template Builder] when requesting to send a scrap message.
When you request to send a scrap message, you must pass requestUrl
, a web page to be scraped. Make sure that you have registered the domain of the web page to be scraped as a site domain in [My Application] > [Platform] > [Web] in advance.
Also, you must set templateId
to the template ID of the custom template registered in [Message Template Builder]. If you use user arguments for some components when you configure a custom message to input variable information, you must also pass key and value pairs as the value of templateArgs
. Otherwise, the defined argument is displayed to users as raw data, such as ${key}
.
To send a message to friends, obtain the receiving users' uuid
s through the Friends picker or the Retrieving list of friends API, and then pass the uuid
s as the receiverUuids
parameter. You can send a message to up to five friends at once.
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.
If the request is failed, it returns MessageFailureInfo
that contains the failure result. Find out the cause of the failure using receiverUuids
, code
, and msg
in MessageFailureInfo
by referring to REST API Reference.
Name | Type | Description | Required |
---|---|---|---|
requestUrl | String |
Web page URL to be scraped. Its domain must match the domain registered on the Kakao Developers. |
O |
templateId | Int64 |
Used when you want to send a scrap message with the template registered in [Tools] > [Message Template Builder]. Specify the ID of the template to apply. When you use this parameter, the scraped content is applied in the template with the specified templateId . |
O |
templateArgs | [String:String]? |
If you specify templateId and the specified template contains other user arguments besides the default argument keys, pass the user arguments using this parameter in key:value format.You cannot overwrite the scrap result. |
X |
let requestUrl = "https://developers.kakao.com"
let templateId : Int64 = 12345
TalkApi.shared.sendScrapMemo(requestUrl: requestUrl, templateId: templateId, templateArgs:["title":"This is title.", "description":"This is description."]) {(error) in
if let error = error {
print(error)
}
else {
print("success.")
}
}
// Class member property
let disposeBag = DisposeBag()
let requestUrl = "https://developers.kakao.com"
let templateId : Int64 = 12345
TalkApi.shared.rx.sendScrapMemo(requestUrl: requestUrl, templateId: templateId, templateArgs:["title":"This is title.", "description":"This is description."])
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe (onCompleted:{
print("success.")
}, onError: {error in
print(error)
})
.disposed(by: disposeBag)
Name | Type | Description | Required |
---|---|---|---|
receiverUuids | [String] |
uuid obtained through the Friends picker or the Retrieving list of friends API. Up to five uuids are allowed. |
O |
requestUrl | String |
Web page URL to be scraped. Its domain must match the domain registered on the Kakao Developers. |
O |
templateId | Int64 |
Used when you want to send a scrap message with the template registered in [Tools] > [Message Template Builder]. Specify the ID of the template to apply. When you use this parameter, the scraped content is applied in the template with the specified templateId . |
O |
templateArgs | [String:String]? |
If you specify templateId and the specified template contains other user arguments besides the default argument keys, pass the user arguments using this parameter in key:value format.You cannot overwrite the scrap result. |
X |
let requestUrl = "https://developers.kakao.com"
let templateId : Int64 = 12345
// Retrieve a list of friends.
TalkApi.shared.friends {(friends, error) in
if let error = error {
print(error)
} else {
print("friends() success.")
guard let friends = friends else {
print(error)
return
}
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
// Send a Kakao Talk message.
TalkApi.shared.sendScrapMessage(requestUrl:requestUrl, templateId:templateId, receiverUuids:friendUuids) { (messageSendResult, error) in
if let error = error {
print(error)
}
else {
print("sendScrapMessage() success.")
//Do something
_ = messageSendResult
}
}
}
}
// Class member property
let disposeBag = DisposeBag()
let requestUrl = "https://developers.kakao.com"
let templateId : Int64 = 12345
TalkApi.shared.rx.friends()
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess: { (friends) in
print("friends() success.")
//Implement a window to select friends.
...
//uuids of the friends selected in the window.
let friendUuids = selectedIds as! [String]
TalkApi.shared.rx.sendScrapMessage(requestUrl:requestUrl, templateId:templateId, receiverUuids:friendUuids)
.retry(when: Auth.shared.rx.incrementalAuthorizationRequired())
.subscribe(onSuccess:{ (messageSendResult) in
print("sendScrapMessage() success.")
//Do something
_ = messageSendResult
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
}, onFailure: {error in
print(error)
})
.disposed(by: disposeBag)
You can attach images to a message by passing an image URL when configuring a message template or by uploading images in the Message template builder in advance.
If you add an image through an image URL, you need to call the imageUpload()
method defined in ShareApi
. Thus, you must add the Kakao Talk sharing module in advance. Refer to Kakao Talk Sharing: iOS > Upload image.
To see how to use the Messaging APIs using the Legacy Kakao SDK for iOS, see Message guide for Legacy iOS SDK.
It is highly recommended to migrate to the new version of iOS SDK as soon as possible because the Legacy version may not be supported anymore.