메시지 연동의 시작,
talkfly API.

첫 연결, 세 단계로 시작하세요.

외부 서비스의 백엔드에서 호출합니다. 처음에는 연결 상태와 템플릿 목록을 조회해 준비 여부를 확인하세요.

1. 1

   계정과 애플리케이션 키 준비

   talkfly 운영 담당자를 통해 계정·애플리케이션·접근 키를 발급받습니다. 공개 회원가입·키 발급 API는 제공하지 않습니다. 최초 조회에는 templates:read 권한이 필요합니다.

2. 2

   연결 상태 확인

   GET /v1/messaging/connection을 호출합니다. sendable: false이면 blockedReason을 확인하세요. HTTP 200만으로 발송 준비 완료를 뜻하지 않습니다.

3. 3

   승인된 템플릿 조회

   GET /v1/messaging/templates에서 id, version, price, variables를 가져옵니다. 빈 배열이면 사용 가능한 승인 템플릿이 없는 상태입니다.

용도에 맞는 키를 사용하세요.

모든 업무 API는 Authorization: Bearer <credential> 헤더로 인증합니다. 요청의 계정과 애플리케이션은 키로 결정됩니다.

관리 API에는 applications:manage, wallet:read 권한을 용도에 맞게 부여합니다. 발송 API에는 엔드포인트별 최소 권한을 부여하세요. 같은 계정의 애플리케이션 키라도 관리 API는 호출할 수 없습니다.

애플리케이션 권한은 templates:read, deliveries:write, deliveries:read, deliveries:cancel, phone:read, phone:write입니다. 기존 sendable은 설정 상태입니다. 발송 권한·잔액·한도까지 확인한 준비 상태는 canEnqueue와 checks를 사용하세요. /health와 /health/ready는 인증이 필요 없습니다.

관리형 앱(managed: true)은 관리 키로 lease 갱신 API를 만료 전에 주기적으로 호출해야 합니다. 유효 시간은 갱신 시점부터 60초입니다. 만료·앱 비활성화·키 폐기는 아직 공급자에 전달되지 않은 대기 발송도 실패시킬 수 있습니다.

채널과 템플릿을 연결하세요.

계정 관리 키로 검색용 ID와 템플릿 내용을 설정할 수 있습니다. 기본 경로는 /v1/management/applications/{application_id}입니다.

채널 설정

POST /channels에 name과 searchId 또는 channelUrl을 전달합니다. 검색 ID는 이미 보유한 카카오 채널의 ID입니다. 카카오 채널을 새로 만드는 API가 아닙니다.

발신키는 이후 PATCH /channels/{channel_id}로 추가할 수 있습니다. 발신키 자체는 응답에 포함되지 않고 senderKeyConfigured로 설정 여부만 확인합니다. 승인·정지된 채널은 수정할 수 없습니다.

템플릿 초안과 검토 요청

POST /templates로 초안을 만들고 PUT /templates/{template_id}로 전체 내용을 교체합니다. POST /templates/{template_id}/submit은 내부 운영 검토를 요청합니다. 반려된 초안을 수정하면 다시 draft 상태가 됩니다.

운영자가 공급자 승인 원문·버튼·발신 프로필을 확인한 후 코드와 단가를 확정합니다. 고객 요청으로 승인 상태·단가를 지정할 수 없습니다. 승인 내용 변경은 새 등록과 검토가 필요합니다.

톡플라이의 건당 청구 단가(price)는 부가세(VAT) 별도입니다. 발송 요청의 expectedPrice에는 조회한 단가를 그대로 입력합니다. 예를 들어 price가 20원이면 expectedPrice도 20입니다.

전용 채널은 앱당 최대 10개, 템플릿 등록은 상태와 무관하게 최대 100개입니다. 채널 생성에는 requestId가 없어 같은 요청을 반복하면 중복 등록될 수 있습니다. 응답 유실 시 채널 목록을 먼저 확인하세요. 채널 삭제·승인, 템플릿 삭제·재활성화 API는 제공하지 않으며 운영 담당자 확인이 필요합니다.

발송용 목록의 channelId: null은 공용 채널입니다. 목록에 보여도 공용 채널 사용 승인이 필요합니다. sendable은 사용 가능한 템플릿이 하나라도 있는지 확인하므로 선택한 템플릿의 발송 가능 여부까지 보장하지 않습니다.

접수와 전달 결과를 구분하세요.

POST /v1/messaging/send는 승인된 템플릿과 수신 동의 정보를 받아 발송을 접수합니다. HTTP 202는 접수·금액 예약 완료입니다. 최종 전달 완료가 아닙니다.

응답이 끊겼다면 먼저 조회하세요.

GET /v1/messaging/requests/{request_id}로 기존 요청을 확인합니다. 동일한 requestId와 동일한 본문으로 재요청하면 기존 발송을 반환합니다. 내용이 다르면 IDEMPOTENCY_CONFLICT입니다. 불명확한 결과를 새 요청 ID로 자동 재발송하지 마세요.

발송 내역은 GET /deliveries로 최신순으로 조회합니다. 개별 발송 상태는 GET /deliveries/{delivery_id}로 주기적으로 조회합니다. queued 상태에서만 취소할 수 있으며, 템플릿 사용 중지는 이미 접수된 발송을 취소하지 않습니다.

requestId는 같은 애플리케이션의 알림톡과 SMS 발송이 공유합니다. 기능마다 새로운 UUID를 생성하세요. 재요청도 계정·앱 활성 상태와 관리형 lease를 검사합니다. 조회의 404만으로 앞선 요청 실패를 확정하지 말고, 재요청할 때는 원래 ID와 본문을 유지하세요.

일일 한도는 자정에 초기화되지 않습니다. 최근 24시간의 알림톡·SMS 접수 건수를 합산하며 실패·취소된 건도 포함합니다. canEnqueue는 현재 권한·사용 가능 잔액·한도를 함께 검사하고, 막힌 이유를 enqueueBlockedReason으로 제공합니다. 실제 접수는 변동된 상태를 다시 검사합니다.

실패를 예측 가능한 흐름으로.

일반 오류는 {"error":{"code":"ERROR_CODE"}} 형태입니다. 아래 기준으로 입력 수정, 상태 조회, 운영 확인을 분리하세요.

엔드포인트별 오류 코드는 각 API 상세에 있습니다. 요청 본문은 정의되지 않은 필드를 거절하며, 422 응답은 입력값을 노출하지 않는 {"error":{"code":"VALIDATION_ERROR"}}입니다. OpenAPI에도 실제 형식과 일치하는 ApiError를 제공합니다. detail 배열은 반환하지 않습니다. 클라이언트는 HTTP 상태와 error.code를 기준으로 처리하세요. 처리되지 않은 5xx·호스팅 프록시 오류는 JSON을 보장하지 않습니다.

필요한 기능을 단계적으로 연결하세요.

SMS 인증

GET /v1/messaging/phone/config로 사용 가능 여부와 가격을 확인한 후 인증 요청을 생성합니다. subject는 서비스가 관리하는 사용자 UUID이며, 자신의 로그인 세션과 서버에서 연결해야 합니다. 인증번호는 5분간 유효하고 재요청 간격은 60초입니다. 검증 API 자체가 사용자 로그인 세션을 발급하지는 않습니다.

유효 시간은 실제 SMS 도착이 아닌 접수 시점부터 5분입니다. 같은 subject는 최근 24시간 5회, 같은 전화번호는 전체 서비스에서 최근 24시간 10회까지이며 앱 한도도 적용됩니다. 오답은 5회까지 누적되고 이후 정답도 거절됩니다. 새 인증 요청은 같은 subject의 최근 미인증 요청을 무효화합니다. 성공 이력 조회의 verified: true는 현재 로그인이나 현재 전화번호 소유를 보장하지 않으며 자동 만료되지 않습니다.

업체별 발송 잔액

톡플라이 운영자가 업체별 잔액을 지정합니다. 서비스는 GET /v1/management/wallet로 자기 계정의 전체 잔액과 발송에 사용할 수 있는 금액(available)을 조회합니다.