자동화 초안 API 레퍼런스

메시지 자동화(캔버스) 초안을 만들고 고치고 검증합니다. 흐름을 채울 재료도 조회합니다 (10개 엔드포인트)

참고인증·애드온·권한
모든 Service API 요청에는 X-API-KEY 헤더를 포함해야 합니다. 메시징 애드온이 있어야 하고, API 키를 만든 사용자에게 자동화 권한이 있어야 합니다 (조회·검증은 자동화 권한 중 하나, 만들기는 messaging_automations.create, 고치기는 create 또는 edit). 공통 규칙은 API 개요를 참고하세요.
중요이 API 는 자동화를 켜지 않습니다
저장한 자동화는 항상 초안(DRAFT)이라 발송이 일어나지 않습니다. 켜진 자동화는 이 API 로 고칠 수 없습니다. 자동화를 켜는 것은 콘솔(자동화 캔버스 또는 목록)에서 사람이 합니다. 켜기 전에 응답의 consoleUrl(콘솔 캔버스)에서 문구와 대상을 확인하세요. 켜면 이후 발송이 자동으로 나가고, 문자·카카오 채널은 이때 발송 자격과 추가 인증을 확인합니다.
개념흐름(flow)
흐름은 {"nodes":[...], "edges":[...], "meta":{...}} 형태의 JSON 객체로, 콘솔 캔버스가 저장하는 것과 같습니다. 노드 종류는 trigger(정확히 1개), wait, condition, split, send, end, note 입니다. 연결은 {"from","to","outputIndex"} 이고 출력 하나에 연결 하나만 둡니다(조건은 0=참·1=거짓, 분기는 0=A·1=B). 노드별 필드는 MCP 도구 get_automation_schema 가 돌려주는 설명과 같습니다(MCP 연동 가이드). 노드 id 는 흐름 안에서 겹치면 안 됩니다. data.uid(노드의 변하지 않는 식별자 — 대기 중 실행의 재개 위치와 노드별 통계에 쓰입니다)는 고칠 때 그대로 두세요. 빠지면 고치기 전 흐름의 같은 노드 값을 잇거나 새로 붙입니다. 노드 위치(x·y)를 생략하면 트리거부터 단계별로 자리를 잡아 줍니다. 흐름이 이 조직에서 찾을 수 없는 앱·주소록·세그먼트·템플릿·카카오 발신 프로필을 가리키면 저장하지 않습니다. 스케줄(SCHEDULE) 흐름은 트리거 바로 다음에 send 1개만 둘 수 있고, 대상은 meta.targetGroupIds(여러 개) 또는 meta.targetSegmentIds(1개) 중 하나입니다 — 회차마다 캠페인 하나로 나갑니다.

GET /api/v1/service/messaging/automations

캔버스 자동화 목록을 최근 수정 순으로 조회합니다. 흐름 본문은 싣지 않습니다.

Query Parameters

파라미터타입필수설명
statusStringDRAFT · ACTIVE · PAUSED · ARCHIVED
sizeInteger최대 개수 (기본: 20, 최대: 50)

Response

automations[] 의 각 항목은 아래와 같고, timeZone(조직 시간대)이 함께 옵니다.

필드타입설명
idLong자동화 ID
nameString이름
statusString상태
triggerModeStringEVENT · FREQUENCY · SCHEDULE
triggerEventNameString트리거 이벤트 (정기 발송이면 null)
appIdsArray트리거 앱 ID
updatedAtString마지막 수정 시각 (조직 시간대, ISO 8601)
consoleUrlString콘솔 캔버스 경로 — 여기서 확인하고 켭니다

GET /api/v1/service/messaging/automations/{id}

자동화 하나를 조회합니다. 목록 항목의 필드에 아래가 더해집니다. 다른 조직의 ID 는 404 입니다.

필드타입설명
flowObject흐름 {nodes, edges, meta}
flowTokenString판본 표식 — 고칠 때 baseFlowToken 으로 그대로 보냅니다
editableBoolean이 API 로 고칠 수 있는지 (초안·일시정지만 true)
validationObject켜기 전 검증 결과 — 검증 응답과 같습니다

POST /api/v1/service/messaging/automations

새 초안을 만듭니다. 성공하면 201 과 자동화(flowToken·validation 포함)를 돌려줍니다. 상태는 항상 DRAFT 이며 본문의 status 는 쓰지 않습니다. 덜 채운 흐름도 저장됩니다.

Request Body

필드타입필수설명
nameStringO이름 (최대 200자)
flowObjectO흐름 — nodes 배열 필수, JSON 으로 최대 262,144자

PUT /api/v1/service/messaging/automations/{id}

초안·일시정지 자동화의 흐름을 통째로 바꿉니다. 상태는 그대로 둡니다. 켜진·보관된 자동화는 409 AUTOMATION_NOT_EDITABLE, 그사이 콘솔에서 누가 고쳤으면 409 SAVE_CONFLICT 입니다(다시 조회해 반영한 뒤 보내세요).

Request Body

필드타입필수설명
flowObjectO바꿀 흐름 전체
baseFlowTokenStringO조회·직전 저장 응답의 flowToken
nameString새 이름 — 생략하면 그대로

POST /api/v1/service/messaging/automations/validate

저장하지 않고 흐름을 검증합니다. 본문은 {"flow": {...}} 입니다. 콘솔에서 켤 때와 같은 규칙입니다.

필드타입설명
activatableBoolean켜기를 막는 문제가 없으면 true (발송 자격·추가 인증은 콘솔에서 따로 확인)
problems[]Array켜기를 막는 문제 — nodeId(노드 문제일 때), messageKey, message
warnings[]Array막지는 않는 안내 — 최근 30일 수집 기록이 없는 이벤트(nodeId, eventName, message)

흐름 재료

흐름을 채울 때 고르는 값입니다. 값이 아니라 구조만 돌려줍니다 — 이벤트 속성은 경로·타입만, 연락처는 키만 옵니다.

GET /api/v1/service/messaging/automations/catalog/events

최근 30일 수집된 이벤트를 앱별로 돌려줍니다. events[]: eventName, appId, lastCollectedDate(마지막 집계일), eventCount(기간 건수). 일별 집계라 오늘 처음 들어온 이벤트는 내일 나타납니다.

GET /api/v1/service/messaging/automations/catalog/events/properties?eventName={이벤트}

이벤트 속성의 구조입니다(최근 7일 표본). properties[]: key(트리거·조건의 속성 키 형식, 배열 안은 items[*].id), type(string·number·boolean·array·mixed), variable(문구 치환 모양, 예: #{event.items[0].id}).

GET /api/v1/service/messaging/automations/catalog/contact-data

연락처 속성의 키입니다. customFieldKeys, activityMetrics, variables(문구 치환 변수).

GET /api/v1/service/messaging/automations/catalog/senders

발송 노드에 넣을 수 있는 발신 수단입니다. senderNumbers(승인된 문자 발신번호), kakaoSenderProfiles[](profileName, senderKey, isDefault).

GET /api/v1/service/messaging/automations/catalog/templates?channel={채널}

발송 노드에 고를 템플릿입니다. search(검색어), size(기본 20, 최대 50)를 함께 줄 수 있습니다. 알림톡(KAKAO_ALIMTALK)은 templateCode·senderKey·inspStatus(심사 상태)를, 그 밖의 채널은 templateId 를 노드에 넣습니다.

오류

상태error뜻
400FLOW_REQUIRED · FLOW_INVALID · NODE_ID_REQUIRED · DUPLICATE_NODE_ID흐름이 없거나 형식이 틀림 · 노드 id 가 없거나 겹침
400INVALID_FLOW이 조직에서 찾을 수 없는 리소스를 가리키거나, 승인되지 않은 발신번호를 쓰거나, 흐름 값이 틀림 (message·nodeId 참고)
400INVALID_NAME · BASE_FLOW_TOKEN_REQUIRED · INVALID_SIZE · CHANNEL_REQUIRED · INVALID_EVENT_NAME파라미터 오류
403ADDON_REQUIRED · PERMISSION_DENIED메시징 애드온 없음 · 자동화 권한 없음
403FOREIGN_IP_NOT_ALLOWED메시징 쓰기 요청(만들기·고치기·검증)은 국내 IP 에서만 — 국외 서버는 콘솔 Q&A 로 국외 IP 승인을 요청하세요
404AUTOMATION_NOT_FOUND없거나 다른 조직의 자동화
409AUTOMATION_NOT_EDITABLE · SAVE_CONFLICT켜진·보관된 자동화 · 그사이 다른 곳에서 고침
413FLOW_TOO_LARGE흐름이 JSON 으로 262,144자를 넘음