# Friend Talk

{% hint style="warning" %}
To use the service, you need to **register the sender number** in **\[Service Console / Sender Number]**.
{% endhint %}

{% hint style="warning" %}
To use the service, you need to perform a **new registration** in **\[Service Console / Template Management]**.
{% endhint %}

{% hint style="warning" %}
Message sending is restricted between 20:50 and 08:00 (KST).
{% endhint %}

{% hint style="info" %}
To include images in KakaoTalk Friend Talk or KakaoTalk Wide, it is essential to use the **image upload API** beforehand.
{% endhint %}

{% hint style="info" %}
The default encoding for all KakaoTalk Friend Talk APIs is UTF-8.
{% endhint %}

{% hint style="success" %}
This API can deliver the message sending results through a [WebHook](/service/kakao-message/message-sending-result-webhook.md).
{% endhint %}

## Friend Talk API

### Path variable

{% hint style="warning" %}
Please refer to the following information to ensure that path variables (enclosed in curly braces {}) within each URI are not omitted when making calls.
{% endhint %}

<table><thead><tr><th width="192">code</th><th>description</th></tr></thead><tbody><tr><td>service_id</td><td><p>service id</p><ul><li>ft-text : friend talk text</li><li>ft-image : friend talk image</li><li>ft-wide : friend talk wide</li><li>ft-wide-item-list: friend talk wide item list</li><li>ft-carousel-feed: friend talk carousel feed</li></ul></td></tr></tbody></table>

## Kakao Friend Talk API

<mark style="color:green;">`POST`</mark> `https://9tpssuhbpx.apigw.ntruss.com/{service_id}/v2/send`

#### Headers

| Name                                            | Type   | Description                    |
| ----------------------------------------------- | ------ | ------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | userID;secret\_key             |
| Content-Type<mark style="color:red;">\*</mark>  | string | application/json;charset=utf-8 |

#### Request Body

| Name                                               | Type   | Description                                                                                                                                                 |
| -------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| msg\_data<mark style="color:red;">\*</mark>        | array  | Detailed data of messages (up to 10 records)                                                                                                                |
| sender\_key<mark style="color:red;">\*</mark>      | string | <p>Kakao BizMessage sender profile key. <br><strong>(Registration is required in \[Service Console / Sender Profile Registration].)</strong></p>            |
| header                                             | string | <p>Wide item list header (32 byte)</p><p>(Requied when use Wide item list)</p>                                                                              |
| msg<mark style="color:red;">\*</mark>              | string | <p>Transmitted message<br>(up to 1000 characters including spaces)</p>                                                                                      |
| receiver\_number<mark style="color:red;">\*</mark> | string | Recipient's mobile phone number                                                                                                                             |
| sender\_number<mark style="color:red;">\*</mark>   | string | Sender's phone number                                                                                                                                       |
| msg\_key<mark style="color:red;">\*</mark>         | string | Unique key for the message managed by the user (automatically assigned if null or blank)                                                                    |
| echo\_to\_webhook                                  | string | The string to be received along with the webhook from API PLEX by the user (up to 256 bytes)                                                                |
| attachment                                         | object | <p>Button or image data <br>(refer to <a href="#attachement-details">attachment details</a>)</p>                                                            |
| ad\_flag                                           | string | <p>Display mandatory information for promotional messages <br>(default value: Y)</p>                                                                        |
| carousel                                           | object | <p>carousel data</p><p>(refer to <a href="#carousel-details">carousel detailes</a>)</p>                                                                     |
| failback\_data                                     | object | [failback](/service/kakao-message/failback.md) data                                                                                                         |
| secret\_key                                        | string | failback service's sub\_account's secret\_key (required when use failback)                                                                                  |
| api\_unique\_id                                    | string | <p>failback service's unique id (required when use failback)</p><p>(see <a href="/pages/hMQ4qMBObS8s2sC3zo8Z">failback</a>)</p>                             |
|                                                    | String | <p>payload for failback service request body.</p><p>fill fileds failback service required.</p><p>(refer to <a href="#request-body-example">example</a>)</p> |

{% tabs %}
{% tab title="200: OK Response returned successfully" %}

{% endtab %}
{% endtabs %}

### Attachement details

<table data-full-width="true"><thead><tr><th width="204">key</th><th width="128">type</th><th width="116" align="center">required</th><th>description</th></tr></thead><tbody><tr><td>button</td><td>array</td><td align="center">N</td><td>Button attribute data (up to 5)</td></tr><tr><td>    name</td><td>string</td><td align="center">Y</td><td>Button title (112 byte)</td></tr><tr><td>    type</td><td>string</td><td align="center">Y</td><td>Button type (Refer to the <a href="#button-type">button type</a>)</td></tr><tr><td>    url_pc</td><td>string</td><td align="center">N</td><td>URL to move to when the button is clicked in a PC environment</td></tr><tr><td>    url_mobile</td><td>string</td><td align="center">N</td><td>URL to move to when the button is clicked in a mobile environment</td></tr><tr><td>    scheme_android</td><td>string</td><td align="center">N</td><td>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</td></tr><tr><td>    scheme_ios</td><td>string</td><td align="center">N</td><td>Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment</td></tr><tr><td>    chat_extra</td><td>string</td><td align="center">N</td><td>Metadata to be transferred when switching to a bot (50 bytes)</td></tr><tr><td>    chat_event</td><td>string</td><td align="center">N</td><td>Bot event name to be linked when switching to a bot (50 bytes)</td></tr><tr><td>image</td><td>object</td><td align="center">N</td><td>Used for images in KakaoTalk Friend Talk or KakaoTalk Wide</td></tr><tr><td>    img_url</td><td>string</td><td align="center">N</td><td>Image path URL</td></tr><tr><td>    img_link</td><td>string</td><td align="center">N</td><td>URL to go to when click image<br>if not set, use kakao talk inner image viewer</td></tr><tr><td>item</td><td>object</td><td align="center">N</td><td>friend talk wide item list information</td></tr><tr><td>    list</td><td>array</td><td align="center">N</td><td>wide item list (minimum: 3, maximum: 4)</td></tr><tr><td>        title</td><td>string</td><td align="center">Y</td><td>The first item is limited to 25 characters, and the 2nd to 4th items are limited to 30 characters each</td></tr><tr><td>        img_url</td><td>string</td><td align="center">Y</td><td>image URL</td></tr><tr><td>        scheme_android</td><td>string</td><td align="center">N</td><td>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</td></tr><tr><td>        scheme_ios</td><td>string</td><td align="center">N</td><td>Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment</td></tr><tr><td>        url_mobile</td><td>string</td><td align="center">Y</td><td>URL to move to when the button is clicked in a mobile environment</td></tr><tr><td>        url_pc</td><td>string</td><td align="center">N</td><td>URL to move to when the button is clicked in a PC environment</td></tr></tbody></table>

### Carousel details

<table data-full-width="true"><thead><tr><th width="246">key</th><th width="128">type</th><th width="70" align="center">required</th><th>description</th></tr></thead><tbody><tr><td>list</td><td>array</td><td align="center"></td><td>carousel list (minimum: 2, maximum: 6)</td></tr><tr><td>    header</td><td>string</td><td align="center">Y</td><td>carousel item title (20 byte)</td></tr><tr><td>    message</td><td>string</td><td align="center">Y</td><td>carousel item message (180 byte)</td></tr><tr><td>    attachment</td><td>object</td><td align="center"></td><td></td></tr><tr><td>        button</td><td>array</td><td align="center"></td><td></td></tr><tr><td>            name</td><td>string</td><td align="center">Y</td><td>button title (8 byte)</td></tr><tr><td>            type</td><td>string</td><td align="center">Y</td><td>button type (refer to <a href="#button-type">button type</a>)</td></tr><tr><td>            scheme_android</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</td></tr><tr><td>            scheme_ios</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment</td></tr><tr><td>            url_mobile</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a mobile environment</td></tr><tr><td>            url_pc</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a PC environment</td></tr><tr><td>        image</td><td>object</td><td align="center"></td><td>carousel thumnail image</td></tr><tr><td>            img_url</td><td>string</td><td align="center">Y</td><td>carousel thumnail image <strong>URL</strong></td></tr><tr><td>            img_link</td><td>string</td><td align="center"></td><td>carousel thumnail image link URL</td></tr><tr><td>        coupon</td><td>object</td><td align="center"></td><td>coupon at the bottom of the carousel</td></tr><tr><td>            title</td><td>string</td><td align="center"></td><td>coupon name</td></tr><tr><td>            description</td><td>string</td><td align="center"></td><td>coupon description (12자)</td></tr><tr><td>            scheme_android</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</td></tr><tr><td>            scheme_ios</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment</td></tr><tr><td>            url_mobile</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a mobile environment</td></tr><tr><td>            url_pc</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a PC environment</td></tr><tr><td>tail</td><td>object</td><td align="center"></td><td>"more" button information</td></tr><tr><td>    scheme_android</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</td></tr><tr><td>    scheme_ios</td><td>string</td><td align="center"></td><td>Custom scheme of the application to be executed when the button is clicked in a mobile IOS environment</td></tr><tr><td>    url_mobile</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a mobile environment</td></tr><tr><td>    url_pc</td><td>string</td><td align="center"></td><td>URL to move to when the button is clicked in a PC environment</td></tr></tbody></table>

### Button Type

<table data-full-width="true"><thead><tr><th width="142">button type</th><th width="157">attribute</th><th width="86">type</th><th width="127" align="center">required</th><th>description</th></tr></thead><tbody><tr><td>WL</td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>[Web link]<br>Web URL to move to when clicked for direct connection, depending on the PC/mobile environment</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">N</td><td>Same as above</td></tr><tr><td>AL</td><td>scheme_android</td><td>string</td><td align="center">Y</td><td><p></p><p>[App link] Either <code>scheme_ios</code>, <code>scheme_android</code>, or <code>url_mobile</code> is required</p><ul><li>Custom scheme of the application to be executed when the button is clicked in a mobile Android environment</li><li>Custom scheme for mobile iOS</li><li>URL to move to when the button is clicked in a mobile environment</li></ul></td></tr><tr><td></td><td>scheme_ios</td><td>string</td><td align="center">Y</td><td>Same as above</td></tr><tr><td></td><td>url_mobile</td><td>string</td><td align="center">Y</td><td>Same as above</td></tr><tr><td></td><td>url_pc</td><td>string</td><td align="center">-</td><td>URL to move to when the button is clicked in a PC environment</td></tr><tr><td>BK</td><td>-</td><td>-</td><td align="center">-</td><td>Send the corresponding button text</td></tr><tr><td>MD</td><td>-</td><td>-</td><td align="center">-</td><td>Send both the corresponding button text and the message body</td></tr><tr><td>BC</td><td>-</td><td>-</td><td align="center">-</td><td>Available only for KakaoTalk channels using Consultation Talk</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>Metadata to be transferred when switching to Consultation Talk</td></tr><tr><td>BT</td><td>-</td><td>-</td><td align="center">-</td><td>Available only for KakaoTalk channels using Kakao | Open Builder chatbots</td></tr><tr><td></td><td>chat_extra</td><td>string</td><td align="center">N</td><td>Metadata to be transferred when switching to a bot</td></tr><tr><td></td><td>chat_event</td><td>string</td><td align="center">N</td><td>Bot event name to be linked when switching to a bot</td></tr><tr><td>BF</td><td>biz_form_key</td><td>string</td><td align="center">Y</td><td>BizForm key obtained through BizForm upload</td></tr></tbody></table>

### Length limit for button names by message sending type

<table><thead><tr><th width="422">Sending Type</th><th>limitation(Maximum)</th></tr></thead><tbody><tr><td>friend talk text(ft-text)</td><td>14 letters</td></tr><tr><td>friend talk image(ft-image)</td><td>14 letters</td></tr><tr><td>friend talk wide(ft-wide)</td><td>8 letters</td></tr><tr><td>friend talk wide item list(ft-wide-item-list)</td><td>8 letters</td></tr><tr><td>friend talk carousel feed(ft-carousel-feed)</td><td>8 letters</td></tr></tbody></table>

### Request Body Example

```json
{
    "msg_data": [
        {
            "msg_key": "user_key_1",
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "ft-text test",
            "ad_flag": "N",
            "sender_key": "user_sender_key_001",
            "echo_to_webhook": "echo test",
            "failback_data": {
                "api_unique_id": "sms-standard",
                "secret_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                "sender_number": "010xxxxxxxx",
                "receiver_number": "010xxxxxxxx",
                "origin_cid": "0123456789",
                "msg": "failback 본문입니다."
            }
        },
        {
            "sender_number": "010xxxxxxxx",
            "receiver_number": "010xxxxxxxx",
            "msg": "ft-text and button test",
            "ad_flag": "N",
            "attachment": {
                "button": [
                    {
                        "name": "button1",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    },
                    {
                        "name": "button2",
                        "type": "WL",
                        "url_pc": "https://www.apiplex.net",
                        "url_mobile": "https://m.apiplex.net"
                    }
                ]
            },
            "sender_key": “user_sender_key_001”
        }
    ]
}
```

### Response Body

{% hint style="info" %}
Even if the response HTTP status returns as 200, it does not necessarily mean the successful acceptance of all requests. (You can check the acceptance status of each transmission by the response code field.)
{% endhint %}

<table data-full-width="true"><thead><tr><th width="107">key</th><th width="111"> </th><th width="131">type</th><th>description</th></tr></thead><tbody><tr><td>results</td><td></td><td>array</td><td>Received message data</td></tr><tr><td> </td><td>msg_key</td><td>string</td><td>Unique key for the message</td></tr><tr><td> </td><td>code</td><td>string</td><td>Acceptance result code (Refer to <a href="#api-plex-response-code">API PLEX response codes</a>)</td></tr><tr><td> </td><td>desc</td><td>string</td><td>Detailed acceptance result code</td></tr></tbody></table>

#### **Success**

```json
{
    "results": [
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "user_key_1"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "11520199-f289-4681-b0e3-354393a4b041"
        }
    ]
}
```

#### Invalid request or error

```json
{
    "code": "C400_2",
    "name": "Invalid Parameter",
    "description": "사용자 인증 실패"
}
```

#### Invalid request within the list

```json
{
    "results": [
        {
            "code": "G141",
            "desc": "수신번호 예외",
            "msg_key": "user_key_101"
        },
        {
            "code": "C100",
            "desc": "success",
            "msg_key": "22c35870-d4a5-46e3-9d64-17f42c1e3248"
        }
    ]
}
```

### API PLEX Response Code

<table><thead><tr><th width="118.33333333333331">code</th><th>title</th><th>description</th></tr></thead><tbody><tr><td>C100</td><td>Success</td><td> </td></tr><tr><td>C400_1</td><td>Invalid data type</td><td>Refer to the description in the response body</td></tr><tr><td>C400_2</td><td>Invalid request parameter</td><td>Refer to the description in the response body</td></tr><tr><td>C400_3</td><td>Missing required parameters</td><td>Refer to the description in the response body</td></tr><tr><td>C404_1</td><td>Unable to find the data</td><td>Refer to the description in the response body</td></tr><tr><td>C500_1</td><td>Internal server error</td><td>Refer to the description in the response body</td></tr><tr><td>G110</td><td>API UNIQUE ID exception (Invalid URL)</td><td> </td></tr><tr><td>G140</td><td>Sender number exception</td><td> </td></tr><tr><td>G141</td><td>Recipient number exception</td><td> </td></tr><tr><td>G142</td><td>Invalid <code>echo_to_webhook</code> value</td><td>Exceed 256 byte or type error</td></tr><tr><td>G150</td><td>Insufficient credit</td><td> </td></tr><tr><td>G160</td><td>Exceeded the maximum number of transmissions per session</td><td> </td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.apiplex.net/service/kakao-message/kakao-friend-talk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.