REST APIGET

Reseñas de la bandeja

Lista las reseñas de Google Business Profile de tus ubicaciones por valoración y estado de respuesta, pon o sustituye la respuesta, elimínala y marca reseñas como leídas.

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

Devuelve las reseñas de Google Business Profile de tus ubicaciones, las más recientes primero. Responde { reviews, total, hasMore, nextCursor }.

Clave API (token Bearer)

Permiso:inbox.readRoles y permisos

Todos los roles tienen inbox.read, así que cualquier clave válida puede leer la bandeja.

Parámetros de consulta

Parámetro	Tipo	Descripción
`accountIds`	`string[]`	Solo estas cuentas, por el id de GET /social-accounts. Repite la clave o separa los valores con comas. Hasta 50
`platforms`	`PlatformType[]`	Solo estas plataformas. Repite la clave o separa los valores con comas
`statuses`	`InboxStatus[]`	Solo elementos en estos estados: UNREAD, READ o DONE. Repite la clave o separa los valores con comas
`since`	`string (ISO 8601)`	Solo elementos creados en la plataforma en esta fecha y hora o después
`search`	`string`	Texto que buscar
`ratings`	`number[]`	Solo reseñas con estas valoraciones en estrellas, de 1 a 5. Repite la clave o separa los valores con comas
`replied`	`boolean`	true para reseñas con respuesta, false para las que no la tienen
`limit`	`number`	Elementos por página, de 1 a 100. Por defecto 25
`cursor`	`string`	El nextCursor de la página anterior. nextCursor es null en la última página

Unos 10 minutos, no en tiempo real

AdaptlyPost lee cada cuenta conectada cada 10 minutos y guarda lo que encuentra. Las listas responden desde esa copia, así que un comentario, mención, mensaje o reseña nuevo aparece en unos 10 minutos. POST /api/v1/inbox/refresh pide una lectura ahora. Los eventos de webhook salen de las mismas lecturas.

Canales que necesitan una reconexión

Todos los canales están abiertos a la API. Cuando a una conexión le falta el permiso de la plataforma para un canal o una acción, incluidos los permisos que la plataforma aún está revisando para AdaptlyPost, GET /api/v1/inbox/summary muestra el canal como RECONNECT_REQUIRED y toda escritura en él responde 403 inbox_reconnect_required. Un token caducado responde lo mismo. Pide al usuario que reconecte la cuenta en AdaptlyPost; reintentar no sirve.

Campos de la reseña

Campo	Descripción
`id`	Id de la reseña. Úsalo con los endpoints de abajo
`accountId`	La cuenta a la que pertenece el elemento: su id de GET /social-accounts
`platform`	Siempre GOOGLE_BUSINESS
`accountName`	Nombre visible de esa cuenta
`platformReviewId`	El id de Google de la reseña
`reviewer`	name, avatarUrl e isAnonymous. Google oculta el nombre de quien deja una reseña anónima
`rating`	Estrellas, de 1 a 5
`text`	El texto de la reseña. Puede estar vacío, porque una valoración sola ya es una reseña
`reply`	La respuesta de la ubicación como { text, updatedAt }, o null
`createdAt`	Cuándo se escribió la reseña
`updatedAt`	Cuándo la cambió por última vez su autor
`status`	UNREAD, READ o DONE. Una reseña nueva empieza como UNREAD, o DONE cuando ya tiene respuesta. Una reseña editada vuelve a UNREAD salvo que tenga respuesta
`repliedAt`	Cuándo respondió tu cuenta por última vez, o null
`maxReplyLength`	La respuesta más larga que acepta Google, en bytes UTF-8: 4096
`capabilities`	canReply: false cuando hay que reconectar la cuenta

Responder a una reseña

Google permite una respuesta por reseña. Enviar una respuesta sustituye la que ya hay, tanto si se escribió en AdaptlyPost como en Google.

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

Pone la respuesta en la reseña, o la sustituye, y responde 200 con la reseña.

Clave API (token Bearer)

Permiso:inbox.replyRoles y permisos

Las escrituras necesitan inbox.reply (Administrador y Editor) y un plan de AdaptlyPost activo. Sin el plan responden 403 subscription_required.

Parámetros del cuerpo

Parámetro	Tipo	Descripción
`text`OBLIGATORIO	`string`	La respuesta, hasta 4096 bytes UTF-8

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

Quita la respuesta de la ubicación y responde 200 con la reseña.

Clave API (token Bearer)

Permiso:inbox.replyRoles y permisos

Marcar como leído o hecho

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

Fija el estado de hasta 100 reseñas y responde { reviews, unreadCount }.

Clave API (token Bearer)

Permiso:inbox.replyRoles y permisos

Parámetros del cuerpo

Parámetro	Tipo	Descripción
`ids`OBLIGATORIO	`string[]`	De 1 a 100 ids de la lista
`status`OBLIGATORIO	`InboxStatus`	UNREAD, READ o DONE

Rechazos

Una llamada rechazada responde { statusCode, error, code, message }. Decide según code. message explica el rechazo con palabras.

Código	Estado	Cuándo, y qué hacer
`inbox_item_not_found`	404	El id no existe o pertenece a otro espacio de trabajo. Detente
`inbox_action_unsupported`	400	La plataforma, o este elemento, no permite ocultar, eliminar o dar me gusta. capabilities dice qué se aplica. Detente
`inbox_reconnect_required`	403	A la conexión le falta el permiso para este canal o acción, incluido uno aún en revisión de la plataforma, o su token caducó. Pide al usuario que reconecte la cuenta en AdaptlyPost. No reintentes
`inbox_reply_invalid`	400	El texto está vacío o supera el límite. El mensaje indica el límite. Corrige el texto
`inbox_messaging_window_closed`	400	Facebook o Instagram: pasó la ventana de respuesta de 24 horas. Detente
`inbox_rate_limited`	429	La plataforma limitó la frecuencia de AdaptlyPost. Reintenta pasado un rato
`inbox_platform_error`	503	La plataforma falló. Reintenta más tarde
`permission_denied`	403	Al rol de la clave le falta inbox.read o inbox.reply. No reintentes
`subscription_required`	403	Una escritura sin un plan de AdaptlyPost activo. No reintentes

Listar valoraciones bajas sin respuesta

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 una reseña

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." }'

Eliminar una respuesta

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

Marcar una reseña como leída

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
}