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

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

본 엔드포인트는 Gateway 채널 사용 자격이 부여된 그룹 전용입니다. 일반 고객사는 기본 발송 API를 사용해 주세요.

Base URL

https://gateway.alltalk.co.kr

Headers

apikey · string · required

제공받은 API key

groupid · string · required

그룹 코드. body의 groupId로 대체 가능합니다.

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

사용 흐름 (최초 가입 시)

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

1. 발급용 인증토큰 요청

   GET /channel/sender/token → 채널 관리자 휴대폰으로 인증토큰(SMS) 발송

2. 발신프로필 발급

   POST /channel/sender → 인증토큰 + 휴대폰번호 + 프로필 정보 → senderKey 발급

3. 발신프로필 조회 (선택)

   GET /channel/sender → 검수/활성 상태 확인

4. 채널 등록

   POST /channel → 발급받은 senderKey를 채널에 연결

---

1. 발신프로필 발급

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

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

phoneNumber · string · required

채널 관리자 휴대폰번호 (인증토큰 수신)

yellowId · string · required

카카오톡 채널 고유 ID.

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

cURL

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"

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

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

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

token · string · required

GET /channel/sender/token에서 수신한 인증토큰

phoneNumber · string · required

채널 관리자 휴대폰번호

yellowId · string · required

카카오톡 채널 고유 ID. ⚠️ @아이디 아님 — 채널 URL http://pf.kakao.com/_aBcDeFg 의 _aBcDeFg 부분

categoryCode · string

발신프로필 카테고리 코드 등 등록 정보 (운영팀 안내 스펙). 카테고리 목록은 GET /category로 조회합니다.

Node.js

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);

200

{
  "senderKey": "78521411466302c0070b38c6a0080aa2c0381d1c",
  "status": "..."
}

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

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

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

senderKey · string · required

조회할 발신프로필 키

cURL

curl -G https://gateway.alltalk.co.kr/channel/sender \
  -H "apikey: YOUR_API_KEY" \
  -H "groupid: YOUR_GROUP_ID" \
  --data-urlencode "senderKey=78521411466302c0070b38c6a0080aa2c0381d1c"

---

2. 채널 관리

POST /channel — 채널 등록

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

name · string · required

채널 이름

senderKey · string · required

사전 발급된 발신프로필 키

kakaoSearchId · string

카카오톡 채널 검색용 ID

callbackNo · string

대체문자 발신번호

Node.js

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);

201

{
  "id": "ch_abc123",
  "groupId": "G1000000027",
  "name": "내 비즈채널",
  "senderKey": "78521411466302...",
  "callbackNo": "01012345678",
  "status": "ENABLE",
  "channelStatus": "ACTIVE",
  "createdAt": 1714989600000,
  "updatedAt": 1714989600000
}

GET /channel — 채널 목록

status · string

필터 (ENABLE / DELETED)

limit · number · default: "50"

최대 200

lastKey · string

페이지네이션 토큰

200

{
  "items": [ { "id": "ch_abc123", "name": "내 비즈채널", "...": "..." } ],
  "count": 12,
  "lastKey": "eyJpZCI6e..."
}

GET /channel/:id — 단건 조회

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

PUT /channel/:id — 수정

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

Body

{
  "name": "변경된 이름",
  "callbackNo": "01098765432",
  "senderKey": "..."
}

DELETE /channel/:id — 삭제

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

---

참고

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