문자 API 연동,
코드 몇 줄이면 끝납니다
회원가입만 하면 API 키가 발급됩니다. 별도 신청이나 심사를 기다릴 필요 없이 그 자리에서 연동을 시작하세요. 문자(SMS·LMS·MMS)와 카카오 알림톡, 브랜드메시지, RCS를 같은 키 하나로 호출해 문자 자동 발송을 붙입니다.
제공 중인 발송 API
| 채널 | 엔드포인트 (POST) | 특징 |
|---|---|---|
| 문자 (SMS · LMS · MMS) | /v1/messages/text/send | messageType 으로 유형 구분 |
| 카카오 알림톡 — 템플릿 | /v1/messages/kakao/alimtalk/template-send | templateCode + parameters |
| 카카오 알림톡 — 전문 | /v1/messages/kakao/alimtalk/send | content 에 본문 직접 작성 |
| 카카오 브랜드메시지 | /v1/messages/kakao/brandmessage/send | targetingType 으로 친구·비친구 |
| RCS | /v1/messages/rcs/send | 브랜드 등록 후 사용 |
| 공통 인증 | X-HACKLE-API-KEY 헤더 | 응답은 messageKey 하나 |
| 중복 방지 | X-IDEMPOTENCY-KEY 헤더 | 10분 내 같은 키는 409 |
전체 스펙은 간편발송 API 문서를 참고해주세요
세 단계면 API 연동이 끝납니다
문자 발송 API 요청과 응답
가장 많이 쓰는 엔드포인트입니다. 나머지 채널도 형태가 같아 하나만 붙여 두면 확장이 쉽습니다.
요청 헤더
| 헤더 | 설명 | 필수 |
|---|---|---|
| X-HACKLE-API-KEY | 발급받은 API 키 | 필수 |
| Content-Type | application/json | 필수 |
| X-IDEMPOTENCY-KEY | 중복 발송을 막는 멱등키. 10분 내 같은 키의 재요청은 409 로 거절됩니다 | 권장 |
메시지 종류
| messageType | 본문 · 제목 | 첨부파일 |
|---|---|---|
| SMS | 최대 90바이트 · 제목 사용 안 함 | 불가 |
| LMS | 최대 2,000바이트 · 제목 필수(40바이트) | 불가 |
| MMS | 최대 2,000바이트 · 제목 선택(40바이트) | 필수 1~3개 |
요청
curl -X POST "https://message-api.hackle.io/v1/messages/text/send" \
-H "X-HACKLE-API-KEY: {발급받은 키}" \
-H "X-IDEMPOTENCY-KEY: order-20260813-0001" \
-H "Content-Type: application/json" \
-d '{
"messageType": "SMS",
"sender": "07012345678",
"recipient": "01012345678",
"body": "인증번호는 [382947] 입니다."
}'응답
// 200 OK
{
"messageKey": "01HZ8K3M9P2Q…"
}
// 실패하면 코드와 사유가 함께 옵니다
{
"code": "A101",
"message": "Invalid API key"
}응답으로 받은 messageKey 로 전송 결과를 조회하거나 웹훅으로 받아볼 수 있습니다
붙이기 전에 확인할 것
아래가 준비되지 않으면 호출은 되더라도 발송이 거절됩니다.
API 키
X-HACKLE-API-KEY를 발급받았는지. 서버에서만 쓰고 클라이언트에 노출하지 않습니다.
발신 정보와 캐시
발신번호와 카카오 발신 프로필 등록이 끝났는지. 선불제라 캐시 잔액도 있어야 합니다.
광고 규정
광고성 메시지라면 (광고) 표기와 080 수신거부 번호, 발송 가능 시간을 지켜야 합니다.
이런 것까지 API로 됩니다
따로 구현할 필요 없이 요청 필드나 헤더 하나로 처리됩니다. 그룹 묶기·개인화 변수·이미지 첨부·발송 결과 웹훅도 같은 방식입니다.
중복 발송 차단
X-IDEMPOTENCY-KEY 를 붙이면 같은 요청이 두 번 나가도 한 번만 처리됩니다
실패 시 문자로 대체
fallback 객체 하나로 못 닿은 건을 문자로 이어 보냅니다
대량 발송 한도 안내
X-RateLimit-Remaining 으로 남은 횟수, Retry-After 로 대기 시간을 알려줍니다
코드 없이 보내야 한다면
대시보드에서 파일을 올려 보내는 방법도 있습니다. 개발 없이 바로 발송할 수 있습니다.
자주 묻는 질문
API를 쓰려면 따로 신청해야 하나요?
아닙니다. 회원가입하면 워크스페이스 전용 키가 바로 발급됩니다. 대시보드 왼쪽 메뉴의 [API 발송]에서 복사해 쓰면 됩니다. 연동 비용이나 월 이용료도 없습니다.
채널마다 API를 따로 붙여야 하나요?
아닙니다. 문자와 카카오 알림톡, 브랜드메시지, RCS 모두 같은 API 키와 같은 요청 형태를 씁니다. 엔드포인트 경로만 채널별로 다르므로, 한 채널을 붙여 두면 경로만 바꿔 그대로 확장할 수 있습니다.
같은 요청이 두 번 나가면 어떻게 되나요?
요청 헤더에 X-IDEMPOTENCY-KEY 를 넣으면 10분 안에 같은 키로 온 요청은 409 응답으로 거절되어 중복 발송이 나가지 않습니다. 헤더를 생략하면 매번 새 요청으로 처리되니, 주문번호처럼 건마다 고유한 키를 붙여 두세요.
호출 횟수에 제한이 있나요?
워크스페이스 단위로 요청 수가 제한되고, 한도를 넘으면 429 응답이 돌아옵니다. 응답의 X-RateLimit-Remaining 헤더로 남은 횟수를 확인할 수 있고, 초과했다면 Retry-After 헤더에 적힌 시간만큼 기다렸다가 다시 호출하면 됩니다.
MMS나 알림톡 이미지는 어떻게 넣나요?
파일 업로드 API에 이미지를 먼저 올리면 fileKey 가 돌아오고, 발송 요청에 그 키를 넣으면 됩니다. MMS 는 JPG 이미지를 최대 3개까지, 한 장에 300KB 이하로 첨부할 수 있습니다.
발송 결과는 어떻게 확인하나요?
응답으로 받은 messageKey 가 발송 건의 식별자입니다. 대시보드의 전송 결과 조회에서 건별 결과와 실패 사유를 확인할 수 있고, 발송 결과 웹훅을 등록하면 결과를 서버로 직접 받아볼 수도 있습니다.
특정 IP에서만 호출하게 막을 수 있나요?
네. 접속 허용 IP 를 등록하면 등록된 IP 에서만 API 를 호출할 수 있습니다. 단일 IP 와 CIDR 표기를 모두 지원하니, 고정 IP 를 쓰는 서버라면 그 주소만 열어 두는 것이 안전합니다.
카카오 발송이 실패하면 문자로 바꿔 보낼 수 있나요?
네. 요청에 fallback 객체를 넣어 두면 카카오로 닿지 못한 건이 문자로 이어서 발송됩니다. 알림톡을 받지 못하는 고객에게도 같은 내용이 문자로 전달됩니다.