REST APIGET

Menciones de la bandeja

Lista las publicaciones y comentarios que mencionan tus cuentas en Facebook, Instagram, Threads, Bluesky y Mastodon, respóndelos y márcalos como leídos.

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

Devuelve las publicaciones y comentarios que mencionan tus cuentas, los más recientes primero. Responde { mentions, 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
`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 mención

Campo	Descripción
`id`	Id de la mención. Úsalo con los endpoints de abajo
`accountId`	La cuenta a la que pertenece el elemento: su id de GET /social-accounts
`platform`	La plataforma, como PlatformType
`accountName`	Nombre visible de esa cuenta
`platformMentionId`	El id en la plataforma de la publicación o comentario que menciona la cuenta
`author`	Quién lo escribió: id (el id de usuario de la plataforma), name, username y avatarUrl. id, username y avatarUrl pueden ser null
`text`	El texto que menciona la cuenta
`permalink`	Enlace público en la plataforma, o null cuando la plataforma no da ninguno
`thumbnailUrl`	Imagen de la publicación, o null
`createdAt`	Cuándo se creó en la plataforma
`status`	UNREAD, READ o DONE. Solo AdaptlyPost guarda este estado; la plataforma no lo ve
`replied`	True cuando tu cuenta respondió con AdaptlyPost
`repliedAt`	Cuándo respondió tu cuenta por última vez, o null
`capabilities`	canReply: false cuando la plataforma no deja responder a la cuenta, como en las menciones de Instagram
`replies`	Respuestas enviadas con AdaptlyPost, las más antiguas primero, cada una con id, text, permalink y createdAt. Las respuestas escritas en la app de la plataforma no aparecen

Responder a una mención

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

Responde a la publicación o comentario que menciona la cuenta, desde esa cuenta, y responde 201 con la mención. En Mastodon la respuesta mantiene la visibilidad de la publicación original.

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. Sigue el límite de comentarios de la plataforma: Threads 500, Bluesky 300, Mastodon 500 y Facebook 8000 caracteres

Marcar como leído o hecho

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

Fija el estado de hasta 100 menciones y responde { mentions, 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 menciones nuevas

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 una mención

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 una mención como leída

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
}