Publicaciones

Una publicación es un post de Instagram o Facebook con comentarios. Sus comentarios se agrupan en hilos: un comentario raíz y sus respuestas. Es lo mismo que ves en la bandeja de Publicaciones y lo mismo que llega en los webhooks comment.* .

Las publicaciones no aparecen en /v1/conversations por defecto (usa kind=all para verlas ahí) y no se les escribe con /v1/messages: se responden con estos endpoints.

Endpoints disponibles

MétodoEndpointDescripción
GET/v1/posts Listar publicaciones
GET/v1/posts/{postId} Obtener una publicación
PATCH/v1/posts/{postId} Pausar o reanudar al agente, o asignarle un agente propio
GET/v1/posts/{postId}/threads Listar hilos
GET/v1/posts/{postId}/threads/{threadId} Obtener un hilo con sus comentarios
PATCH/v1/posts/{postId}/threads/{threadId} Resolver, reabrir, pausar al agente en el hilo o cambiar responsables
POST/v1/posts/{postId}/comments Publicar un comentario de la marca
POST/v1/posts/{postId}/threads/{threadId}/replies Responder en público
POST/v1/posts/{postId}/threads/{threadId}/private-replies Responder por mensaje privado
POST/v1/posts/{postId}/threads/{threadId}/send-to-agent Mandar el hilo a responder al agente
POST/v1/posts/{postId}/comments/{commentId}/moderation Ocultar, mostrar, eliminar o marcar spam

Cómo funcionan los IDs

CampoQué identifica
postIdEl id de la publicación en Platica. Es el mismo post.id de los webhooks comment.*.
externalIdEl id del post en Meta.
threadIdEl id del comentario raíz del hilo en Meta. Es el mismo thread.id de los webhooks.
commentIdEl id de un comentario en Meta. Es el mismo comment.id de los webhooks.

Permisos

Los endpoints de publicaciones usan el módulo de conversaciones, igual que la bandeja. Las escrituras se ejecutan a nombre de la persona dueña de la API key (o la que conectó el cliente OAuth): necesita acceso de escritura a conversaciones en el workspace y, si su rol solo ve lo asignado, que la publicación esté asignada a ella. Los agentes internos de Platica pueden leer pero no escribir.

Cobro y bloqueos

Responder por API cuesta y se bloquea igual que en la bandeja:

AcciónSe cobraSe bloquea
Comentario o respuesta públicaNoCon pago vencido o suscripción cancelada
Respuesta privadaComo respuesta a comentario (gratis durante el beta)Con pago vencido o suscripción cancelada
ModerarNoNunca
Pausar, reanudar, resolver, asignarNoNo
Mandar a responder al agenteLo que responda el agenteCon pago vencido, o en prueba sin créditos o al llegar al tope de respuestas del mes

Reintentos seguros

Publicar un comentario, responder en público y responder por privado aceptan el header Idempotency-Key con un UUID. Si repites la llamada con la misma llave, la respuesta trae replayed: true y no se publica dos veces. Úsalo siempre que vayas a reintentar: un timeout puede llegar después de que Meta ya publicó.

Idempotency-Key: 6f1c7a9e-3b4d-4f8a-9c2e-1a5b7d9e0f12

Errores

Los errores siguen el formato general . En details.code viene el motivo:

details.codeHTTPCuándo
COMMENT_FORBIDDEN403La persona de la llave no tiene acceso a esta publicación
COMMENT_POST_NOT_FOUND404La publicación no existe
COMMENT_PAYMENT_PENDING402El workspace tiene un pago pendiente
COMMENT_TEXT_TOO_LONG400Más de 2,200 caracteres en Instagram u 8,000 en Facebook
COMMENT_ATTACHMENT_NOT_SUPPORTED415Imagen en un comentario de Instagram
COMMENT_RATE_LIMITED_BY_META429Meta limitó la cuenta; espera antes de reintentar
COMMENT_META_REJECTED422Meta rechazó la acción
COMMENT_PUBLISH_RESULT_UNKNOWN504No se sabe si Meta publicó; reintenta con la misma llave
PRIVATE_REPLY_ALREADY_SENT409Meta permite una respuesta privada por comentario
PRIVATE_REPLY_WINDOW_CLOSED422Pasaron más de 7 días desde el comentario
PRIVATE_REPLY_NO_DM_CHANNEL409La cuenta no tiene conectado su canal de mensajes
COMMENT_PRIVATE_REPLY_DISABLED403Las respuestas privadas no están activas en el workspace
COMMENT_POST_PAUSED409Mandar a responder con la publicación pausada