자동화 초안 API 레퍼런스
메시지 자동화(캔버스) 초안을 만들고 고치고 검증합니다. 흐름을 채울 재료도 조회합니다 (10개 엔드포인트)
GET /api/v1/service/messaging/automations
캔버스 자동화 목록을 최근 수정 순으로 조회합니다. 흐름 본문은 싣지 않습니다.
Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| status | String | DRAFT · ACTIVE · PAUSED · ARCHIVED | |
| size | Integer | 최대 개수 (기본: 20, 최대: 50) |
Response
automations[] 의 각 항목은 아래와 같고, timeZone(조직 시간대)이 함께 옵니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| id | Long | 자동화 ID |
| name | String | 이름 |
| status | String | 상태 |
| triggerMode | String | EVENT · FREQUENCY · SCHEDULE |
| triggerEventName | String | 트리거 이벤트 (정기 발송이면 null) |
| appIds | Array | 트리거 앱 ID |
| updatedAt | String | 마지막 수정 시각 (조직 시간대, ISO 8601) |
| consoleUrl | String | 콘솔 캔버스 경로 — 여기서 확인하고 켭니다 |
GET /api/v1/service/messaging/automations/{id}
자동화 하나를 조회합니다. 목록 항목의 필드에 아래가 더해집니다. 다른 조직의 ID 는 404 입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| flow | Object | 흐름 {nodes, edges, meta} |
| flowToken | String | 판본 표식 — 고칠 때 baseFlowToken 으로 그대로 보냅니다 |
| editable | Boolean | 이 API 로 고칠 수 있는지 (초안·일시정지만 true) |
| validation | Object | 켜기 전 검증 결과 — 검증 응답과 같습니다 |
POST /api/v1/service/messaging/automations
새 초안을 만듭니다. 성공하면 201 과 자동화(flowToken·validation 포함)를 돌려줍니다. 상태는 항상 DRAFT 이며 본문의 status 는 쓰지 않습니다. 덜 채운 흐름도 저장됩니다.
Request Body
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| name | String | O | 이름 (최대 200자) |
| flow | Object | O | 흐름 — nodes 배열 필수, JSON 으로 최대 262,144자 |
PUT /api/v1/service/messaging/automations/{id}
초안·일시정지 자동화의 흐름을 통째로 바꿉니다. 상태는 그대로 둡니다. 켜진·보관된 자동화는 409 AUTOMATION_NOT_EDITABLE, 그사이 콘솔에서 누가 고쳤으면 409 SAVE_CONFLICT 입니다(다시 조회해 반영한 뒤 보내세요).
Request Body
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| flow | Object | O | 바꿀 흐름 전체 |
| baseFlowToken | String | O | 조회·직전 저장 응답의 flowToken |
| name | String | 새 이름 — 생략하면 그대로 |
POST /api/v1/service/messaging/automations/validate
저장하지 않고 흐름을 검증합니다. 본문은 {"flow": {...}} 입니다. 콘솔에서 켤 때와 같은 규칙입니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| activatable | Boolean | 켜기를 막는 문제가 없으면 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 | 뜻 |
|---|---|---|
| 400 | FLOW_REQUIRED · FLOW_INVALID · NODE_ID_REQUIRED · DUPLICATE_NODE_ID | 흐름이 없거나 형식이 틀림 · 노드 id 가 없거나 겹침 |
| 400 | INVALID_FLOW | 이 조직에서 찾을 수 없는 리소스를 가리키거나, 승인되지 않은 발신번호를 쓰거나, 흐름 값이 틀림 (message·nodeId 참고) |
| 400 | INVALID_NAME · BASE_FLOW_TOKEN_REQUIRED · INVALID_SIZE · CHANNEL_REQUIRED · INVALID_EVENT_NAME | 파라미터 오류 |
| 403 | ADDON_REQUIRED · PERMISSION_DENIED | 메시징 애드온 없음 · 자동화 권한 없음 |
| 403 | FOREIGN_IP_NOT_ALLOWED | 메시징 쓰기 요청(만들기·고치기·검증)은 국내 IP 에서만 — 국외 서버는 콘솔 Q&A 로 국외 IP 승인을 요청하세요 |
| 404 | AUTOMATION_NOT_FOUND | 없거나 다른 조직의 자동화 |
| 409 | AUTOMATION_NOT_EDITABLE · SAVE_CONFLICT | 켜진·보관된 자동화 · 그사이 다른 곳에서 고침 |
| 413 | FLOW_TOO_LARGE | 흐름이 JSON 으로 262,144자를 넘음 |