Conversation API KakaoTalk Support

Conversation API provides support for KakaoTalk channel. To start using KakaoTalk through Conversation API you need to first have KakaoTalk Business Channel ID configured with KakaoTalk then contact your Sinch account manager to obtain a Sender key.

If you are not familiar with KakaoTalk, we highly recommend to read our articles on Sinch Community first before you continue How can I get started using KakaoTalk?

Channel Configuration

The easiest way to configure your Conversation API app with KakaoTalk support is to use the Sinch Customer Dashboard. Just select your app and click "SET UP CHANNEL" beside the KakaoTalk channel.

Setup KakaoTalk integration using the API

Sending a KakaoTalk message requires a Conversation API app with channel_credentials for KAKAOTALK channel. Example app is given in the following snippet:

Copy
Copied
{
  "channel_credentials": [
    {
      "channel": "KAKAOTALK",
      "kakaotalk_credentials": {
        "kakaotalk_plus_friend_id": "{{KAKAOTALK_BUSINESS_CHANNEL_ID}}",
        "kakaotalk_sender_key": "{{KAKAOTALK_SENDER_KEY}}"
      }
    }
  ]
}

You need to replace {{KAKAOTALK_BUSINESS_CHANNEL_ID}} with your KakaoTalk Business Channel ID and {{KAKAOTALK_SENDER_KEY}} with the Sender Key.

Don't forget that for receiving delivery receipts you also need to configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. The most important triggers for your conversation application is:

  • MESSAGE_DELIVERY - delivery receipts for business messages

Rich Message Support

Conversation API supports rich template messages for KakaoTalk API.

Sending Messages

This section provides examples of messaging capabilities of KakaoTalk channel, and how to utilize them using Conversation API generic message format.

Note

Before sending Template messages, which is called AlimTalk, a template must be registered and approved by KakaoTalk.

Note

Text, Media, Choice, Card, Carousel and Location messages are only sent between 8:00 AM and 9:00 PM Korea Standard Time (KST). Messages sent outside that time are rejected. Before sending those messages the receiver must subscribe to your channel.

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

Kakaotalk supports Media messages natively.

Note

Media messages on Kakaotalk only support .png and .jpg image media types.

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

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.

Note

Card messages on Kakaotalk only support png and jpg image media types.

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.

Template messages

Sending a message requires an approved template. Sinch will register template on your behalf when you setup this channel on the dashboard. Contact your Sinch account manager for more information. When sending a 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 template messages.

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

Copy
Copied
{
  "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.

Warning

Authentication message must contain one of the keywords in the message body (template after replacement):

  1. auth
  2. password
  3. verif
  4. にんしょう
  5. 認証
  6. 비밀번호
  7. 인증

Otherwise, the message can't be delivered as an authentication message.

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

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

The rendered message:

Channel Template Message

Explicit Channel messages

If you need to send a message in the native channel format instead of using generic Conversation API types, you can send an explicit channel message. For example, you may want to send a message with more than three buttons, which is not supported in the generic Conversation API types because the maximum limit is set to three. Using explicit_channel_message you can send a message with more than three buttons.

Below is an example of sending an explicit_channel_message with four buttons.

Conversation API POST messages:send

Copy
Copied
    "message": {
        "explicit_channel_message": {
        "KAKAOTALK":"{\"recipientList\": [{\"content\": \"Check out our new products\",\"buttons\": [{\"ordering\": 1,\"type\": \"WL\",\"name\": \"Ski\",\"linkMo\": \"{{link_product_1}}\",\"linkPc\": \"{{link_product_1}}\"},{\"ordering\": 2,\"type\": \"WL\",\"name\": \"Snowboard\",\"linkMo\": \"{{link_product_2}}\",\"linkPc\": \"{{link_product_2}}\"},{\"ordering\": 3,\"type\": \"WL\",\"name\": \"Skates\",\"linkMo\": \"{{link_product_3}}\",\"linkPc\": \"{{link_product_3}}\"},{\"ordering\": 4,\"type\": \"WL\",\"name\": \"Clothes\",\"linkMo\": \"{{link_product_4}}\",\"linkPc\": \"{{link_product_4}}\"}]}]}"
        }
    }

The rendered message:

Explicit Channel Message

Receiving Delivery Receipts

Messages sent on KakaoTalk channel can have two statuses: DELIVERED and FAILED. If the status is FAILED the reason will include more information about the failure. Below is an example for DELIVERED receipt - DELIVERED and FAILED differ by the status and reason only. Conversation API POST to MESSAGE_DELIVERY webhook:

Copy
Copied
{
  "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).

Copy
Copied
{
  "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": ""
  }
}

Support

KakaoTalk channel is currently open to selected customers on the Sinch Customer Dashboard. To request access, send an email to kakaotalk@sinch.com. For beta support, send an email to ConvAPIKakaoTalkbeta@sinch.com.

Was this page helpful?