REST APIGET

Mensagens da caixa de entrada

Leia as conversas de mensagens diretas no Facebook, Instagram, Bluesky e Mastodon, envie respostas dentro das regras de cada plataforma e marque conversas como concluídas.

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

Retorna as conversas de mensagens diretas, primeiro a que tem a mensagem mais recente. Responde { conversations, 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 conversa

Campo	Descrição
`id`	ID da conversa. 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
`participant`	A outra pessoa: id, name, username e avatarUrl
`lastMessageText`	Texto da mensagem mais recente
`lastMessageAt`	Quando a mensagem mais recente foi enviada
`lastMessageIsOwn`	True quando sua conta enviou a mensagem mais recente
`status`	UNREAD, READ ou DONE. Uma conversa volta a UNREAD quando a outra pessoa escreve e ninguém respondeu desde então, então uma resposta enviada pelo próprio app da plataforma a mantém lida
`repliedAt`	Quando sua conta respondeu pela última vez, ou null
`replyWindowEndsAt`	Facebook e Instagram: quando a janela de resposta de 24 horas fecha, contada a partir da última mensagem que o AdaptlyPost leu. null nas outras plataformas
`maxMessageLength`	A maior mensagem que a plataforma aceita nesta conversa
`capabilities`	canReply: false quando a janela de resposta já fechou ou a plataforma não deixa a conta enviar

Ler uma conversa

GEThttps://post.adaptlypost.com/post/api/v1/inbox/conversations/:id

Retorna { conversation, messages }: a conversa e as mensagens que o AdaptlyPost leu dela. Um id desconhecido responde 404 inbox_item_not_found. Cada mensagem tem estes campos:

Chave API (Bearer token)

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

Campo	Descrição
`id`	ID da mensagem
`isOwn`	True quando sua conta a enviou
`text`	O texto da mensagem
`hasAttachments`	True quando a mensagem traz imagens ou arquivos. A API retorna só o texto
`createdAt`	Quando foi enviada

Enviar uma mensagem

POSThttps://post.adaptlypost.com/post/api/v1/inbox/conversations/:id/messages

Envia uma mensagem da conta na conversa e responde 201 { conversation, message }.

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 mensagem, até o maxMessageLength da conversa

A janela de 24 horas no Facebook e no Instagram

O Facebook e o Instagram só deixam uma empresa responder até 24 horas depois da última mensagem da pessoa. O envio ainda vai para a plataforma depois de replyWindowEndsAt, porque a pessoa pode ter escrito desde a última leitura; quando a plataforma o recusa, a chamada responde 400 inbox_messaging_window_closed. As mensagens do Bluesky exigem uma senha de app com acesso a mensagens diretas.

Marcar como lido ou concluído

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

Define o status de até 100 conversas e responde { conversations, 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 conversas não lidas

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/conversations?statuses=UNREAD' \
  --header 'Authorization: Bearer <api-key>'

Ler uma conversa

curl --request GET \
  --url https://post.adaptlypost.com/post/api/v1/inbox/conversations/cnv_5d0e7a19 \
  --header 'Authorization: Bearer <api-key>'

200
{
  "conversation": { "id": "cnv_5d0e7a19", "...": "..." },
  "messages": [
    {
      "id": "msg_a1f20c33",
      "isOwn": false,
      "text": "Hi, do you ship to Portugal?",
      "hasAttachments": false,
      "createdAt": "2026-11-08T08:55:02.000Z"
    }
  ]
}

Enviar uma mensagem

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/conversations/cnv_5d0e7a19/messages \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Yes, delivery to Portugal takes 3 to 5 days." }'

Marcar uma conversa como concluída

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

200

{
  "conversations": [
    {
      "id": "cnv_5d0e7a19",
      "accountId": "conn_fb_page_001",
      "platform": "FACEBOOK",
      "accountName": "AdaptlyPost",
      "participant": {
        "id": "7230011122233344",
        "name": "João Silva",
        "username": null,
        "avatarUrl": null
      },
      "lastMessageText": "Hi, do you ship to Portugal?",
      "lastMessageAt": "2026-11-08T08:55:02.000Z",
      "lastMessageIsOwn": false,
      "status": "UNREAD",
      "repliedAt": null,
      "replyWindowEndsAt": "2026-11-09T08:55:02.000Z",
      "maxMessageLength": 2000,
      "capabilities": { "canReply": true }
    }
  ],
  "total": 2,
  "hasMore": false,
  "nextCursor": null
}