Bandeja

La bandeja reúne lo que la gente dice de las cuentas de un perfil. Los listados piden el profileId; las acciones, la accountId a la que pertenece cada elemento. Los ids de la bandeja (thr_…, cmt_…, mtn_…, cnv_…, rev_…) son opacos y solo valen en tu workspace: guárdalos y devuélvelos tal cual.

Comentarios

Primero, las publicaciones recientes con comentarios, también las que se publicaron fuera de Marsial:

curl

curl "https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Después, los comentarios de una de ellas, con sus respuestas anidadas. Cada comentario dice en can lo que su red permite: responder, borrar, ocultar o dar me gusta.

curl

curl "https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Para responder bajo un comentario, manda su id en commentId; sin él, comentas en la publicación:

curl

curl -X POST "https://api.marsial.dev/v1/inbox/posts/thr_…/comments" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias, Luis!",
    "commentId": "cmt_…"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts/thr_…/comments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias, Luis!",
    "commentId": "cmt_…"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/posts/thr_…/comments",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "¡Gracias, Luis!",
        "commentId": "cmt_…"
    },
)
data = res.json()["data"]

Para ocultarlo o darle me gusta, PATCH con hidden o liked; para borrarlo, DELETE. Si prefieres que te avisemos de cada comentario nuevo, suscríbete a comment.received en los webhooks.

Menciones

Publicaciones y comentarios de otras personas que etiquetan a tus cuentas, de los últimos 7 días:

• Instagram: cuando te etiquetan en un comentario (kind: "comment") o en el texto de su publicación (kind: "caption"). Solo cuentas conectadas a través de Facebook. Instagram manda el texto un momento después: hasta entonces, content llega vacío.
• LinkedIn: cuando mencionan a tu página en una publicación (kind: "post"), con su url.

curl

curl "https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

200 OK

{
  "data": {
    "items": [
      {
        "id": "mtn_…",
        "accountId": "acc_3k9x2m",
        "platform": "instagram",
        "kind": "comment",
        "content": "¡Mirad lo que me ha llegado de @acme!",
        "author": { "username": "lucia" },
        "publishedAt": "2026-10-25T09:12:00.000Z",
        "canReply": true
      }
    ],
    "nextCursor": null
  }
}

Las menciones de Instagram se pueden responder (canReply: true): bajo el comentario que te etiquetó o como comentario en la publicación que lo hizo.

curl

curl -X POST "https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias por compartirlo, Lucía!"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias por compartirlo, Lucía!"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "¡Gracias por compartirlo, Lucía!"
    },
)
data = res.json()["data"]

Precaución

Responder envía un comentario público en la red, en nombre de la cuenta. Haz tus pruebas con una cuenta tuya de pruebas, nunca con la de un cliente.

Mensajes directos

Instagram, Facebook, X, Bluesky y Telegram. En X solo se ven los mensajes no cifrados.

curl

curl "https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Los mensajes de una conversación, de los más nuevos a los más antiguos (sigue con cursor para traer los anteriores):

curl

curl "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Responder devuelve 201 con el id del mensaje (o null si la red no da uno):

curl

curl -X POST "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "¡Hola! Sí, nos quedan en talla M."
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "¡Hola! Sí, nos quedan en talla M."
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "text": "¡Hola! Sí, nos quedan en talla M."
    },
)
data = res.json()["data"]

El id de la conversación ya lleva su cuenta, así que estas llamadas no necesitan accountId. Solo los ids cnv_… guardados antes del 27 de octubre de 2026 lo siguen pidiendo.

Precaución

Instagram y Facebook solo dejan responder durante las 24 horas siguientes al último mensaje de la persona. Pasado ese plazo, la API devuelve un error con el motivo.

Marca una conversación como leída con POST …/read y archívala o recupérala con PATCH y status (archived o active). Para enterarte al momento de cada mensaje nuevo, suscríbete a message.received en los webhooks.

Reseñas

Google Business (de 1 a 5 estrellas) y Facebook (recomienda o no). hasReply=false deja solo las que faltan por responder.

curl

curl "https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

curl

curl -X POST "https://api.marsial.dev/v1/inbox/reviews/rev_…/reply" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias por venir, Marta!"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/reviews/rev_…/reply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "¡Gracias por venir, Marta!"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/reviews/rev_…/reply",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "¡Gracias por venir, Marta!"
    },
)
data = res.json()["data"]

Para borrar tu respuesta, DELETE en la misma ruta con accountId. Las reseñas nuevas llegan por webhook con review.received.