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étodo | Endpoint | Descripció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
| Campo | Qué identifica |
|---|---|
postId | El id de la publicación en Platica. Es el mismo post.id de los webhooks comment.*. |
externalId | El id del post en Meta. |
threadId | El id del comentario raíz del hilo en Meta. Es el mismo thread.id de los webhooks. |
commentId | El 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ón | Se cobra | Se bloquea |
|---|---|---|
| Comentario o respuesta pública | No | Con pago vencido o suscripción cancelada |
| Respuesta privada | Como respuesta a comentario (gratis durante el beta) | Con pago vencido o suscripción cancelada |
| Moderar | No | Nunca |
| Pausar, reanudar, resolver, asignar | No | No |
| Mandar a responder al agente | Lo que responda el agente | Con 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 Si la respuesta es 504 con COMMENT_PUBLISH_RESULT_UNKNOWN, Meta pudo haber publicado. Reintenta
con la misma Idempotency-Key, nunca con una nueva.
Errores
Los errores siguen el formato general . En details.code viene el motivo:
details.code | HTTP | Cuándo |
|---|---|---|
COMMENT_FORBIDDEN | 403 | La persona de la llave no tiene acceso a esta publicación |
COMMENT_POST_NOT_FOUND | 404 | La publicación no existe |
COMMENT_PAYMENT_PENDING | 402 | El workspace tiene un pago pendiente |
COMMENT_TEXT_TOO_LONG | 400 | Más de 2,200 caracteres en Instagram u 8,000 en Facebook |
COMMENT_ATTACHMENT_NOT_SUPPORTED | 415 | Imagen en un comentario de Instagram |
COMMENT_RATE_LIMITED_BY_META | 429 | Meta limitó la cuenta; espera antes de reintentar |
COMMENT_META_REJECTED | 422 | Meta rechazó la acción |
COMMENT_PUBLISH_RESULT_UNKNOWN | 504 | No se sabe si Meta publicó; reintenta con la misma llave |
PRIVATE_REPLY_ALREADY_SENT | 409 | Meta permite una respuesta privada por comentario |
PRIVATE_REPLY_WINDOW_CLOSED | 422 | Pasaron más de 7 días desde el comentario |
PRIVATE_REPLY_NO_DM_CHANNEL | 409 | La cuenta no tiene conectado su canal de mensajes |
COMMENT_PRIVATE_REPLY_DISABLED | 403 | Las respuestas privadas no están activas en el workspace |
COMMENT_POST_PAUSED | 409 | Mandar a responder con la publicación pausada |