# 카카오 메시지 발송

{% hint style="info" %}
HTTP API는 서버 환경에서만 사용할 수 있습니다.
{% endhint %}

HTTP API 를 사용하여 API 기반 카카오 메시지 캠페인을 발송할 수 있습니다.

SDK 키를 통해 인증을 진행합니다.

* SDK 키를 아래와 같이 HTTP 헤더에 추가해주세요.
* SDK 키는 핵클 대시보드 내 [SDK 연동 정보](https://dashboard.hackle.io/config/sdk-setting)에서 확인하실 수 있습니다.

```http
X-HACKLE-API-KEY: {YOUR_SERVER_SDK_KEY}
```

### Request

{% hint style="warning" %}

* 발송 대상 사용자의 정보는 카카오 메시지 캠페인에 설정된 '발송 대상' 조건에 부합해야 합니다.\
  해당 조건과 부합하지 않는 사용자에게는 카카오 메시지가 발송되지 않습니다.
* 카카오 메시지 발송을 위해서는 userId 별로 전화번호 수집이 필요합니다.\
  [가이드 문서](/crm-marketing/crm-properties/collect-phone-number.md)를 참고해주세요.
  {% endhint %}

```http
POST https://api.hackle.io/v1/kakao-message/trigger/send
```

#### Request Body

| Field       | Type                 | Required | Description     | Restrict              |
| ----------- | -------------------- | -------- | --------------- | --------------------- |
| campaignKey | number               | O        | 카카오 메시지의 캠페인 키  |                       |
| users       | array`<User object>` | O        | 메시지를 수신할 사용자 목록 | **목록의 최대 길이는 50입니다.** |

**User Object**

| Field         | Type   | Required | Description                                                                                                                                          |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| userId        | string | O        | 사용자 ID                                                                                                                                               |
| apiProperties | object | X        | [카카오 메시지 개인화](https://docs.hackle.io/development-guide/http-api/pages/YTKZu3fKk1DP4VJ2gBty#개인화-메시지) 에 사용되는 key-value 쌍 입니다. key(string)-value(string |

#### Example

```shell
curl -i -X POST \
  'https://api.hackle.io/v1/kakao-message/trigger/send' \
  -H 'X-HACKLE-API-KEY: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaignKey": 1,
    "users": [
      {  
        "userId": "eb24b2d8-21a3-4e95-b801-626ba0904e01",
        "apiProperties": {
          "productNumber": "123"
        }
      }
    ]
  }'
```

### Response

API 발송 요청 결과의 응답 값으로 Success Response 또는 Error Response 객체를 반환합니다.

#### Success (200)

{% hint style="info" %}
**카카오 메시지 발송 요청 성공 응답은, 실제로 해당 유저가 카카오 메시지를 받았음 보장하지 않습니다.**

최종 발송 성공에 대한 통계는 대시 보드에서 확인하실 수 있습니다.
{% endhint %}

| Field      | Data Type | Description                           |
| ---------- | --------- | ------------------------------------- |
| dispatchId | string    | API 로 트리거 된 카카올 메시지 요청에 대한 고유한 uuid 값 |
| message    | string    | "success" 라는 내용이 담깁니다.                |

**example**

```json
{
    "dispatchId": "bac3da45-f6e3-44ea-989e-e0fa0ffc9f5c",
    "message": "success"
}
```

#### Error

| Field   | Data Type | Description        |
| ------- | --------- | ------------------ |
| code    | string    | 특정 응답 에러 코드가 내려옵니다 |
| message | string    | 에러에 대한 메시지를 표시합니다  |

**example**

```json
{
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
}
```

**error case**

| Http Status | Code                      | Message                                                    | Description                            |
| ----------- | ------------------------- | ---------------------------------------------------------- | -------------------------------------- |
| 401         | INVALID\_API\_KEY         | “Invalid API key“                                          | 헤더에 유효하지 않은 API KEY 를 넣는 경우            |
| 401         | API\_KEY\_NOT\_FOUND      | “API key not found”                                        | 헤더에 API KEY 를 넣지 않은 경우                 |
| 400         | EXCEED\_USER\_MAX\_LENGTH | “Max input length exceeded“                                | 한번에 보낼 수 있는 최대 대상 유저 수를 넘겨서 요청한 경우     |
| 400         | CAMPAIGN\_NOT\_FOUND      | “Could not find kakao message campaign with the given key“ | 주어진 캠페인 키와 일치하는 API 기반 캠페인이 존재하지 않는 경우 |
| 400         | EMPTY\_IDENTIFIER         | “At least one identifier should be given“                  | 카카오 발송 대상 유저 정보에 userId 가 존재하지 않는 경우   |


---

# 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://docs.hackle.io/development-guide/http-api/api-kakao-message-send.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.