Feed de cambios · API de Totem

Resumen

GET /v1/sync/changes devuelve los cambios de un equipo, página a página, en el orden en que Totem los registró. Sin cursor, empieza una carga inicial de todos los registros. Con el next_cursor de tu última página, devuelve lo que ha cambiado desde entonces. Cada elemento es el estado actual de un registro, o una eliminación que te indica que lo borres. En cualquier versión pueden aparecer en el feed nuevos tipos de registro: guarda u omite un elemento cuyo kind no conozcas y sigue sincronizando.

Guarda next_cursor después de aplicar cada página, aunque venga vacía, y envíalo en tu siguiente petición. Un cursor caduca 30 días después del punto del feed al que llegó; un equipo que consultas cada pocos minutos nunca llega a ese punto.

Esta página es la referencia: los parámetros, el objeto de cada elemento y los errores. Sincroniza una copia es la guía: cómo aplicar una página, cómo recuperarte de cada error y cómo ejecutar un cliente de sincronización que Totem prueba.

Lee el feed de cambios de un equipo

GET /v1/sync/changes

Devuelve la siguiente página de cambios de un equipo, en el orden en que Totem los registró: cada elemento es el estado actual de un registro o su eliminación. Sin cursor empieza una carga inicial de todos los registros; después de aplicar cada página, guarda su next_cursor y envíalo en la siguiente petición, aunque la página llegue vacía. Un cursor caduca 30 días después del punto del feed al que llegó o, mientras una carga inicial sigue en curso, 30 días después de que empezara.

Permisos: crm:readcalls:readmessages:readcalendar:read
Límite de frecuencia: Sincronización

Parámetros de consulta

cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo para empezar una carga inicial desde el principio.
limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos FeedItem.

object string
Siempre list.
data Array<FeedItem>
Cambios en el orden en que Totem los registró. Durante una carga inicial, un registro puede aparecer más de una vez.
has_more boolean
true si ya hay más cambios listos; false cuando estás al día.
next_cursor string
Siempre presente, también en una página vacía. Guárdalo después de aplicar la página y envíalo en la siguiente petición.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 resync_required Hay que volver a sincronizar
409 capture_not_ready Los datos del equipo aún se están preparando
410 sync_cursor_expired Cursor de sincronización caducado
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/sync/changes?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "kind": "lead",
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "version": 3,
      "object": {
        "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
        "object": "lead",
        "livemode": false,
        "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
        "record_kind": "lead",
        "name": "Alex",
        "surname": "Rivera",
        "email": "alex.rivera@example.com",
        "company": "Example Dental",
        "phone": "+12025550123",
        "phone_status": "valid",
        "status": "contacted",
        "status_set_by": "ai",
        "archive_reason": null,
        "archived_from_status": null,
        "contact_permissions": {
          "do_not_contact": false,
          "email_opt_out": false,
          "email_opt_out_at": null,
          "whatsapp_consent": null,
          "provenance": {
            "do_not_contact": null,
            "email_opt_out": null,
            "whatsapp_consent": null
          }
        },
        "merged_into": null,
        "transferred_to": null,
        "revived_at": null,
        "pipeline_cleared": false,
        "converted_at": null,
        "value_at_conversion": null,
        "priority": "high",
        "tags": [
          "spring-check-up"
        ],
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
        "assignees": [
          "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
        ],
        "estimated_value": 1200,
        "estimated_value_currency": null,
        "source": "meta_lead_ads",
        "source_channel": null,
        "source_detail": null,
        "source_provenance": "member_editable",
        "created_at": "2026-09-28T10:15:00.000Z",
        "version": 3,
        "updated_at": "2026-09-28T10:20:01.250Z"
      }
    },
    {
      "kind": "call",
      "id": "call_m1pf4APjJWVi3Z7ulyNaW8y3lUi7V",
      "version": 5,
      "removed": {
        "reason": "deleted"
      }
    },
    {
      "kind": "lead_response",
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "version": 7,
      "object": {
        "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
        "object": "lead_response",
        "livemode": false,
        "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
        "last_inbound_at": "2026-10-01T08:58:00.000Z",
        "last_outbound_at": "2026-10-01T08:59:30.000Z",
        "awaiting_reply": false,
        "last_answered_call_at": "2026-09-28T10:17:00.000Z",
        "last_whatsapp_delivery_status": "read",
        "coverage": {
          "conversations": 2,
          "calls": 1,
          "channels_without_delivery_data": [
            "email"
          ],
          "truncated": false
        },
        "version": 7,
        "updated_at": "2026-10-01T08:59:31.040Z"
      }
    }
  ],
  "has_more": false,
  "next_cursor": "eyJ2IjoxLCJ0ZWFtIjoidGVhbV9yOXVZcklXNGdTRkpKNmhaUTlpcDFVSXBQYUFEMUNGN05SIiwiZXBvY2giOjAsInQiOnsicyI6MTc5MDg0NTE3MSwibnMiOjQwMDAwMDAwfSwibiI6IjVkMjJhMTVlM2E5MmNmYTE4NzUzZTVmYzkyZmVjNzI0MjQyNjIzZDE2MGIxZTUxMzRiYTM1ODE5MmUzNzM0ZjEiLCJicyI6bnVsbH01ZPX02"
}

El objeto `FeedItem`

Un cambio: el estado actual del registro, o su eliminación.

Atributos comunes a todas las variantes

kind string
El tipo del registro, como lead o call.
Valores posibles
- lead
- lead_attribution
- lead_response
- activity
- call
- conversation
- booking
- board
version integer Rango ≥ 1
La versión del registro. Aplica el elemento solo si es mayor que la versión que guardas.

Variantes

Cada FeedItem es exactamente una de estas 2 variantes.

Con `object`

id string Prefijo del id lead_… act_… call_… conv_… bkg_… brd_…
Identificador público del registro; las facetas lead_attribution y lead_response usan el de su lead.
object uno de 8 objetos
El registro tal como está ahora.
Según kind:
- lead usa Lead
- lead_attribution usa LeadAttribution
- lead_response usa LeadResponse
- activity usa Activity
- call usa Call
- conversation usa Conversation
- booking usa Booking
- board usa Board

Con `removed`

id string Prefijo del id lead_… act_… call_… conv_… bkg_… brd_…
Identificador público del registro eliminado.
removed object
Presente solo en una eliminación.
- reason string
  erased tras una supresión, que es también lo que hace borrar un lead, una llamada o una conversación en Totem: suprimir un lead suprime también sus llamadas, sus conversaciones y sus duplicados fusionados, mientras que sus citas se conservan con lead a null. deleted en cualquier otra eliminación. En ambos casos, borra tu copia y conserva esta versión para ignorar una copia anterior que llegue después.
  Valores posibles
  erased
  deleted

{
  "kind": "lead",
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "version": 3,
  "object": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "record_kind": "lead",
    "name": "Alex",
    "surname": "Rivera",
    "email": "alex.rivera@example.com",
    "company": "Example Dental",
    "phone": "+12025550123",
    "phone_status": "valid",
    "status": "contacted",
    "status_set_by": "ai",
    "archive_reason": null,
    "archived_from_status": null,
    "contact_permissions": {
      "do_not_contact": false,
      "email_opt_out": false,
      "email_opt_out_at": null,
      "whatsapp_consent": null,
      "provenance": {
        "do_not_contact": null,
        "email_opt_out": null,
        "whatsapp_consent": null
      }
    },
    "merged_into": null,
    "transferred_to": null,
    "revived_at": null,
    "pipeline_cleared": false,
    "converted_at": null,
    "value_at_conversion": null,
    "priority": "high",
    "tags": [
      "spring-check-up"
    ],
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
    "assignees": [
      "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
    ],
    "estimated_value": 1200,
    "estimated_value_currency": null,
    "source": "meta_lead_ads",
    "source_channel": null,
    "source_detail": null,
    "source_provenance": "member_editable",
    "created_at": "2026-09-28T10:15:00.000Z",
    "version": 3,
    "updated_at": "2026-09-28T10:20:01.250Z"
  }
}