Conversation API KakaoTalk Support

The Conversation API provides support for KakaoTalk through the KakaoTalk channel.

Depending on the context, the KakaoTalk channel is represented as either KAKAOTALK or KAKAOTALKCHAT in API calls and callbacks. This documentation provides information on which designation should be used or expected.

Prerequisites

To start using KakaoTalk through the Conversation API, you must first have a KakaoTalk Business Channel ID configured with KakaoTalk. Then, contact your Sinch account manager to obtain a Sender key.

Channel configuration

The easiest way to configure your Conversation API app for use with the KakaoTalk channel is to reach out to our dedicated online team. They will be able to assist you in setting up your account. Log in to the Sinch Customer Dashboard, navigate to the the Overview page of the Conversation API tab, and look under Support and help section for more details.

Setup KakaoTalk integration using the API

Using the KakaoTalk channel requires a Conversation API app with channel_credentials configured for the KAKAOTALK and KAKAOTALKCHAT. You can configure these credentials directly using the API. The following snippet provides an example of a JSON payload that includes the channel_credentials:

{
  "channel_credentials": [
    {
      "channel": "KAKAOTALK",
      "kakaotalk_credentials": {
        "kakaotalk_plus_friend_id": "{{KAKAOTALK_BUSINESS_CHANNEL_ID}}",
        "kakaotalk_sender_key": "{{SENDER_KEY}}"
      }
    },
    {
      "channel": "KAKAOTALKCHAT",
      "kakaotalkchat_credentials": {
        "kakaotalk_plus_friend_id": "{{KAKAOTALK_BUSINESS_CHANNEL_ID}}"
      }
    }
  ]
}

Replace {{KAKAOTALK_BUSINESS_CHANNEL_ID}} with your KakaoTalk Business Channel ID and {{SENDER_KEY}} with the Sender key you obtained from your Sinch account manager.

In order to receive delivery receipts and messages, you also need to configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. The most important trigger for your conversation application is MESSAGE_DELIVERY, which delivers receipts for business messages.

Sending Messages

You can send different types of KakaoTalk messages using the different message types supported by the Conversation API. This section reviews the KakaoTalk message types supported by the Conversation API, provides examples of the messaging capabilities of the KakaoTalk channel, and illustrates how to send KakaoTalk messages using the Conversation API's message formats.

Types of KakaoTalk messages

When using the KakaoTalk channel, you may send AlimTalk, FriendTalk, or ConsultationTalk messages.

• An AlimTalk message is a template message sent by your business account to an end-user. In order to send an AlimTalk message, you must use a template that has been registered and approved by KakaoTalk. To send these messages, you must designate KAKAOTALK as the channel.
• A FriendTalk message is a message sent by your business account to an end-user that has added your business as a friend. When using FriendTalk, a template is not required; you may use any of the generic message types that can be used with the Conversation API. However, you may only send FriendTalk messages between 8:00 AM and 9:00 PM Korea Standard Time (KST). To send these messages, you must designate KAKAOTALK as the channel.
• Any ConsultationTalk messages are messages sent in a conversation that was initiated by an end-user. Once a ConsultationTalk conversation begins, all messages sent during a limited time-frame are considered ConsultationTalk messages. The ConsultationTalk conversation can also be terminated by the end-user at anytime. ConsultationTalk messages are received and sent under the KAKAOTALKCHAT designation.

Specifying recipients

When you want to send a business-initiated message (that is, AlimTalk or FriendTalk) to a customer on KakaoTalk, you must set the identity of the end-user to the end-user's MSISDN:

{
    "id": "{{APP_ID}}",
    "channel_identities": [
        {
            "channel": "KAKAOTALK",
            "identity": "{{MSISDN}}",
            "app_id": ""
        }
    ],
    "channel_priority": [
        "KAKAOTALK"
    ],
    "display_name": "Unknown",
    "email": "",
    "external_id": "",
    "metadata": "",
    "language": "UNSPECIFIED"
}

However, if you receive a KakaoTalk message response (that is, ConsultationTalk) from the user, a new contact, with a unique identifier, will be created:

{
    "id": "{{APP_ID}}",
    "channel_identities": [
        {
            "channel": "KAKAOTALKCHAT",
            "identity": "{{CHANNEL_UNIQUE_IDENTIFIER}}",
            "app_id": ""
        }
    ],
    "channel_priority": [
        "KAKAOTALKCHAT"
    ],
    "display_name": "Unknown",
    "email": "",
    "external_id": "",
    "metadata": "",
    "language": "UNSPECIFIED"
}

If you want to reply to the user's message (which would also be considered a ConsultationTalk message), you must use the newly created contact's unique identifier when sending the message.

In this case, that would be the contact's {{CHANNEL_UNIQUE_IDENTIFIER}} created in the previous example:

{
    "app_id": "{{APP}}",
     "recipient": {
         "contact_id": "{{CHANNEL_UNIQUE_IDENTIFIER}}"
    },
    "message": {
        "text_message": {
            "text": "Thank you for contacting Sinch!"
        }
    }
}

To create and maintain a full conversation history with this user on the KakaoTalk channel, you need the MSISDN of the user that responded to the AlimTalk or FriendTalk message.

Once you have the MSISDN, you can use it to merge the original contact and the new contact, specifying the KAKAOTALK for the initial contact and KAKAOTALKCHAT for the contact that was created when the user responded.

Template message support

Sending an AlimTalk message requires an approved template.

When sending an AlimTalk message, you need to specify the template id, recipient, and the set of parameters defined in the template for the recipient. Each key in the dictionary corresponds to a property of a template parameter. Sinch provides the ability to send generic or authentication AlimTalk template messages. You can register templates via the KakaoTalk section in the Sinch Customer Dashboard to create channel-specific messages.

Sending a FriendTalk or ConsultationTalk message does not require an approved template. You may, however, use an omni-channel template to send a FriendTalk or ConsultationTalk message. You can use the Template Management API or the Message Composer in the Sinch Customer Dashboard to create omni-channel template messages. To learn more, see Working with templates.

Generic template message

Below is an example of sending a generic template message with two body parameters. The template id is package_template.

Conversation API POST messages:send

{
  "message": {
    "template_message": {
      "channel_template": {
        "KAKAOTALK": {
          "template_id": "package_template",
          "parameters": {
            "package_id": "Value of first parameter",
            "expected_delivery": "Value of second parameter"
          }
        }
      }
    }
  }
}

Authentication template message

Authentication messages are treated differently than generic ones - they're delivered faster.

When sending authentication message you must also add an additional parameter under channel_properties -> KAKAOTALK_AUTHENTICATION with value set to true (which defines it as an authentication message, not a generic one).

Below is an example of sending an authentication template message with one body parameter. The template id is sinch_template_example.

Conversation API POST messages:send

{
  "message": {
    "template_message": {
      "channel_template": {
        "KAKAOTALK": {
          "template_id": "sinch_template_example",
          "parameters": {
            "password": "magical password"
          }
        }
      }
    }
  },
  "channel_properties": {
    "KAKAOTALK_AUTHENTICATION": "true"
  },
}

The rendered message:

Generic message type support

When sending FriendTalk or ConsultationTalk messages, you can use the following generic message types supported by the Conversation API.

Text Messages

KakaoTalk supports text messages natively. The text of the Text message has a maximum length of 1000 characters.

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Messages

The KAKAOTALK and KAKAOTALKCHAT channels support Media messages natively.

When sending Media messages as AlimTalk Template messages or FriendTalk messages on the KAKAOTALK channel, the supported image media types are .png and .jpg.

Media included in the Media message will be rejected by the channel if:

• the width is below 500px, or if the 'width:length' ratio is below 2:1, or above 3:4 or if the image dimension is not equal to [800px * 600px]
• image file format is different than JPG or PNG
• file size is bigger than 500KB or for image with dimension [800px * 600px] is bigger than 2MB

When sending Media messages as ConsultationTalk messages on the KAKAOTALKCHAT channel, the supported image media types are .gif, .png, and .jpg.

Media included in the Media message will be rejected by the channel if:

• file size is larger than 5MB

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Messages

KakaoTalk supports choice messages natively.

The text of the Choice message has a maximum length of 1000 characters.

The title of the choice in the Choice message has a maximum length of 14 characters.

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Messages

KakaoTalk supports Card messages natively.

Media included in the Media message will be rejected by the channel if:

• the width is below 500px, or if the 'width:length' ratio is below 2:1, or above 3:4 or if the image dimension is not equal to [800px * 600px] (so called wide image)
• image file format is different than JPG or PNG
• file size is bigger than 500KB or for image with dimension [800px * 600px] is bigger than 2MB

The concatenated title and descritpion text of the Card message has a maximum length of:

• 1000 characters (if Card message doesn't contain Media message)
• 400 characters (if Card message contains Media message)
• 76 characters (if Card message contains Media message with wide image)

The title of the choice in the Card message has a maximum length of 14 characters.

The Card message can have only one choice in case Media message is a wide image.

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Messages

KakaoTalk doesn't natively support Carousel messages and so they're transcoded and sent as text message by Conversation API.

The Carousel message as text has a maximum length of 1000 characters.

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Messages

KakaoTalk doesn't natively support location messages, and so they're transcoded and sent as text messages by Conversation API.

The Location message as text (including title, label, url) has a maximum length of 1000 characters.

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Receiving Delivery Receipts

Messages sent on KakaoTalk channel can have two statuses: DELIVERED and FAILED. If the status is FAILED, a reason with more information about the failure will be included. Below is an example for DELIVERED receipt - DELIVERED and FAILED differ by the status and reason only. Depending on how the original message was sent, the Conversation API sends delivery receipts to either the KAKAOTALK or KAKAOTALKCHAT channel designation with a POST to the MESSAGE_DELIVERY webhook:

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message_delivery_report": {
    "message_id": "{{message_id}}",
    "conversation_id": "{{conversation_id}}",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "KAKAOTALK",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "contact_id": "{{contact_id}}",
    "metadata": ""
  }
}

Below is an example of FAILED delivery (lack of keyword in authentication message).

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message_delivery_report": {
    "message_id": "{{message_id}}",
    "conversation_id": "{{conversation_id}}",
    "status": "FAILED",
    "channel_identity": {
      "channel": "KAKAOTALK",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "contact_id": "{{contact_id}}",
    "reason": {
      "code": "TEMPLATE_INSUFFICIENT_PARAMETERS",
      "description": "Authentication message not included in Template, when sending an authentication message.The content must contain auth guide ment.",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": ""
  }
}

Below is the example of DELIVERED delivery (a ConsultationTalk message in response to a user message).

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message_delivery_report": {
    "message_id": "{{message_id}}",
    "conversation_id": "{{conversation_id}}",
    "status": "DELIVERED",
    "channel_identity": {
      "channel": "KAKAOTALKCHAT",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "contact_id": "{{contact_id}}",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Receiving Messages

The KakaoTalk channel can receive various types of ConsultationTalk messages. These include text messages, media messages, and choice replies.

All of these are delivered by Conversation API to the KAKAOTALKCHAT channel designation with a POST to the MESSAGE_INBOUND webhook:

Example media message:

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message": {
    "id": "{{message_id}}",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "{{image_url}}",
        "thumbnail_url": ""
      }
    },
    "channel_identity": {
      "channel": "KAKAOTALKCHAT",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "conversation_id": "{{conversation_id}}",
    "contact_id": "{{contact_id}}",
    "metadata": "",
    "accept_time": "{{accept_time}}",
    "sender_id": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Example text message:

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message": {
    "id": "{{message_id}}",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Hello"
      }
    },
    "channel_identity": {
      "channel": "KAKAOTALKCHAT",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "conversation_id": "{{conversation_id}}",
    "contact_id": "{{contact_id}}",
    "metadata": "",
    "accept_time": "{{accept_time}}",
    "sender_id": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Example choice response message:

{
  "app_id": "{{app_id}}",
  "accepted_time": "{{accepted_time}}",
  "event_time": "{{event_time}}",
  "project_id": "{{project_id}}",
  "message": {
    "id": "{{message_id}}",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "{{mt_message_id}}",
        "postback_data": "{{mt_message_id}}_Reply"
      }
    },
    "channel_identity": {
      "channel": "KAKAOTALKCHAT",
      "identity": "{{identity}}",
      "app_id": ""
    },
    "conversation_id": "{{conversation_id}}",
    "contact_id": "{{contact_id}}",
    "metadata": "",
    "accept_time": "{{accept_time}}",
    "sender_id": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}