> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.developer.alltalk.co.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# 발신프로필 · 채널 관리 (Gateway)

> 발신프로필(senderKey)을 발급하고 발송 채널을 등록·관리합니다.

<Warning>
  본 엔드포인트는 [Gateway 채널](/introduction) 사용 자격이 부여된 그룹 전용입니다.
  일반 고객사는 [기본 발송 API](https://developer.alltalk.co.kr/api-reference/messaging/alimtalk)를 사용해 주세요.
</Warning>

## Base URL

```
https://gateway.alltalk.co.kr
```

## Headers

<ParamField header="apikey" type="string" required>
  제공받은 API key
</ParamField>

<ParamField header="groupid" type="string" required>
  그룹 코드. body의 `groupId`로 대체 가능합니다.
</ParamField>

<Note>
  권한은 자동으로 자기 그룹 한정으로 제한됩니다. 다른 그룹의 자원에는 접근할 수 없습니다.
</Note>

## 사용 흐름 (최초 가입 시)

채널을 만들려면 발신프로필(`senderKey`)이 필요합니다. `senderKey`가 없으면 아래 1\~3으로 **발급**한 뒤 4의 `POST /channel`로 채널을 등록하세요. 이미 `senderKey`가 있으면 바로 4로 진행합니다.

<Steps>
  <Step title="발급용 인증토큰 요청">
    `GET /channel/sender/token` → 채널 관리자 휴대폰으로 인증토큰(SMS) 발송
  </Step>

  <Step title="발신프로필 발급">
    `POST /channel/sender` → 인증토큰 + 휴대폰번호 + 프로필 정보 → `senderKey` 발급
  </Step>

  <Step title="발신프로필 조회 (선택)">
    `GET /channel/sender` → 검수/활성 상태 확인
  </Step>

  <Step title="채널 등록">
    `POST /channel` → 발급받은 `senderKey`를 채널에 연결
  </Step>
</Steps>

***

## 1. 발신프로필 발급

### GET /channel/sender/token — 발급용 인증토큰 요청

발신프로필 발급 전, 채널 관리자 본인확인용 인증토큰을 휴대폰으로 발송합니다. (Rate limit: 분당 10회)

<ParamField query="phoneNumber" type="string" required>
  채널 관리자 휴대폰번호 (인증토큰 수신)
</ParamField>

<ParamField query="yellowId" type="string" required>
  카카오톡 **채널 고유 ID**.

  ⚠️ `@아이디` 형식이 **아닙니다** — 채널 URL `http://pf.kakao.com/_aBcDeFg` 의 **`_aBcDeFg`** 부분(맨 앞 `_` 포함)을 사용하세요.
  누락 시 채널을 식별하지 못해 인증 SMS가 발송되지 않습니다(`508`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://gateway.alltalk.co.kr/channel/sender/token \
    -H "apikey: YOUR_API_KEY" \
    -H "groupid: YOUR_GROUP_ID" \
    --data-urlencode "phoneNumber=01012345678" \
    --data-urlencode "yellowId=_aBcDeFg"
  ```
</RequestExample>

발송된 인증토큰은 다음 단계(`POST /channel/sender`)의 `token` 값으로 사용합니다.

### POST /channel/sender — 발신프로필 발급

인증토큰 + 휴대폰번호 + 프로필 정보로 발신프로필(`senderKey`)을 발급합니다. **발급만 수행**하며, 발급된 `senderKey`로 `POST /channel`을 호출해 채널을 등록해야 발송에 사용됩니다.

<ParamField body="token" type="string" required>
  `GET /channel/sender/token`에서 수신한 인증토큰
</ParamField>

<ParamField body="phoneNumber" type="string" required>
  채널 관리자 휴대폰번호
</ParamField>

<ParamField body="yellowId" type="string" required>
  카카오톡 **채널 고유 ID**. ⚠️ `@아이디` 아님 — 채널 URL `http://pf.kakao.com/_aBcDeFg` 의 **`_aBcDeFg`** 부분
</ParamField>

<ParamField body="categoryCode" type="string">
  발신프로필 카테고리 코드 등 등록 정보 (운영팀 안내 스펙). 카테고리 목록은 `GET /category`로 조회합니다.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const { data } = await axios.post(
    'https://gateway.alltalk.co.kr/channel/sender',
    {
      token: '123456',
      phoneNumber: '01012345678',
      yellowId: '_aBcDeFg',
      categoryCode: '001001001',
    },
    { headers: { apikey: 'YOUR_API_KEY', groupid: 'YOUR_GROUP_ID' } },
  );
  console.log(data.senderKey);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "senderKey": "78521411466302c0070b38c6a0080aa2c0381d1c",
    "status": "..."
  }
  ```
</ResponseExample>

<Warning>
  발급 후 발송 가능 상태까지는 카카오 검수가 필요할 수 있습니다(1\~3 영업일).
  발급된 `senderKey`는 `POST /channel`로 채널에 연결해야 발송에 사용됩니다.
</Warning>

### GET /channel/sender — 발신프로필 조회

발신프로필 상태(활성/검수 등)를 조회합니다.

<ParamField query="senderKey" type="string" required>
  조회할 발신프로필 키
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://gateway.alltalk.co.kr/channel/sender \
    -H "apikey: YOUR_API_KEY" \
    -H "groupid: YOUR_GROUP_ID" \
    --data-urlencode "senderKey=78521411466302c0070b38c6a0080aa2c0381d1c"
  ```
</RequestExample>

***

## 2. 채널 관리

### POST /channel — 채널 등록

발급받은 `senderKey`를 연결해 발송 채널을 등록합니다.

<ParamField body="name" type="string" required>
  채널 이름
</ParamField>

<ParamField body="senderKey" type="string" required>
  사전 발급된 발신프로필 키
</ParamField>

<ParamField body="kakaoSearchId" type="string">
  카카오톡 채널 검색용 ID
</ParamField>

<ParamField body="callbackNo" type="string">
  대체문자 발신번호
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const { data } = await axios.post(
    'https://gateway.alltalk.co.kr/channel',
    {
      name: '내 비즈채널',
      kakaoSearchId: '_xxxxx',
      callbackNo: '01012345678',
      senderKey: '78521411466302c0070b38c6a0080aa2c0381d1c',
    },
    { headers: { apikey: 'YOUR_API_KEY', groupid: 'YOUR_GROUP_ID' } },
  );
  console.log(data.id);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "ch_abc123",
    "groupId": "G1000000027",
    "name": "내 비즈채널",
    "senderKey": "78521411466302...",
    "callbackNo": "01012345678",
    "status": "ENABLE",
    "channelStatus": "ACTIVE",
    "createdAt": 1714989600000,
    "updatedAt": 1714989600000
  }
  ```
</ResponseExample>

### GET /channel — 채널 목록

<ParamField query="status" type="string">
  필터 (`ENABLE` / `DELETED`)
</ParamField>

<ParamField query="limit" type="number" default="50">
  최대 200
</ParamField>

<ParamField query="lastKey" type="string">
  페이지네이션 토큰
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "items": [ { "id": "ch_abc123", "name": "내 비즈채널", "...": "..." } ],
    "count": 12,
    "lastKey": "eyJpZCI6e..."
  }
  ```
</ResponseExample>

### GET /channel/:id — 단건 조회

채널 단건을 조회합니다. 다른 그룹의 채널은 `404`를 반환합니다.

### PUT /channel/:id — 수정

`name` / `callbackNo` / `senderKey` 중 **최소 하나**는 필요합니다. 빈 바디는 `400`.

<RequestExample>
  ```json Body theme={null}
  {
    "name": "변경된 이름",
    "callbackNo": "01098765432",
    "senderKey": "..."
  }
  ```
</RequestExample>

### DELETE /channel/:id — 삭제

`status='DELETED'`로 soft delete 처리됩니다. 발송 이력 정합성을 위해 hard delete는 지원하지 않습니다.

***

## 참고

* 채널을 등록한 뒤에는 [알림톡 템플릿 등록·검수](/introduction)를 거쳐 [`POST /alimTalk`](/alimtalk)으로 발송합니다.
* 카테고리 코드는 `GET /category`로 조회할 수 있습니다.
* 인증 정보(`apikey`, `groupId`)는 운영팀 안내 메일을 참고하세요.