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필수 | path | A template id from GET /v1/automations/templates, e.g. comment_to_dm, comment_public_reply, keyword_dm, default_reply. |
accountId필수 | string | The connected account the flow runs on. |
params필수 | object | The template's parameters. Their schema is in the template's params. |
enabled | boolean | true to turn it on right away. Defaults to false (a draft). |
name | string | Defaults 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필수 | string | The connected account the flow runs on. |
doc필수 | object | The flow document: triggers and nodes. POST /v1/automations/validate checks it first. |
name | string | Defaults to Untitled automation. |
enabled | boolean | Defaults to false. |
postId | string | Ties 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필수 | number | The version you read. A newer save answers 409 version_conflict with the current version. |
doc | object | The new document. Or send template instead. |
template | object | { id, params }: rebuild the document from a template, as the dashboard wizard does. |
name | string | A new name. |
PATCH/v1/automations/{id}
이름을 바꾸거나 enabled 로 켜고 끄거나 템플릿 인자 일부를 고칩니다. 그 밖의 칸(doc 등)은 400 invalid_params 이고, 문서를 통째로 바꾸려면 PUT 을 씁니다.
| 이름 | 타입 | 설명 |
|---|---|---|
version | number | The version you read. Required with params; a newer save answers 409 version_conflict with the current version. |
name | string | A new name. Leave it out to keep the current one. |
enabled | boolean | true turns it on through the same checks as POST /v1/automations/{id}/enable; false turns it off. |
params | object | Only 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 와 작업을 돌려주고, 흐름마다 한 번에 하나만 돕니다.
| 이름 | 타입 | 설명 |
|---|---|---|
includeAnswered | boolean | Also send to comments that already have a reply from the account. Defaults to false. |
publicReply | boolean | Also post the trigger's public reply under each comment. Defaults to false. |
retryRefused | boolean | Also 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
흐름이 돌 때마다 일어난 일. 상태, 멈춘 이유, 단계 기록.
| 이름 | 타입 | 설명 |
|---|---|---|
limit | query | 1-200, defaults to 50. |
before | query | A run id from the previous page. |
GET/v1/automations/{id}/versions
저장된 문서의 판, 최근 것부터.
GET/v1/automations/{id}/versions/{version}
저장된 판 하나의 문서.