예약 방송

개요

oe.schedules.*는 템플릿 기반 예약 방송을 관리합니다. 예약은 반복 규칙(1회·매일·매주·매월)에 따라 지정한 템플릿을 자동으로 발화합니다.

시작하기 전에

예약 방송을 시작하기 전에 아래를 준비하세요.

파트너 앱에 SCHEDULE capability grant 가 있어야 합니다. 없으면 CapabilityDenied 에러가 발생합니다.
예약은 템플릿 기반만 지원합니다. 예약을 만들기 전에 먼저 방송 템플릿을 생성하세요.
참조할 템플릿에 실행 권한(TEMPLATE capability, 실행 grant)이 있어야 합니다. 템플릿 관리 권한만으로는 예약에 자동으로 사용할 수 없습니다.

참고: capability 는 부여 등급(READ·MANAGE)에 따라 사용할 수 있는 API 가 다릅니다. 메서드별 등급은 컨트롤 플레인 개요의 Capability 요약에서 확인하세요.

예약 생성 — `oe.schedules.create()`

지정한 템플릿을 반복 규칙에 따라 자동 발화하는 예약을 만듭니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.schedules.create(input)`	`SCHEDULE` + `TEMPLATE`	`templateHandle` 이 이 앱이 접근 가능한 템플릿으로 resolve 되고, 그 템플릿에 대한 실행 권한 grant 가 있어야 함	`Promise<ScheduleView>`

요청

이름	타입	설명	기본값	필수
`templateHandle`	`string`	예약에 사용할 템플릿 handle	-	O
`name`	`string`	예약 이름	-	O
`recurrence`	`"ONCE" \| "DAILY" \| "WEEKLY" \| "MONTHLY"`	반복 규칙	-	O
`executeTime`	`string`	실행 시각(`HH:MM`)	-	O
`executeDate`	`string`	실행 날짜(`YYYY-MM-DD`)	-	조건부
`daysOfWeek`	`string`	실행 요일(쉼표 구분, 예 `"MON,WED,FRI"`)	-	조건부
`monthlyDay`	`number`	실행 날짜(1–31)	-	조건부
`isLastDay`	`boolean`	말일 실행 여부	-	O
`startDate`	`string`	예약 시작일(`YYYY-MM-DD`)	-	O
`endDate`	`string`	예약 종료일(`YYYY-MM-DD`)	-	X
`notes`	`string`	메모	-	X

참고: executeDate 는 recurrence가 ONCE일 때, daysOfWeek 는 WEEKLY일 때, monthlyDay 는 MONTHLY이고 isLastDay가 false일 때 필요합니다.

응답

ScheduleView — 필드는 아래 "예약 상세 조회" 절의 응답 표와 같습니다.

예제

// 1회 실행
await oe.schedules.create({
  templateHandle: "tpl_morning",
  name: "아침 방송 1회",
  recurrence: "ONCE",
  executeTime: "09:00",
  executeDate: "2026-07-01",
  startDate: "2026-07-01",
  isLastDay: false,
});

// 매일 반복
await oe.schedules.create({
  templateHandle: "tpl_morning",
  name: "매일 아침 방송",
  recurrence: "DAILY",
  executeTime: "09:00",
  startDate: "2026-07-01",
  isLastDay: false,
});

// 매주 평일
await oe.schedules.create({
  templateHandle: "tpl_morning",
  name: "평일 아침 방송",
  recurrence: "WEEKLY",
  executeTime: "09:00",
  daysOfWeek: "MON,TUE,WED,THU,FRI",
  startDate: "2026-07-01",
  isLastDay: false,
});

// 매월 말일
await oe.schedules.create({
  templateHandle: "tpl_monthly",
  name: "월말 마감 방송",
  recurrence: "MONTHLY",
  executeTime: "17:00",
  isLastDay: true,
  startDate: "2026-07-01",
});

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `SCHEDULE` 또는 `TEMPLATE` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`templateHandle` 을 해석할 수 없거나 실행 권한이 없음	템플릿 handle 이 유효한지, 실행 권한이 있는지 확인하세요

예약 목록 조회 — `oe.schedules.list()`

이 앱이 소유한 예약 목록을 조회합니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.schedules.list(opts?)`	`SCHEDULE`	없음 — capability 만으로 게이트되고, 이후 이 앱이 소유한 예약만 반환됩니다	`Promise<ScheduleView[]>`

요청 — 필터 파라미터

이름	타입	설명	기본값	필수
`search`	`string`	예약명 부분일치 필터(대소문자 무시)	-	X

응답

ScheduleView[] — 각 항목의 필드는 아래 "예약 상세 조회" 절의 응답 표와 같습니다.

예제

const all = await oe.schedules.list();

const filtered = await oe.schedules.list({ search: "아침" });

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `SCHEDULE` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요

예약 상세 조회 — `oe.schedules.get()`

예약 하나의 상세 정보를 조회합니다. 반복 상세 필드까지 모두 포함하므로 수정 폼을 채울 때 사용합니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.schedules.get(handle)`	`SCHEDULE`	`handle` 이 이 앱이 소유한 예약으로 resolve 되어야 함(불일치 시 존재 은닉)	`Promise<ScheduleView>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	조회할 예약 handle	-	O

응답

이름	타입	설명
`handle`	`string`	예약 handle
`name`	`string`	예약 이름
`templateHandle`	`string`	사용 중인 템플릿 handle
`recurrence`	`"ONCE" \| "DAILY" \| "WEEKLY" \| "MONTHLY"`	반복 규칙
`executeTime`	`string`	실행 시각
`executionAvailability`	`string`	실행 가능 여부 관련 상태
`executeDate`	`string \| null \| undefined`	실행 날짜(`ONCE`)
`daysOfWeek`	`string \| null \| undefined`	실행 요일(`WEEKLY`)
`monthlyDay`	`number \| null \| undefined`	실행 날짜(`MONTHLY`)
`isLastDay`	`boolean \| undefined`	말일 실행 여부
`startDate`	`string \| null \| undefined`	예약 시작일
`endDate`	`string \| null \| undefined`	예약 종료일
`notes`	`string \| null \| undefined`	메모

예제

const detail = await oe.schedules.get("sch_morning");
console.log(detail.name, detail.recurrence, detail.executeTime);

수정 폼 프리필에는 반복 상세 필드를 그대로 옮겨 담습니다.

const detail = await oe.schedules.get(scheduleHandle);
form.name = detail.name;
form.recurrence = detail.recurrence;
form.executeTime = detail.executeTime?.slice(0, 5) ?? "12:00";
form.executeDate = detail.executeDate ?? todayLocal();
form.daysOfWeek = detail.daysOfWeek?.split(",").map((d) => d.trim()) ?? [];
form.monthlyDay = detail.monthlyDay;
form.isLastDay = detail.isLastDay ?? false;
form.startDate = detail.startDate ?? todayLocal();

주의: startDate 는 요청 형식이 서버 로컬 날짜 검증을 따릅니다. new Date().toISOString()(UTC)으로 만들면 자정 전후에 하루가 밀릴 수 있으므로, YYYY-MM-DD 로컬 날짜 문자열을 직접 조립해 사용하세요.

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `SCHEDULE` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 을 해석할 수 없음	예약 handle 이 유효한지 목록을 다시 조회해 확인하세요

예약 수정 — `oe.schedules.update()`

변경할 필드만 전달합니다. 모든 필드가 optional 입니다.

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.schedules.update(handle, input)`	`SCHEDULE` + (템플릿 교체 시) `TEMPLATE`	`handle` 이 이 앱이 소유한 예약으로 resolve 되어야 함. `templateHandle` 을 함께 보내 템플릿을 교체하면 새 템플릿에 대한 실행 권한이 재검증됨	`Promise<ScheduleView>`

요청

이름	타입	설명	기본값	필수
`templateHandle`	`string`	교체할 템플릿 handle	-	X
`name`	`string`	예약 이름	-	X
`recurrence`	`"ONCE" \| "DAILY" \| "WEEKLY" \| "MONTHLY"`	반복 규칙	-	X
`executeTime`	`string`	실행 시각(`HH:MM`)	-	X
`executeDate`	`string`	실행 날짜(`YYYY-MM-DD`)	-	X
`daysOfWeek`	`string`	실행 요일	-	X
`monthlyDay`	`number`	실행 날짜(1–31)	-	X
`isLastDay`	`boolean`	말일 실행 여부	-	X
`startDate`	`string`	예약 시작일	-	X
`endDate`	`string`	예약 종료일	-	X
`notes`	`string`	메모	-	X

참고: 필드 타입은 서버 검증보다 느슨합니다. 최종 판정은 서버(400 응답)에서 이루어집니다.

응답

ScheduleView — 필드는 위 "예약 상세 조회" 절의 응답 표와 같습니다.

예제

await oe.schedules.update("sch_morning", {
  name: "새벽 방송으로 변경",
  executeTime: "06:00",
});

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `SCHEDULE` 또는 `TEMPLATE` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 또는 교체할 `templateHandle` 을 해석할 수 없음	handle 이 유효한지, 실행 권한이 있는지 확인하세요

예약 삭제 — `oe.schedules.delete()`

기본 정보

메서드	앱 capability	참조 handle 조건	반환 타입
`oe.schedules.delete(handle)`	`SCHEDULE`	`handle` 이 이 앱이 소유한 예약으로 resolve 되어야 함	`Promise<void>`

요청

이름	타입	설명	기본값	필수
`handle`	`string`	삭제할 예약 handle	-	O

응답

반환값이 없습니다(Promise<void>).

예제

await oe.schedules.delete("sch_morning");

대표 에러

에러	HTTP 상태	원인	해결 방법
`CapabilityDenied`	403	앱에 `SCHEDULE` capability grant 가 없음	Open Echo 지원 채널로 grant 를 요청하세요
`TargetUnresolved`	404	`handle` 을 해석할 수 없음	예약 handle 이 유효한지 확인하세요

참고 코드

레퍼런스 앱의 예약 방송 화면 구현은 partner-app/src/features/schedules/Schedules.tsx에서 확인할 수 있습니다.

예약 방송

개요

시작하기 전에

예약 생성 — oe.schedules.create()

기본 정보

요청

응답

예제

대표 에러

예약 목록 조회 — oe.schedules.list()

기본 정보

요청 — 필터 파라미터

응답

예제

대표 에러

예약 상세 조회 — oe.schedules.get()

기본 정보

요청

응답

예제

대표 에러

예약 수정 — oe.schedules.update()

기본 정보

요청

응답

예제

대표 에러

예약 삭제 — oe.schedules.delete()

기본 정보

요청

응답

예제

대표 에러

참고 코드

더보기

예약 생성 — `oe.schedules.create()`

예약 목록 조회 — `oe.schedules.list()`

예약 상세 조회 — `oe.schedules.get()`

예약 수정 — `oe.schedules.update()`

예약 삭제 — `oe.schedules.delete()`