REST APIGET

Mensajes de la bandeja

Lee las conversaciones de mensajes directos en Facebook, Instagram, Bluesky y Mastodon, envía respuestas dentro de las reglas de cada plataforma y marca conversaciones como hechas.

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

Devuelve las conversaciones de mensajes directos, primero la del mensaje más reciente. Responde { conversations, 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 conversación

Campo	Descripción
`id`	Id de la conversació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
`participant`	La otra persona: id, name, username y avatarUrl
`lastMessageText`	Texto del mensaje más reciente
`lastMessageAt`	Cuándo se envió el mensaje más reciente
`lastMessageIsOwn`	True cuando tu cuenta envió el mensaje más reciente
`status`	UNREAD, READ o DONE. Una conversación pasa a UNREAD cuando la otra persona escribe y nadie ha respondido desde entonces, así que una respuesta enviada desde la app de la plataforma la deja leída
`repliedAt`	Cuándo respondió tu cuenta por última vez, o null
`replyWindowEndsAt`	Facebook e Instagram: cuándo se cierra la ventana de respuesta de 24 horas, contada desde el último mensaje que leyó AdaptlyPost. null en otras plataformas
`maxMessageLength`	El mensaje más largo que acepta la plataforma en esta conversación
`capabilities`	canReply: false cuando se cerró la ventana de respuesta o la plataforma no deja enviar a la cuenta

Leer una conversación

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

Devuelve { conversation, messages }: la conversación y los mensajes que AdaptlyPost ha leído de ella. Un id desconocido responde 404 inbox_item_not_found. Cada mensaje tiene estos campos:

Clave API (token Bearer)

Permiso:inbox.readRoles y permisos

Campo	Descripción
`id`	Id del mensaje
`isOwn`	True cuando lo envió tu cuenta
`text`	El texto del mensaje
`hasAttachments`	True cuando el mensaje lleva imágenes o archivos. La API devuelve solo el texto
`createdAt`	Cuándo se envió

Enviar un mensaje

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

Envía un mensaje desde la cuenta en la conversación y responde 201 { conversation, message }.

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`	El mensaje, hasta el maxMessageLength de la conversación

La ventana de 24 horas en Facebook e Instagram

Facebook e Instagram solo dejan responder a una empresa dentro de las 24 horas siguientes al último mensaje de la persona. El envío sigue llegando a la plataforma después de replyWindowEndsAt, porque la persona puede haber escrito desde la última lectura; cuando la plataforma lo rechaza, la llamada responde 400 inbox_messaging_window_closed. Los mensajes de Bluesky necesitan una contraseña de aplicación con acceso a mensajes directos.

Marcar como leído o hecho

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

Fija el estado de hasta 100 conversaciones y responde { conversations, 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 conversaciones no leídas

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

Leer una conversación

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 un mensaje

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 una conversación como hecha

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
}