문서

인박스와 연락처

DM, 멘션, 댓글 대화를 읽고 답하는 방법이에요. 연락처, 승인을 기다리는 Threads 답글, 팔로워 수도 여기서 다뤄요.

대화는 세 종류예요. 한 사람과 주고받은 DM, Threads 멘션, 네이버 블로그 댓글 묶음이에요. DM 대화에 답하면 DM이 나가요. 멘션이나 댓글 대화에 답하면 그 아래에 공개 답글이 달려요.

DM은 상대가 마지막으로 메시지를 보낸 뒤 24시간 안에만 보낼 수 있어요. 이 시간이 지나서 보내면 403 window_closed가 와요. 포샌디 기록에는 창이 열려 있는데 Instagram이 닫혔다고 거절하는 경우에도 같은 코드가 와요.

직접 답하면 자동화가 30분 쉬어요. 인박스에서 사람이 직접 답하면, 그 대화에서는 자동화가 30분 동안 메시지를 보내지 않아요.

대화

`GET /v1/conversations`

대화 목록을 최근 메시지 순서로 돌려줘요. 상태, 종류, 안 읽음, 별표, 계정, 채널, 검색어로 걸러 볼 수 있어요.

이름	타입	설명
`state`	query	`open`(기본값) 또는 `closed`
`kind`	query	`dm`, `mention`, `comment` 중 하나
`unread`	query	`1`이면 안 읽은 대화만
`starred`	query	`1`이면 별표 단 대화만
`accountId`	query	연결된 계정 하나
`platform`	query	채널 id 하나. 예: `instagram`
`search`	query	사용자 이름, 이름, 마지막 메시지에서 찾아요
`before`	query	앞 페이지에서 받은 `lastMessageAt` 값
`limit`	query	1~200

{
  "data": [
    {
      "id": "cnv_91d2",
      "accountId": "acc_7f3c",
      "account": { "platform": "instagram", "handle": "@brand" },
      "contact": { "id": "ctc_44a0", "username": "jiyoung", "name": "Jiyoung", "optedOut": false },
      "kind": "dm",
      "state": "open",
      "unread": true,
      "lastMessagePreview": "아직 구매할 수 있나요?",
      "window": { "open": true, "expiresAt": "2026-10-03T09:12:00.000Z", "mode": "window" }
    }
  ],
  "hasMore": false,
  "counts": { "open": { "total": 1, "unread": 1 } }
}

`GET /v1/conversations/{id}`

대화 하나를 연락처, 메시지와 함께 돌려줘요.

`POST /v1/conversations/{id}/messages`

내 계정으로 답해요. DM 대화면 DM이 나가고, 멘션이나 댓글 대화면 공개 답글이 달려요.

이름	타입	설명
`text` (필수)	string	보낼 내용
`mediaId`	string	DM에 붙일 업로드한 파일 하나

성공하면 201로 답하고, 창이 닫혔으면 403으로 답해요.

{ "data": { "id": "msg_0c7e", "mid": "aWdfZAG...", "sentAs": "window" } }

`POST /v1/conversations/{id}/drafts/{messageId}`

자동화가 승인을 기다리며 만들어 둔 초안을 보내요. 내용을 고쳐서 보내도 돼요.

`DELETE /v1/conversations/{id}/drafts/{messageId}`

초안을 보내지 않고 버려요.

`POST /v1/inbox/sync`

계정 하나의 최근 대화를 채널에서 다시 가져와요.

상태

주소	하는 일
`POST /v1/conversations/{id}/read`	읽음으로 표시해요
`POST /v1/conversations/{id}/open`	닫았던 대화를 다시 열어요
`POST /v1/conversations/{id}/close`	대화를 닫아요. 열린 목록에서 빠져요
`POST /v1/conversations/{id}/star`	별표를 달아요
`POST /v1/conversations/{id}/unstar`	별표를 떼요
`POST /v1/conversations/{id}/assign`	담당자를 정해요. `userId`를 빼면 나에게 맡겨요
`POST /v1/conversations/{id}/unassign`	담당자를 풀어요

연락처

`GET /v1/contacts`

계정에 메시지를 보낸 사람 목록이에요. 태그, 사용자 필드, 수신 거부 여부가 들어 있어요. 채널이 알려 주는 경우에는 팔로우 여부도 들어 있어요.

이름	타입	설명
`accountId`	query	연결된 계정 하나
`tag`	query	이 태그가 붙은 연락처만
`optedOut`	query	`1`이면 수신을 거부한 사람만
`search`	query	사용자 이름이나 이름에서 찾아요
`limit`	query	1~500. 기본값은 100

`GET /v1/contacts/{id}`

연락처 하나와 그 사람과의 대화를 돌려줘요.

`PATCH /v1/contacts/{id}`

태그, 사용자 필드, 수신 거부를 정해요.

이름	타입	설명
`tags`	string[]	태그를 이 값으로 바꿔요. 최대 50개
`fields`	object	정할 사용자 필드. 기존 필드에 합쳐져요
`optedOut`	boolean	`true`면 이 사람에게 자동 메시지를 하나도 보내지 않아요

`POST /v1/contacts/{id}/refresh`

채널에서 프로필을 다시 읽어 와요.

`DELETE /v1/contacts/{id}`

포샌디에 저장된 연락처와 대화, 메시지를 지워요. 채널 쪽에는 아무 변화가 없어요.

계정 단위

`GET /v1/accounts/{id}/audience`

팔로워 수와 Threads 인구 통계를 돌려줘요. 팔로워 목록은 어느 채널에서도 주지 않아요.

`GET /v1/messaging/violations`

채널 규칙에 걸려서 자동화가 보내지 않은 메시지를 최근 것부터 돌려줘요.

승인을 기다리는 Threads 답글

`GET /v1/threads/pending-replies`

Threads 계정에서 승인을 기다리는 답글 목록이에요.

이름	타입	설명
`accountId` (필수)	query	연결된 Threads 계정

`POST /v1/threads/pending-replies/{replyId}`

기다리는 답글 하나를 승인하거나 무시해요.

이름	타입	설명
`accountId` (필수)	string	그 답글이 있는 Threads 계정
`approve`	boolean	`false`면 답글을 무시해요. 기본값은 `true`

자동 답장을 만들려면 자동화로 넘어가요.

이전자동화 다음플랫폼