알림톡 발송 (Gateway) - AllTalk Gateway

const talkData = {
  groupId: 'YOUR_GROUP_ID',
  service: 'YOUR_SENDER_KEY',
  template: 'AT_TEMPLATE_001',
  message: '홍길동님, 테스트 알림톡입니다.\n주문번호: 20260330002',
  numbers: [
    { hp: '01012345678', name: '홍길동' }
  ],
  buttons: [
    {
      type: 'WL',
      name: '바로가기',
      url_pc: 'https://example.com',
      url_mobile: 'https://example.com',
    },
  ],
};

const { data } = await axios.post(
  'https://gateway.alltalk.co.kr/alimTalk',
  talkData,
  { headers: { apikey: 'YOUR_API_KEY', groupid: 'YOUR_GROUP_ID' } },
);
console.log(data.results[0].id); // 결과 조회 시 사용

{
  "success": true,
  "sendGroupId": "0d8398a2-979f-4b26-bdeb-2b4957f47b78",
  "accepted": 1,
  "total": 1,
  "results": [
    {
      "id": "89a3066e-a7f2-4e39-9bdd-b40f766ea658",
      "uid": "dmotj0o7o0ij1c8",
      "mobile": "01012345678",
      "status": "DHN_PENDING",
      "rawStatus": "00"
    }
  ]
}

POST

alimTalk

const talkData = {
  groupId: 'YOUR_GROUP_ID',
  service: 'YOUR_SENDER_KEY',
  template: 'AT_TEMPLATE_001',
  message: '홍길동님, 테스트 알림톡입니다.\n주문번호: 20260330002',
  numbers: [
    { hp: '01012345678', name: '홍길동' }
  ],
  buttons: [
    {
      type: 'WL',
      name: '바로가기',
      url_pc: 'https://example.com',
      url_mobile: 'https://example.com',
    },
  ],
};

const { data } = await axios.post(
  'https://gateway.alltalk.co.kr/alimTalk',
  talkData,
  { headers: { apikey: 'YOUR_API_KEY', groupid: 'YOUR_GROUP_ID' } },
);
console.log(data.results[0].id); // 결과 조회 시 사용

{
  "success": true,
  "sendGroupId": "0d8398a2-979f-4b26-bdeb-2b4957f47b78",
  "accepted": 1,
  "total": 1,
  "results": [
    {
      "id": "89a3066e-a7f2-4e39-9bdd-b40f766ea658",
      "uid": "dmotj0o7o0ij1c8",
      "mobile": "01012345678",
      "status": "DHN_PENDING",
      "rawStatus": "00"
    }
  ]
}

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

Base URL

https://gateway.alltalk.co.kr

Headers

string

required

제공받은 API key

string

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

Body (JSON)

string

required

그룹 코드

string

required

발신프로필 키 (sender key). 운영팀 안내 받은 값

string

required

등록된 템플릿 코드

string

required

등록된 템플릿 본문과 일치하는 메시지. 가변 변수는 호출 측에서 미리 치환하거나 numbers[].VARn으로 매핑 가능합니다.

object[]

required

수신자 배열. 각 항목 구성:

hp (string): 수신자 휴대폰 번호 (필수)
name (string): 수신자 이름. 메시지의 #{이름} 또는 #{name} 자리 치환에 사용
VAR1, VAR2, … (string): 가변 변수 매핑값

string

강조 표기 템플릿인 경우 필수

object[]

템플릿에 등록된 버튼 정보. 명시 시 우선 사용되며, 미명시 시 시스템에서 등록된 버튼을 자동 조회합니다.각 항목 구성:

type (string): WL / AL / BK / MD
name (string): 버튼 표시명
url_pc, url_mobile (string): WL 타입 시 사용
scheme_android, scheme_ios (string): AL 타입 시 사용

boolean

default:"false"

알림톡 실패 시 SMS 대체문자 발송 여부

string

대체문자 본문. alter=true 일 때 사용

string

대체문자 발신번호. alter=true 일 때 사용

string

채널 ID

동작

본 API는 발송 요청을 접수하고 즉시 응답합니다.
응답 본문의 results[].status는 접수 단계 결과입니다 (DHN_PENDING = 정상 접수, FAILED/ERROR = 접수 실패).
실제 카카오톡 발송 결과(OK / FAILED / GIVEUP)는 약 5분 이내 자동 갱신됩니다.
갱신된 최종 결과는 GET /result/:id 로 조회합니다.

차감 정책

접수 성공한 건만 즉시 차감됩니다 (실패는 차감 없음).
최종 결과가 FAILED로 확정되면 접수 시 차감된 금액이 자동 환불됩니다.
접수는 성공했으나 DB 저장에 실패한 경우(status: ERROR) 차감되지 않습니다.

예제

const talkData = {
  groupId: 'YOUR_GROUP_ID',
  service: 'YOUR_SENDER_KEY',
  template: 'AT_TEMPLATE_001',
  message: '홍길동님, 테스트 알림톡입니다.\n주문번호: 20260330002',
  numbers: [
    { hp: '01012345678', name: '홍길동' }
  ],
  buttons: [
    {
      type: 'WL',
      name: '바로가기',
      url_pc: 'https://example.com',
      url_mobile: 'https://example.com',
    },
  ],
};

const { data } = await axios.post(
  'https://gateway.alltalk.co.kr/alimTalk',
  talkData,
  { headers: { apikey: 'YOUR_API_KEY', groupid: 'YOUR_GROUP_ID' } },
);
console.log(data.results[0].id); // 결과 조회 시 사용

{
  "success": true,
  "sendGroupId": "0d8398a2-979f-4b26-bdeb-2b4957f47b78",
  "accepted": 1,
  "total": 1,
  "results": [
    {
      "id": "89a3066e-a7f2-4e39-9bdd-b40f766ea658",
      "uid": "dmotj0o7o0ij1c8",
      "mobile": "01012345678",
      "status": "DHN_PENDING",
      "rawStatus": "00"
    }
  ]
}

응답 필드

필드	설명
`success`	요청 처리 성공 여부
`sendGroupId`	본 발송의 sendGroup 식별자. 일괄 결과 조회 시 사용
`accepted`	정상 접수된 건수
`total`	전체 요청 건수
`results[].id`	수신자별 발송 식별자. 단건 결과 조회 시 이 값 사용
`results[].uid`	발송 메시지 식별자 (20자 이내)
`results[].mobile`	수신자 번호
`results[].status`	접수 단계 결과: `DHN_PENDING` / `FAILED` / `ERROR`
`results[].rawStatus`	게이트웨이 원본 응답 코드
`results[].error`	접수 실패 시 사유

참고

결과는 약 5분 후 갱신되므로, 응답에 포함된 DHN_PENDING을 최종 결과로 판단하지 마세요.
일정 시간이 지나도 결과가 갱신되지 않으면 GIVEUP으로 처리됩니다 (장애 케이스).
가변 변수 치환 규칙은 기본 알림톡 API와 동일합니다.

발신프로필 · 채널 관리 (Gateway)발송 결과 조회 (Gateway)

⌘I

​Base URL

​Headers

​Body (JSON)

​동작

​차감 정책

​예제

​응답 필드

​참고

Base URL

Headers

Body (JSON)

동작

차감 정책

예제

응답 필드

참고