문서

자동화

댓글에 DM 보내기, 키워드에 답하기 같은 자동화를 템플릿으로 만들고, 고치고, 켜고, 실행 기록을 확인해요.

자동화 하나는 JSON 문서 하나예요. 문서는 트리거와 그 뒤에 이어지는 단계로 되어 있어요. 트리거는 댓글, DM, 멘션, 스토리 답장 중 하나예요.

대시보드의 설정 도우미, 캔버스, 이 API는 모두 같은 문서를 고쳐요. 그래서 API로 만든 흐름을 대시보드에서 열 수 있고, 반대로도 돼요.

보통은 템플릿으로 시작해요. 새로 만든 흐름은 켜기 전까지 초안이에요. 초안 상태에서는 누구에게도 메시지가 나가지 않아요.

계정이 채널 웹훅을 아직 구독하지 않았으면 응답에 warning이 같이 와요. 이때는 그 계정을 다시 연결해야 흐름이 댓글과 메시지를 받을 수 있어요.

DM을 보내려면 계정에 메시지 권한이 있어야 해요. 메시지 권한 없이 연결된 Instagram, Facebook 계정은 409 reconsent_required로 답해요. Instagram 댓글 공감과 Threads 멘션은 권한이 하나씩 따로 필요해요. 그 권한이 없는 계정에서 해당 기능을 쓰는 흐름은 feature 값이 담긴 409 reconsent_required로 답해요. 계정을 한 번 다시 연결하면 권한이 붙어요. 이 오류의 help 값에는 안 될 때 페이지 주소가 들어 있어요.

템플릿과 채널별 가능 범위

comment_public_reply(댓글에 대댓글)와 comment_to_dm(댓글에 DM)은 미리 써 둔 문장 대신 AI가 공개 답글을 쓰게 할 수 있어요.

comment_public_reply: replyMode: "ai"와 instruction을 넣어요. onlyPositive는 기본으로 켜져 있고, AI가 긍정적인 댓글이라고 판단한 경우에만 답해요.
comment_to_dm: publicReplyMode: "ai"와 publicReplyInstruction을 넣어요. 공개 답글은 비공개 답장이 나간 다음에만 달려요. AI는 방금 DM을 보냈다는 사실을 알고 답글을 써요.
예전 템플릿 id인 ai_comment_reply도 받아요. 이 id로 요청하면 replyMode가 "ai"인 comment_public_reply로 만들고, 응답에 renamedFrom을 넣어 줘요.

키워드 조건이 없는 메시지 흐름(기본 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	`GET /v1/automations/templates`에 나온 템플릿 id. 예: `comment_to_dm`, `comment_public_reply`, `keyword_dm`, `default_reply`
`accountId` (필수)	string	흐름이 돌아갈 연결된 계정
`params` (필수)	object	템플릿 인자. 형식은 템플릿의 `params`에 있어요
`enabled`	boolean	`true`면 만들자마자 켜요. 기본값은 `false`(초안)
`name`	string	기본값은 템플릿 제목

curl -X POST https://api.posendy.com/v1/automations/quick/comment_to_dm \
  -H "Authorization: Bearer $POSENDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_7f3c",
    "params": {
      "post": "any",
      "keywords": ["링크"],
      "message": "댓글 고마워요. 아래 버튼을 누르면 링크를 보내 드려요.",
      "buttonTitle": "링크 받기",
      "deliver": { "text": "여기 있어요.", "links": [{ "title": "열기", "url": "https://example.com" }] }
    }
  }'

성공하면 201로 답해요.

`POST /v1/automations`

흐름 문서 전체를 보내서 만들어요.

이름	타입	설명
`accountId` (필수)	string	흐름이 돌아갈 연결된 계정
`doc` (필수)	object	흐름 문서(트리거와 단계). 먼저 `POST /v1/automations/validate`로 검사할 수 있어요
`name`	string	기본값은 `Untitled automation`
`enabled`	boolean	기본값은 `false`
`postId`	string	내 글 하나에 흐름을 묶어요

`POST /v1/automations/validate`

문서를 저장하지 않고 검사만 해요. 문제가 있으면 목록으로 돌려주고, 문제가 없으면 빈 목록을 돌려줘요.

목록과 읽기

`GET /v1/automations`

워크스페이스의 모든 흐름을 최근 것부터 돌려줘요.

`GET /v1/automations/{id}`

흐름 하나를 돌려줘요. 문서, 판, 실행 횟수, 그 채널에서 쓸 수 있는 범위가 들어 있어요.

고치기, 켜고 끄기

`PUT /v1/automations/{id}`

문서를 바꿔요. 읽어 온 판 번호를 같이 보내야 해요. 그 사이에 다른 곳에서 저장했으면 409 version_conflict가 와요.

이름	타입	설명
`version` (필수)	number	읽어 온 판 번호. 더 새 저장이 있으면 `409 version_conflict`와 현재 판 번호가 와요
`doc`	object	새 문서. 대신 `template`을 보내도 돼요
`template`	object	`{ id, params }`. 대시보드 설정 도우미처럼 템플릿으로 문서를 다시 만들어요
`name`	string	새 이름

`PATCH /v1/automations/{id}`

이름을 바꾸거나 enabled 값으로 켜고 꺼요.

`POST /v1/automations/{id}/enable`

흐름을 켜요. 이때부터 실제 사람에게 메시지가 나가요.

`POST /v1/automations/{id}/disable`

흐름을 꺼요. 기다리던 실행도 더 이어지지 않아요.

`POST /v1/automations/{id}/duplicate`

같은 문서와 같은 템플릿 인자로 새 초안을 하나 만들어요.

`DELETE /v1/automations/{id}`

흐름을 지워요. 그 흐름의 실행 기록과 판도 같이 지워져요.

지난 댓글에 보내기

흐름은 원래 새로 달리는 댓글에만 반응해요. 이미 달려 있는 댓글에도 보내려면 흐름을 지난 댓글에 보내요. 흐름을 켜기 전에 달린 댓글이나, 다른 도구가 계정을 맡고 있던 동안 놓친 댓글이 여기에 해당해요.

대상은 Instagram과 Facebook 글의 맨 위 댓글이에요. 흐름이 켜져 있어야 해요.
먼저 미리보기를 불러요. 미리보기는 아무것도 보내지 않아요. 보낼 수 있는 댓글 수를 eligible로, 빠지는 댓글의 이유를 skipped로 알려 줘요.
skipped의 이유 값은 mine, tooOld, keyword, alreadyRan, refused, replyUsed, answered, sameAuthor예요.
한 사람에게는 한 번만 보내요. 같은 사람이 댓글을 여러 번 달았으면 가장 최근 댓글에만 답해요.
refused는 Instagram이 비공개 답장을 거절해서(오류 2534025) 실행이 끝난 댓글 수예요. retryRefused를 켜면 댓글이 달린 지 7일 안인 댓글에 같은 작업 안에서 다시 보내요. 이때 공개 답글은 달지 않아요. 그 사이 다른 실행이 이미 답한 댓글은 replyUsed로 세요.
Instagram이 계정의 메시지를 막고 있는 동안에는 작업이 쉬어요. 그동안 차례가 온 댓글은 held로 세요. 차단이 풀리면 포샌디가 그 댓글에 보내요.

Meta는 댓글 하나에 비공개 답장(프라이빗 리플라이)을 한 번만, 댓글이 달린 뒤 7일 안에만 보내게 해요. 그래서 7일이 지난 댓글은 빠져요. 다른 앱이 이미 DM을 보낸 댓글은 Meta가 거절하고, alreadyReplied로 세요.

Meta는 비공개 답장을 계정당 1시간에 750건으로 제한해요. 켜 둔 흐름도 같은 한도를 나눠 쓰기 때문에 1분에 몇 건씩 나눠서 보내요. 답한 댓글은 아래 실행 기록에 하나씩 남아요.

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

보내지 않고 세기만 해요. 보낼 댓글 수와 빠지는 댓글의 이유를 돌려줘요. 본문은 시작 호출과 같아요.

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

보내기를 시작해요. 202와 작업 정보를 돌려줘요. 흐름마다 작업은 한 번에 하나만 돌아요.

이름	타입	설명
`includeAnswered`	boolean	내 계정이 이미 답글을 단 댓글에도 보내요. 기본값은 `false`
`publicReply`	boolean	각 댓글 아래에 트리거의 공개 답글도 달아요. 기본값은 `false`
`retryRefused`	boolean	Instagram이 비공개 답장을 거절한(오류 2534025) 댓글 중 7일이 안 지난 댓글에 같은 작업 안에서 다시 보내요. 기본값은 `false`

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

가장 최근 작업을 돌려줘요. 상태, 보낸 수, 남은 수가 들어 있어요. 같은 값이 GET /v1/automations/{id} 응답의 pastComments에도 들어 있어요.

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

돌고 있는 작업을 멈춰요. 이미 답한 댓글은 그대로 남아요.

실행과 판

실행이 멈추면 error나 실행 기록에 이유가 남아요.

이유	뜻
`window_closed`	24시간 메시지 창이 닫혔어요
`private_reply_expired`	댓글이 달린 지 7일이 지났어요
주소가 들어 있는 문장	다른 앱이 대화를 맡고 있어요
`failed_ai`	AI 단계가 댓글을 분류하지 못했거나 답을 쓰지 못했어요
`blocked_ai_quota`	워크스페이스가 자동화 AI의 하루 한도를 다 썼어요

failed_ai와 blocked_ai_quota로 멈추면 어느 갈래로도 넘어가지 않아요.

상태가 waiting이고 기록에 private_reply_held가 있으면, Instagram이 계정의 메시지를 잠시 막아서 기다리는 중이에요. 차단이 풀리면 포샌디가 댓글이 달린 지 7일 안에 DM을 보내고, 공개 답글은 그 DM 다음에 달아요.

멈춘 이유로 무엇을 하면 되는지는 GET /v1/help?code= 뒤에 이유 값을 붙여 부르면 알려 줘요.

`GET /v1/automations/{id}/runs`

흐름이 돌 때마다 일어난 일을 돌려줘요. 상태, 멈춘 이유, 단계별 기록이 들어 있어요.

이름	타입	설명
`limit`	query	1~200. 기본값은 50
`before`	query	앞 페이지의 마지막 실행 id

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

저장된 문서의 판 목록을 최근 것부터 돌려줘요.

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

저장된 판 하나의 문서를 돌려줘요. 다음 문서는 인박스와 연락처예요.

이전미디어 다음인박스와 연락처