매크로

대시보드에 등록된 매크로(자주 쓰는 답변)의 목록을 읽는 조회 API입니다. 매크로를 만들거나 고치려면 대시보드를 사용하세요.

목록 조회

GET /macros — 워크스페이스 매크로와 팀 매크로를 함께 cursor pagination으로 조회합니다.

• Scope: macros:read
• 쿼리: limit(기본 50, 1~100), cursor(이전 응답의 meta.next_cursor 값)
• 삭제된 매크로는 제외되며, created_at 내림차순으로 정렬됩니다.

범위를 벗어난 limit은 자동 보정 없이 400 INVALID_QUERY로 거부합니다. 발급 후 24시간이 지난 cursor도 같은 오류를 반환합니다. 자세한 규칙은 페이지네이션을 참고하세요.

아래 요청은 매크로 50건을 조회합니다.

curl "https://api.talk.zeroworks.ai/api/public/v1/macros?limit=50" \
  -H "Authorization: Bearer ztpat_..."

응답

{
  "success": true,
  "data": [
    {
      "id": "m1a2b3c4-...",
      "name": "환영 인사",
      "content": "안녕하세요! 무엇을 도와드릴까요?",
      "scope": "workspace",
      "action_type": "template",
      "sort_order": 0,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "meta": { "has_more": true, "next_cursor": "eyJ..." }
}

필드

필드	타입	설명
id	string	매크로 UUID
name	string	매크로 이름
content	string	답변 본문. template형에서 채워지고, 값이 없으면 키가 생략됩니다
scope	string	적용 범위. workspace 또는 team
team_id	string	scope가 team일 때 해당 팀 UUID. 워크스페이스 범위 매크로에서는 키가 생략됩니다
action_type	string	template(텍스트 응답형) 또는 workflow(워크플로 실행형)
sort_order	integer	대시보드에서 상담원에게 표시되는 정렬 위치
created_at·updated_at	string	RFC 3339 시각

team_id·content는 값이 없으면 null이 아니라 키 자체가 빠지므로 "key" in obj로 존재를 판별하세요. workflow형 매크로에는 content가 없을 수 있습니다. 첨부파일만 가진 template형 매크로는 content가 빈 문자열("")로 반환될 수 있으며, 첨부파일은 공개 API로 노출되지 않습니다. 빈 content를 오류로 취급하지 마세요.

sort_order는 대시보드의 표시 순서를 알려 주는 힌트입니다. 이 API의 목록 정렬에는 쓰이지 않고, 목록은 항상 created_at 내림차순으로 반환됩니다.