> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waspytech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Social (Instagram/Facebook)

> Métricas de publicaciones, comentarios y cuenta de Instagram y Facebook.

Publicaciones de Instagram y Facebook con sus métricas, los comentarios que deja
la gente, y el resumen de cuenta (seguidores y crecimiento). Pensada para
cruzar contenido con ventas desde un sistema externo (CRM).

**Scope requerido:** `social:read`

**Regla del dato:** una métrica en `null` significa que Meta **no entrega ese
valor hoy** — porque falta un permiso de App Review o porque no aplica a ese
tipo de medio. Un `0` es un cero de verdad. Nunca convertimos "sin dato" en 0.

**Cache:** las métricas se refrescan en segundo plano cada 6 horas (Meta
limita a \~120 llamadas/hora por cuenta, cupo compartido con el inbox en vivo).
`metricsUpdatedAt` dice de cuándo es el dato. `?refresh=true` fuerza una
lectura fresca donde está disponible.

## GET /social/posts

Listado de publicaciones con métricas, más recientes primero. Paginación por
cursor (`meta.cursor` → `?cursor=`).

| Query param       | Descripción                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `since` / `until` | Filtro por fecha de publicación (ISO, ej. `2026-08-01`)                                                                    |
| `network`         | `instagram` \| `facebook` (omitir = ambas)                                                                                 |
| `type`            | `image` \| `carousel` \| `reel` \| `video` \| `story` \| `text` \| `link`                                                  |
| `limit`           | 1–100, default 50                                                                                                          |
| `refresh`         | `true` encola un refresco inmediato en segundo plano (la respuesta sigue siendo la cacheada; volvé a consultar en \~1 min) |

```bash theme={null}
curl "https://api.waspytech.com/api/v2/social/posts?network=instagram&since=2026-08-01&limit=50" \
  -H "Authorization: Bearer wspy_..."
```

### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "18058723964789810",
      "network": "instagram",
      "type": "reel",
      "permalink": "https://www.instagram.com/reel/DcyboAADTKf/",
      "caption": "Los 3 más vendidos de la semana…",
      "mediaUrl": "https://…",
      "thumbnailUrl": "https://…",
      "publishedAt": "2026-09-02T14:17:37.000Z",
      "expiresAt": null,
      "channelId": "852876b5-…",
      "channelUsername": "blanqueriaxmayorok",
      "metrics": {
        "likes": 15,
        "comments": 2,
        "saved": null,
        "shares": null,
        "reach": null,
        "impressions": null,
        "views": null,
        "video_views": null,
        "plays": null,
        "total_interactions": null,
        "profile_visits": null,
        "follows": null,
        "replies": null,
        "clicks": null
      },
      "metricsUpdatedAt": "2026-09-02T15:00:00.000Z"
    }
  ],
  "meta": { "requestId": "…", "hasMore": true, "cursor": "2026-09-02T14:17:37.000Z|uuid" }
}
```

Las historias (`type: "story"`) traen `expiresAt` (publicación + 24 h). Meta
deja de servirlas al expirar, pero acá quedan guardadas con las métricas del
último refresco.

## GET /social/posts/:id

Un posteo puntual por su id de Meta. Con `?refresh=true` se lee de Meta en el
momento (gasta 1–2 llamadas del cupo compartido; si no hay cupo devuelve `429`
con `Retry-After`).

```bash theme={null}
curl "https://api.waspytech.com/api/v2/social/posts/18058723964789810?refresh=true" \
  -H "Authorization: Bearer wspy_..."
```

## GET /social/posts/:id/comments

Los comentarios del posteo **con su texto**, autor y respuestas anidadas.
Lectura en vivo de Meta con cache de 10 minutos; `?refresh=true` saltea el
cache. `limit` 1–300 (default 100, sobre los comentarios de primer nivel).

```bash theme={null}
curl "https://api.waspytech.com/api/v2/social/posts/18058723964789810/comments?limit=100" \
  -H "Authorization: Bearer wspy_..."
```

### Response `200`

```json theme={null}
{
  "data": {
    "postId": "18058723964789810",
    "network": "instagram",
    "total": 2,
    "comments": [
      {
        "id": "1789…",
        "text": "¿mandás catálogo?",
        "username": "usuario_ig",
        "createdAt": "2026-09-01T15:02:00+0000",
        "likeCount": 0,
        "replies": [
          { "id": "1790…", "text": "¡Sí! Te escribimos por DM", "username": "blanqueriaxmayorok", "createdAt": "…", "likeCount": 1 }
        ]
      }
    ]
  },
  "meta": { "requestId": "…", "cached": false }
}
```

## GET /social/account/summary

Seguidores actuales por cuenta + serie de crecimiento diaria. Meta **no** da
historial de seguidores con los permisos actuales: la serie la construye Waspy
guardando un snapshot por día, así que acumula desde que la función se
desplegó.

| Query param       | Descripción                                |
| ----------------- | ------------------------------------------ |
| `network`         | `instagram` \| `facebook` (omitir = ambas) |
| `since` / `until` | Período (default: últimos 30 días)         |

```bash theme={null}
curl "https://api.waspytech.com/api/v2/social/account/summary?network=instagram" \
  -H "Authorization: Bearer wspy_..."
```

### Response `200`

```json theme={null}
{
  "data": {
    "accounts": [
      {
        "channelId": "852876b5-…",
        "network": "instagram",
        "name": "Blanqueria X Mayor",
        "username": "blanqueriaxmayorok",
        "current": { "followersCount": 945022, "followsCount": 1, "mediaCount": 823, "capturedAt": "2026-09-02" },
        "period": {
          "since": "2026-08-03", "until": "2026-09-02",
          "followerGrowth": null,
          "postsPublished": 41, "likesTotal": 512, "commentsTotal": 87,
          "followerSeries": [ { "date": "2026-09-02", "followers": 945022 } ]
        },
        "insights": { "reach": null, "profileVisits": null, "websiteClicks": null }
      }
    ]
  },
  "meta": { "requestId": "…" }
}
```

## De dónde sale cada métrica (Graph API)

Cuando un número no cuadre, este es el campo exacto de Meta del que salió:

| Métrica                      | Instagram                                                             | Facebook                             |
| ---------------------------- | --------------------------------------------------------------------- | ------------------------------------ |
| `likes`                      | `media.like_count`                                                    | `post.reactions.summary.total_count` |
| `comments`                   | `media.comments_count`                                                | `post.comments.summary.total_count`  |
| `shares`                     | insight `shares` ⏳                                                    | `post.shares.count` ✅                |
| `saved`                      | insight `saved` ⏳                                                     | no existe                            |
| `reach`                      | insight `reach` ⏳                                                     | no existe en Graph v22               |
| `impressions` / `views`      | insight `views` ⏳ (v22 reemplazó `impressions` y `plays` por `views`) | no existe en Graph v22               |
| `video_views`                | = `views` en reels ⏳                                                  | insight `post_video_views` ⏳         |
| `plays`                      | alias de `views` en reels/videos ⏳                                    | —                                    |
| `total_interactions`         | insight `total_interactions` ⏳                                        | —                                    |
| `profile_visits` / `follows` | insights `profile_visits` / `follows` (solo feed) ⏳                   | —                                    |
| `replies`                    | insight `replies` (solo historias) ⏳                                  | —                                    |
| `clicks`                     | —                                                                     | insight `post_clicks` ⏳              |
| `avg_watch_time_ms`          | insight `ig_reels_avg_watch_time` (solo reels) ⏳                      | —                                    |
| seguidores                   | `me.followers_count` ✅                                                | `page.followers_count` ✅             |

✅ = disponible hoy · ⏳ = requiere permisos pendientes de App Review de Meta
(`instagram_business_manage_insights` para IG, `read_insights` para FB). El
código ya los pide: apenas Meta apruebe, las métricas empiezan a llenarse solas
sin ningún deploy.