REST APIGET

Avaliações da caixa de entrada

Liste as avaliações do Google Business Profile dos seus locais por nota e por estado de resposta, coloque ou substitua a resposta, exclua-a e marque avaliações como lidas.

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

Retorna as avaliações do Google Business Profile dos seus locais, as mais novas primeiro. Responde { reviews, 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
`ratings`	`number[]`	Só avaliações com estas notas em estrelas, de 1 a 5. Repita a chave ou separe os valores com vírgulas
`replied`	`boolean`	true para avaliações com resposta, false para as sem resposta
`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 avaliação

Campo	Descrição
`id`	ID da avaliação. Use com os endpoints abaixo
`accountId`	A conta a que o item pertence: o id dela em GET /social-accounts
`platform`	Sempre GOOGLE_BUSINESS
`accountName`	Nome de exibição dessa conta
`platformReviewId`	O id da avaliação no Google
`reviewer`	name, avatarUrl e isAnonymous. O Google oculta o nome de quem avalia de forma anônima
`rating`	Estrelas, de 1 a 5
`text`	O texto da avaliação. Pode estar vazio, já que só a nota já é uma avaliação
`reply`	A resposta do local como { text, updatedAt }, ou null
`createdAt`	Quando a avaliação foi escrita
`updatedAt`	Quando quem avaliou a alterou pela última vez
`status`	UNREAD, READ ou DONE. Uma avaliação nova começa como UNREAD, ou DONE quando já tem resposta. Uma avaliação editada volta a UNREAD, a menos que tenha resposta
`repliedAt`	Quando sua conta respondeu pela última vez, ou null
`maxReplyLength`	A maior resposta que o Google aceita, em bytes UTF-8: 4096
`capabilities`	canReply: false quando a conta precisa ser reconectada

Responder a uma avaliação

O Google permite uma resposta por avaliação. Enviar uma resposta substitui a que já existe, tenha sido escrita no AdaptlyPost ou no Google.

PUThttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Coloca a resposta na avaliação, ou a substitui, e responde 200 com a avaliação.

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, até 4096 bytes UTF-8

DELETEhttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Remove a resposta do local e responde 200 com a avaliação.

Chave API (Bearer token)

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

Marcar como lido ou concluído

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

Define o status de até 100 avaliações e responde { reviews, 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 notas baixas sem resposta

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/reviews?ratings=1,2&replied=false' \
  --header 'Authorization: Bearer <api-key>'

Responder a uma avaliação

curl --request PUT \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Sorry about the wait, Piotr. We have added a second barista on weekends." }'

Excluir uma resposta

curl --request DELETE \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>'

Marcar uma avaliação como lida

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

200

{
  "reviews": [
    {
      "id": "rvw_0c93b4d1",
      "accountId": "conn_gbp_001",
      "platform": "GOOGLE_BUSINESS",
      "accountName": "AdaptlyPost Kraków",
      "platformReviewId": "AbFvOqm4x2...",
      "reviewer": {
        "name": "Piotr K.",
        "avatarUrl": null,
        "isAnonymous": false
      },
      "rating": 2,
      "text": "Good coffee, but a 20 minute wait on Saturday.",
      "reply": null,
      "createdAt": "2026-11-07T12:30:00.000Z",
      "updatedAt": "2026-11-07T12:30:00.000Z",
      "status": "UNREAD",
      "repliedAt": null,
      "maxReplyLength": 4096,
      "capabilities": { "canReply": true }
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextCursor": null
}