REST APIGET

Menções da caixa de entrada

Liste as publicações e os comentários que mencionam suas contas no Facebook, Instagram, Threads, Bluesky e Mastodon, responda a eles e marque como lidos.

GEThttps://post.adaptlypost.com/post/api/v1/inbox/mentions

Retorna publicações e comentários que mencionam suas contas, os mais novos primeiro. Responde { mentions, total, hasMore, nextCursor }.

Chave API (Bearer token)

Permissão:inbox.readPapéis e permissões

Todos os papéis têm inbox.read, então qualquer chave válida pode ler a caixa de entrada.

Parâmetros de consulta

Parâmetro	Tipo	Descrição
`accountIds`	`string[]`	Só estas contas, pelo id de GET /social-accounts. Repita a chave ou separe os valores com vírgulas. Até 50
`platforms`	`PlatformType[]`	Só estas plataformas. Repita a chave ou separe os valores com vírgulas
`statuses`	`InboxStatus[]`	Só itens nestes estados: UNREAD, READ ou DONE. Repita a chave ou separe os valores com vírgulas
`since`	`string (ISO 8601)`	Só itens criados na plataforma nesta data e hora ou depois
`search`	`string`	Texto a procurar
`limit`	`number`	Itens por página, de 1 a 100. Padrão 25
`cursor`	`string`	O nextCursor da página anterior. nextCursor é null na última página

Cerca de 10 minutos, não em tempo real

O AdaptlyPost lê cada conta conectada a cada 10 minutos e guarda o que encontra. As listas respondem a partir dessa cópia, então um novo comentário, menção, mensagem ou avaliação aparece em cerca de 10 minutos. POST /api/v1/inbox/refresh pede uma leitura agora. Os eventos de webhook vêm das mesmas leituras.

Canais que precisam de reconexão

Todos os canais estão abertos à API. Quando uma conexão não tem a permissão da plataforma para um canal ou ação, incluindo permissões que a plataforma ainda está analisando para o AdaptlyPost, GET /api/v1/inbox/summary mostra o canal como RECONNECT_REQUIRED e toda escrita nele responde 403 inbox_reconnect_required. Um token expirado responde o mesmo. Peça ao usuário que reconecte a conta no AdaptlyPost; tentar de novo não ajuda.

Campos de uma menção

Campo	Descrição
`id`	ID da menção. Use com os endpoints abaixo
`accountId`	A conta a que o item pertence: o id dela em GET /social-accounts
`platform`	A plataforma, como PlatformType
`accountName`	Nome de exibição dessa conta
`platformMentionId`	O id, na plataforma, da publicação ou do comentário que menciona a conta
`author`	Quem escreveu: id (o id de usuário na plataforma), name, username e avatarUrl. id, username e avatarUrl podem ser null
`text`	O texto que menciona a conta
`permalink`	Link público na plataforma, ou null quando a plataforma não fornece um
`thumbnailUrl`	Imagem da publicação, ou null
`createdAt`	Quando foi criado na plataforma
`status`	UNREAD, READ ou DONE. Só o AdaptlyPost guarda esse estado; a plataforma não o vê
`replied`	True quando sua conta respondeu pelo AdaptlyPost
`repliedAt`	Quando sua conta respondeu pela última vez, ou null
`capabilities`	canReply: false quando a plataforma não deixa a conta responder, como nas menções do Instagram
`replies`	Respostas enviadas pelo AdaptlyPost, das mais antigas às mais novas, cada uma com id, text, permalink e createdAt. Respostas escritas no próprio app da plataforma não aparecem

Responder a uma menção

POSThttps://post.adaptlypost.com/post/api/v1/inbox/mentions/:id/reply

Responde, pela conta mencionada, à publicação ou ao comentário que a menciona, e responde 201 com a menção. No Mastodon, a resposta mantém a visibilidade da publicação original.

Chave API (Bearer token)

Permissão:inbox.replyPapéis e permissões

As escritas exigem inbox.reply (Administrador e Editor) e um plano ativo do AdaptlyPost. Sem o plano, respondem 403 subscription_required.

Parâmetros do corpo

Parâmetro	Tipo	Descrição
`text`OBRIGATÓRIO	`string`	A resposta. Segue o limite de comentários da plataforma: Threads 500, Bluesky 300, Mastodon 500 e Facebook 8000 caracteres

Marcar como lido ou concluído

POSThttps://post.adaptlypost.com/post/api/v1/inbox/mentions/status

Define o status de até 100 menções e responde { mentions, unreadCount }.

Chave API (Bearer token)

Permissão:inbox.replyPapéis e permissões

Parâmetros do corpo

Parâmetro	Tipo	Descrição
`ids`OBRIGATÓRIO	`string[]`	De 1 a 100 ids da lista
`status`OBRIGATÓRIO	`InboxStatus`	UNREAD, READ ou DONE

Recusas

Uma chamada recusada responde { statusCode, error, code, message }. Decida pelo code. message explica a recusa em palavras.

Código	Status	Quando, e o que fazer
`inbox_item_not_found`	404	O id não existe ou pertence a outro espaço de trabalho. Pare
`inbox_action_unsupported`	400	A plataforma, ou este item, não permite ocultar, excluir ou curtir. capabilities diz o que se aplica. Pare
`inbox_reconnect_required`	403	A conexão não tem a permissão para este canal ou ação, incluindo uma ainda em análise pela plataforma, ou o token expirou. Peça ao usuário que reconecte a conta no AdaptlyPost. Não tente de novo
`inbox_reply_invalid`	400	O texto está vazio ou passa do limite. A mensagem informa o limite. Corrija o texto
`inbox_messaging_window_closed`	400	Facebook ou Instagram: a janela de resposta de 24 horas já passou. Pare
`inbox_rate_limited`	429	A plataforma limitou as chamadas do AdaptlyPost. Tente de novo depois de um tempo
`inbox_platform_error`	503	A plataforma falhou. Tente de novo mais tarde
`permission_denied`	403	O papel da chave não tem inbox.read ou inbox.reply. Não tente de novo
`subscription_required`	403	Uma escrita sem plano ativo do AdaptlyPost. Não tente de novo

Listar menções novas

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/mentions?statuses=UNREAD&since=2026-11-01T00:00:00Z' \
  --header 'Authorization: Bearer <api-key>'

Responder a uma menção

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/mnt_41c7e0b2/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Thanks for the shout-out!" }'

Marcar uma menção como lida

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/status \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["mnt_41c7e0b2"], "status": "READ" }'

200

{
  "mentions": [
    {
      "id": "mnt_41c7e0b2",
      "accountId": "conn_bsky_001",
      "platform": "BLUESKY",
      "accountName": "adaptlypost.com",
      "platformMentionId": "at://did:plc:4k2x.../app.bsky.feed.post/3lb2x7q",
      "author": {
        "id": "did:plc:7f3q2m",
        "name": "Marta Nowak",
        "username": "marta.bsky.social",
        "avatarUrl": null
      },
      "text": "Scheduling a month of posts with @adaptlypost.com took me 20 minutes",
      "permalink": "https://bsky.app/profile/marta.bsky.social/post/3lb2x7q",
      "thumbnailUrl": null,
      "createdAt": "2026-11-07T18:03:10.000Z",
      "status": "UNREAD",
      "replied": false,
      "repliedAt": null,
      "capabilities": { "canReply": true },
      "replies": []
    }
  ],
  "total": 3,
  "hasMore": false,
  "nextCursor": null
}