REST API

자동화

댓글 → DM, 키워드 답장 같은 자동화를 템플릿으로 만들고, 읽고, 고치고, 켜고, 실행 기록을 봅니다.

자동화 하나는 JSON 문서 하나입니다. 트리거(댓글, DM, 멘션, 스토리 답장)와 그 뒤의 단계로 이루어집니다. 대시보드 마법사, 캔버스, 이 API 가 모두 같은 문서를 고치므로 여기서 만든 흐름이 대시보드에서 열리고 그 반대도 됩니다.

대부분은 템플릿에서 시작합니다. 새 흐름은 켜기 전까지 초안이고, 그 전에는 누구에게도 아무것도 나가지 않습니다. 계정이 아직 채널 웹훅을 구독하지 않았으면 응답에 warning 이 함께 실립니다. 그 계정을 다시 연결하지 않으면 흐름이 아무 사건도 받지 못합니다.

템플릿과 채널별 가능 범위

「댓글 → 대댓글」(comment_public_reply) 과 「댓글 → DM」(comment_to_dm) 은 정해 둔 문장 대신 AI 가 공개 답글을 쓰게 할 수 있습니다. comment_public_reply 는 replyMode: "ai" 와 instruction 을 주고, 기본으로 켜진 onlyPositive 는 AI 가 긍정으로 읽은 댓글에만 답합니다. comment_to_dm 은 publicReplyMode: "ai" 와 publicReplyInstruction 을 주고, 답글은 비공개 답장이 나간 뒤에만 달리며 AI 는 DM 을 방금 보냈다는 것을 압니다. 예전 템플릿 id ai_comment_reply 도 그대로 받습니다. replyMode "ai" 인 comment_public_reply 로 짓고 응답에 renamedFrom 을 싣습니다.

네이버 블로그의 「서로이웃 새 글 → 댓글」(neighbor_post_comment) 은 블로그마다 간격을 둘 수 있습니다. ownerGapHours 에 1 ~ 720 사이의 시간을 정수로 주면, 자동화가 그 블로그에 마지막으로 단 댓글부터 그 시간이 지나야 다시 답니다. 빼면 간격이 없습니다. 간격은 이 설정이 지키고, 지시문에 적은 간격 규칙은 지키지 못합니다. 범위 밖의 값은 422 invalid_flow 이고 문제 목록에 owner_gap_hours 가 실립니다. excludeBlogs 는 댓글을 달지 않을 블로그 목록입니다. 블로그 주소나 블로그 · 글 링크를 넣으면(최대 200개) 블로그 아이디로 저장되고, 닉네임은 422 exclude_blogs 로 거절됩니다. 목록에 있는 블로그의 새 글은 글을 읽기 전에 neighbor_excluded 로 끝납니다. 목록을 바꿀 때는 전체 목록을 다시 보내고, null 은 목록을 지웁니다.

단어 조건 없는 메시지 흐름(기본 DM 답장 · AI DM 답장)은 계정마다 켜진 것 하나만 둘 수 있습니다. 둘이면 메시지 하나에 답이 둘 나갑니다. 둘째를 켠 채 만들거나 켜면 409 automation_catch_all_taken 이 켜진 흐름 이름과 함께 옵니다.

GET/v1/automations/templates

템플릿 전부. id, 채널, 인자(JSON Schema), 필요한 심사 대상 기능.

GET/v1/automations/capabilities

채널마다 흐름에 쓸 수 있는 트리거와 단계.

만들기

POST/v1/automations/quick/{template}

템플릿과 인자로 흐름을 만듭니다. 가장 흔한 길입니다.

이름타입설명
template필수pathA template id from GET /v1/automations/templates, e.g. comment_to_dm, comment_public_reply, keyword_dm, default_reply.
accountId필수stringThe connected account the flow runs on.
params필수objectThe template's parameters. Their schema is in the template's params.
enabledbooleantrue to turn it on right away. Defaults to false (a draft).
namestringDefaults to the template's title.
curl -X POST https://api.uplika.com/v1/automations/quick/comment_to_dm \
  -H "Authorization: Bearer $UPLIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_7f3c",
    "params": {
      "post": "any",
      "keywords": ["link"],
      "message": "Thanks for the comment. Tap below and I will send the link.",
      "buttonTitle": "Send me the link",
      "deliver": { "text": "Here it is.", "links": [{ "title": "Open", "url": "https://example.com" }] }
    }
  }'

POST/v1/automations

문서 전체로 흐름을 만듭니다.

이름타입설명
accountId필수stringThe connected account the flow runs on.
doc필수objectThe flow document: triggers and nodes. POST /v1/automations/validate checks it first.
namestringDefaults to Untitled automation.
enabledbooleanDefaults to false.
postIdstringTies the flow to one of your posts.

POST/v1/automations/validate

저장하지 않고 문서를 검사합니다. 문제 목록을 주고, 괜찮으면 빈 목록입니다.

목록과 읽기

GET/v1/automations

워크스페이스의 흐름 전부, 최근 것부터.

GET/v1/automations/{id}

흐름 하나. 문서, 판, 실행 수, 그 채널의 가능 범위.

고치기, 켜고 끄기

PUT/v1/automations/{id}

문서를 바꿉니다. 읽은 판을 보내고, 그 뒤에 다른 저장이 있으면 409 version_conflict 입니다.

이름타입설명
version필수numberThe version you read. A newer save answers 409 version_conflict with the current version.
docobjectThe new document. Or send template instead.
templateobject{ id, params }: rebuild the document from a template, as the dashboard wizard does.
namestringA new name.

PATCH/v1/automations/{id}

이름을 바꾸거나 enabled 로 켜고 끄거나 템플릿 인자 일부를 고칩니다. 그 밖의 칸(doc 등)은 400 invalid_params 이고, 문서를 통째로 바꾸려면 PUT 을 씁니다.

이름타입설명
versionnumberThe version you read. Required with params; a newer save answers 409 version_conflict with the current version.
namestringA new name. Leave it out to keep the current one.
enabledbooleantrue turns it on through the same checks as POST /v1/automations/{id}/enable; false turns it off.
paramsobjectOnly the template params to change; the rest stay as they are. An automation edited on the canvas answers 409 automation_not_template.

POST/v1/automations/{id}/enable

켭니다. 이때부터 실제 사람에게 메시지가 나갑니다.

POST/v1/automations/{id}/disable

끕니다. 기다리던 실행은 이어지지 않습니다.

POST/v1/automations/{id}/duplicate

같은 문서와 템플릿 인자로 새 초안을 만듭니다.

DELETE/v1/automations/{id}

흐름과 그 실행 · 판을 지웁니다.

지난 댓글에 보내기

흐름은 새로 달리는 댓글에 반응합니다. 켜기 전에 달렸거나 다른 도구가 계정을 맡고 있던 동안 놓친 댓글, 곧 이미 달려 있는 댓글에 닿으려면 흐름을 지난 댓글에 보냅니다. 인스타그램과 페이스북의 맨 위 댓글이 대상이고 흐름이 켜져 있어야 합니다. 먼저 미리보기를 부릅니다. 아무것도 보내지 않고, 지금 흐름이 나갈 댓글 수를 eligible 로, 나머지가 빠지는 이유를 skipped 의 mine · tooOld · keyword · alreadyRan · refused · replyUsed · answered · sameAuthor 로 돌려줍니다. 한 사람에게는 한 번만 나갑니다. 같은 사람이 댓글을 여러 번 달았으면 가장 새 댓글에만 답합니다. refused 는 인스타그램이 비공개 답장을 거절해(오류 2534025), 또는 계정 주인이 연결된 도구의 메시지 접근을 꺼서(오류 200) 실행이 끝난 댓글 수입니다. retryRefused 를 주면 댓글이 달린 지 7일 안의 그 댓글에 같은 실행으로 다시 보내고 공개 답글은 달지 않으며, 그 사이 다른 실행이 이미 답한 댓글은 replyUsed 로 셉니다. 인스타그램이 계정의 메시지를 막은 동안 작업은 쉬고, 닿은 댓글은 held 로 셉니다. 차단이 풀리면 Uplika 가 그 댓글에 보냅니다.

Meta 는 댓글 하나에 프라이빗 리플라이를 한 번, 댓글 뒤 7일 안에만 허용합니다. 그래서 7일이 지난 댓글은 빠지고, 다른 앱이 이미 DM 을 보낸 댓글은 Meta 가 거절해 alreadyReplied 로 셉니다. Meta 가 프라이빗 리플라이를 계정당 한 시간에 750건으로 제한하고 켜 둔 흐름이 같은 한도를 쓰기 때문에 1분에 몇 건씩 나갑니다. 답한 댓글은 아래 실행 목록에 하나씩 남습니다.

POST/v1/automations/{id}/past-comments/preview

보내지 않고 셉니다. 흐름이 나갈 댓글 수와 나머지가 빠지는 이유. 본문은 시작 호출과 같습니다.

POST/v1/automations/{id}/past-comments

보내기를 시작합니다. 202 와 작업을 돌려주고, 흐름마다 한 번에 하나만 돕니다.

이름타입설명
includeAnsweredbooleanAlso send to comments that already have a reply from the account. Defaults to false.
publicReplybooleanAlso post the trigger's public reply under each comment. Defaults to false.
retryRefusedbooleanAlso send again to comments whose private reply Instagram refused (error 2534025) or that were refused because the account owner turned off message access for connected tools (error 200), within 7 days of the comment, in the same run. Defaults to false.

GET/v1/automations/{id}/past-comments

가장 최근 작업. 상태, 보낸 수, 대기 중인 수. 채널에서 지워진 글은 건너뛰고 posts.gone 에 셉니다(미리보기는 postsGone). 글이 전부 지워졌으면 작업은 post_unavailable 문장으로 failed 가 됩니다. GET /v1/automations/{id} 의 pastComments 에도 같은 값이 실립니다.

DELETE/v1/automations/{id}/past-comments

도는 작업을 멈춥니다. 이미 답한 댓글은 그대로입니다.

실행과 판

멈춘 실행은 error 나 기록에 이유를 남깁니다. 24시간 메시지 창이 닫혔으면 window_closed, 댓글이 7일을 넘겼으면 private_reply_expired, 다른 앱이 대화를 쥐고 있으면 주소가 붙은 문장입니다. superseded 로 끝난 실행은 그 댓글에 프라이빗 리플라이가 이미 있었던 것입니다. 다른 실행이 보냈거나, 이유에 error 2534023 이 있으면 계정에 연결된 다른 앱이 보냈습니다. AI 단계가 댓글을 가르거나 답을 쓰지 못하면 failed_ai, 워크스페이스가 자동화 AI 하루 한도에 닿으면 blocked_ai_quota 로 멈추고, 두 경우 모두 어느 갈래로도 넘어가지 않습니다. 상태가 waiting 이고 기록에 private_reply_held 가 있으면 인스타그램이 계정의 메시지를 일시 차단해 기다리는 중입니다. 차단이 풀리면 댓글이 달린 지 7일 안에 Uplika 가 보내고 공개 답글은 그 DM 뒤에 답니다. 네이버 「서로이웃 새 글 → 댓글」 실행은 done 으로 끝나고 기록에 무슨 일이 있었는지 남깁니다. 글의 블로그가 excludeBlogs 에 있으면 neighbor_excluded, 댓글이 나갔으면 neighbor_commented, 그 블로그의 마지막 댓글부터 ownerGapHours 가 안 지났으면 neighbor_owner_gap(다음 차례 시각이 같이 적힙니다), AI 가 글이 지시문의 주제 밖이라고 봤으면 neighbor_off_topic, 다른 이유로 그 글에 안 쓰겠다고 했으면 neighbor_ai_declined, AI 를 부르지 못했거나 하루 AI 한도를 다 썼으면 neighbor_ai_failed, 우리 댓글이 이미 있었으면 neighbor_already, 글을 읽지 못했으면 neighbor_unreadable 입니다. GET /v1/help?code=<이유> 가 할 일을 알려 줍니다.

GET/v1/automations/{id}/runs

흐름이 돌 때마다 일어난 일. 상태, 멈춘 이유, 단계 기록.

이름타입설명
limitquery1-200, defaults to 50.
beforequeryA run id from the previous page.

GET/v1/automations/{id}/versions

저장된 문서의 판, 최근 것부터.

GET/v1/automations/{id}/versions/{version}

저장된 판 하나의 문서.