Saltar al contenido

Apartado 4 de 15 · Sincronizar

Qué se sincroniza y en qué sentido

La lista completa: contactos, etiquetas, conversaciones, mensajes, plantillas, citas y cobros, con lo que se lee, lo que se escribe y lo que Chatendo avisa solo.

Revisado el API 1.27.0 9 min de lectura

En esta página (5)
  1. 4.1 · Personas y su ficha
  2. 4.2 · Conversaciones y mensajes
  3. 4.3 · Canal, plantillas y estado con Meta
  4. 4.4 · Venta, agenda y cobro
  5. 4.5 · Equipo, medición y la IA

Esta es la tabla que hay que mirar para decidir qué se puede sincronizar hoy. Sale de recorrer las rutas de la API, sus permisos y los webhooks de entrada, no de la documentación.

Leyenda: ✅ existe · ⚠️ existe con una pega · ❌ no existe todavía.

4.1 · Personas y su ficha

Entidad Leer (Chatendo → tú) Escribir (tú → Chatendo) Aviso automático
Contacto ✅ GET /contacts (q busca en el nombre, el teléfono, el correo y el valor de cualquier campo propio —un DNI, con o sin guiones ni espacios—; si lo que casó no se ve en la fila, search_hit dice por qué sale), GET /contacts/{id} ✅ POST /contacts · PATCH /contacts/{id} · DELETE · POST /contacts/{id}/merge ✅ contact.created, .updated, .merged, .deleted
Etiquetas de contacto ✅ GET /tags ✅ POST /tags · PATCH · DELETE · PUT /contacts/{id}/tags ✅ contact.tags_changed
Campos propios ✅ GET /contact-field-defs · GET /contacts/{id}/fields ✅ POST /contact-field-defs · PUT /contacts/{id}/fields ❌
Notas del contacto ✅ GET /contacts/{id}/notes ✅ POST · PATCH · DELETE ❌
Duplicados ✅ GET /contacts/{id}/duplicates — —
Persona (varios canales) (§6.7) ✅ GET /conversations/{id}/persona · GET /conversations/{id}/persona/buscar?q= · el campo persona de cada conversación ✅ POST /contacts/{id}/persona (enlazar) · DELETE /contacts/{id}/persona (separar) · POST /contacts/{id}/persona/descartar ❌ ninguno: enlazar no mueve el updated_at de nadie
Historia del contacto ✅ GET /contacts/{id}/timeline — —
Ficha económica ✅ GET /contacts/{id}/ficha-economica — —
Documentos del cliente ✅ GET /contacts/{id}/documents (los archivos de todos sus chats; kind, q, page, per_page) — —
Chats del cliente, por todos sus canales ✅ GET /contacts/{id}/conversations — —

Los documentos del cliente (GET /contacts/{id}/documents, desde Chatendo 1.66.1) son los archivos de todos sus chats, del más reciente al más antiguo: la misma lista que la pestaña Documentos del perfil del cliente en el panel. Incluyen los de sus contactos unidos como la misma persona (§6.7). Pide el permiso conversations:read y solo devuelve lo que ese token podría leer abriendo cada chat; sin ese permiso, 403, y un contacto que no existe o es de otra cuenta da 404. Es de solo lectura y admite kind (all, document, image, audio o video), q (parte del nombre del archivo, hasta 100 caracteres), page y per_page (hasta 50; 12 de serie): cualquier otro parámetro da 422 UNKNOWN_QUERY_PARAM.

Cada archivo trae su id (el de GET /media/{id}), filename, kind, mime, size (bytes; 0 mientras no se ha bajado), direction (in: lo mandó el cliente; out: tu equipo o un automatismo), created_at (cuándo se mandó el mensaje), status (downloaded, pending, failed o deleted: solo downloaded se puede abrir), stream_url, y dónde está: conversation_id, message_id y channel_id. Junto a data y meta (la paginación de siempre) viene counts, con los archivos de cada clase de lo que buscas con q —sin contar kind—, para pintar los filtros:

Terminal
curl -s "$API/contacts/4/documents?kind=document&q=presupuesto&per_page=2" \
     -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'
JSON
{
  "data": [
    {
      "id": 77,
      "message_id": 501,
      "conversation_id": 9,
      "channel_id": 12,
      "kind": "document",
      "mime": "application/pdf",
      "filename": "Presupuesto reforma cocina.pdf",
      "size": 122880,
      "direction": "out",
      "created_at": "2026-10-28T09:00:00Z",
      "status": "downloaded",
      "stream_url": "https://app.chatendo.app/api/v1/media/77"
    }
  ],
  "meta": {"current_page": 1, "last_page": 1, "per_page": 2,
           "total": 1, "from": 1, "to": 1},
  "counts": {"all": 1, "document": 1, "image": 0, "audio": 0, "video": 0}
}

Los chats del cliente (GET /contacts/{id}/conversations) son las conversaciones del contacto —y de sus contactos unidos— que ese token puede leer, la más reciente primero y hasta 100 (meta.has_more dice si había más). Cada una es un recorte de la fila de GET /conversations: el canal (whatsapp_channel_id, platform, channel_name), state, assigned_user, unread_count, last_message_at y el último mensaje. No admite ningún parámetro.

4.2 · Conversaciones y mensajes

Entidad Leer Escribir Aviso automático
Conversación ✅ GET /conversations (por cursor) · GET /conversations/{id} (con persona si su contacto está enlazado con otros, §6.7) ⚠️ assign · claim · close · reopen · bulk-action piden conversations:write, que Desarrolladores → Tokens de API no ofrece (§3). Con messages:send sí: programar mensajes (§6.8) ✅ conversation.created, .assigned, .closed, .reopened, .snoozed, .unsnoozed
Etiquetas de conversación ✅ GET /conversation-tags ✅ POST · PATCH · DELETE ✅ conversation.tags_changed
Mensaje ✅ GET /conversations/{id}/messages (cursor) · /messages/search ✅ POST /conversations/{id}/messages · /media-messages · /forward · /cta-link · POST /outbound-messages (a un teléfono sin conversación, §6.8) · /conversations/{id}/scheduled-messages (programados, §6.8) ✅ message.received, message.sent, message.delivered, message.read, message.failed (message.status_updated queda por compatibilidad)
Notas internas del chat ✅ GET /conversations/{id}/notes ✅ POST · DELETE ❌
Ficheros ✅ GET /media/{id} ✅ POST /conversations/{id}/media-messages —
Códigos de cierre ✅ GET /disposition-codes ✅ POST · PATCH · DELETE —
Respuestas rápidas ✅ GET /canned-responses ✅ POST · PATCH · DELETE —

El nombre de un archivo (filename, desde Chatendo 1.66.1). En los mensajes con archivo (document, image, audio o video), GET /conversations/{id}/messages trae el archivo en media, y su filename es ya el nombre que ve tu equipo en el chat: el que viene en la ficha del archivo o, si esta no lo tiene (pasa con los documentos que manda el cliente por WhatsApp), el que trae el propio mensaje. Un document trae además payload.document.filename (solo esa clave: el resto del payload no sale). Si de verdad no hay nombre, filename es null. El mismo nombre sale en los documentos del cliente (arriba).

4.3 · Canal, plantillas y estado con Meta

Entidad Leer Escribir Aviso automático
Canal ✅ GET /channels · GET /channels/{id} (con su etiqueta y su etiqueta_tono) ✅ POST · PUT · PATCH /settings ❌
Salud del canal ✅ GET /channels/{id}/healthcheck · GET /channels/{id}/quality (la calidad del número, el estado en Meta, el límite diario y el historial; la misma calidad va dentro de cada canal de WhatsApp de GET /channels, como calidad) ✅ PATCH /channels/{id} con proteccion_calidad · POST /channels/{id}/quality/refresh ✅ channel.health_changed (con el estado anterior y el nuevo)
Plantillas ✅ GET /channels/{id}/templates (con su tipo) ✅ POST · PUT · DELETE ✅ template.status_changed (cuando Meta aprueba, rechaza o pausa una)
Instagram ✅ /instagram/profile · /instagram/health ✅ ice-breakers · persistent-menu · subscribe —
Buzón de correo (§15) ✅ GET /channels · GET /channels/{id} (con su bloque email) · GET /channels/{id}/healthcheck ⚠️ POST /channels/email/discover · /test · POST /channels/email · PATCH /channels/{id}/email · POST /channels/{id}/email/sync: piden channels:manage, que un token de Ajustes no lleva (se conecta desde el panel). Contestar sí, con las rutas de siempre (§6.2) ⚠️ message.received y message.sent como en cualquier canal; el estado del buzón no avisa

La calidad del número (calidad en cada canal de WhatsApp y GET /channels/{id}/quality) trae lo que Meta dice del número y lo que Chatendo hace en consecuencia: rating (GREEN, YELLOW, RED o NA), nivel (ok, atencion, alto o desconocido: es el que decide el panel y el freno; un nivel que no conozcas, trátalo como desconocido, nunca como ok), estado_numero, limite_diario (personas nuevas por día, del portfolio de Meta), restriccion, proteccion y frenando. Con proteccion_calidad encendido (de serie), mientras el nivel sea alto una plantilla de marketing no sale: 422 QUALITY_PROTECTION_ACTIVE (§8). Meta ya no avisa del color por webhook: Chatendo se lo pregunta cada hora y cuando alguien pulsa «Comprobar ahora» (POST /channels/{id}/quality/refresh, solo owner o admin, 12 por minuto).

Etiqueta y color del canal, y tipo de plantilla (desde Chatendo 1.66.1). Son datos internos de tu cuenta, para que tu equipo reconozca un número de un vistazo y encuentre una plantilla entre muchas: no viajan a Meta, el cliente nunca los ve, y guardarlos no llama a Meta ni devuelve ninguna plantilla a revisión.

  • etiqueta (texto de hasta 30 caracteres, o null) y etiqueta_tono (un color del 1 al 6, o null para el de siempre) vienen siempre en cada canal de GET /channels y GET /channels/{id}. Son independientes: un canal puede tener color y no etiqueta. Sin etiqueta, el panel enseña el name del canal.
  • tipo (texto de hasta 40 caracteres, o null: sin tipo) viene en cada plantilla de GET /channels/{id}/templates. Agrupa las plantillas de un número: el mismo tipo en dos números son dos grupos.
  • Se leen con channels:read. Ponerlos es PUT o PATCH /channels/{id} (etiqueta, etiqueta_tono) y PUT /channels/{id}/templates/{id} (tipo): piden channels:manage, que Desarrolladores → Tokens de API no ofrece (§2). Lo normal es que los ponga tu equipo desde el panel (Canales y Administración → Plantillas); tu programa los lee, por ejemplo para agrupar sus avisos.
  • Al escribirlos, la clave que no mandas se queda como estaba y null (o un texto vacío) la quita. El servidor guarda el texto limpio (sin espacios de más). Más de 30 o de 40 caracteres, o un color fuera del 1 al 6, es 422. Un PUT de plantilla que solo trae tipo se guarda sin pasar por Meta: no gasta ninguna de las ediciones que Meta permite.
Terminal
curl -s "$API/channels/12" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json'
JSON
{"data": {"id": 12, "name": "WhatsApp 3918",
          "etiqueta": "Ventas", "etiqueta_tono": 3}}

(Recortado a lo que importa aquí: el canal trae muchas más claves.) Ponerlas, con un token que lleve channels:manage:

Terminal
curl -s -X PATCH "$API/channels/12" \
     -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -d '{"etiqueta":"Ventas","etiqueta_tono":3}'

Quitarlas: {"etiqueta":null,"etiqueta_tono":null}.

Y el tipo de una plantilla:

Terminal
curl -s -X PUT "$API/channels/12/templates/42" \
     -H "Authorization: Bearer $TOKEN" -H 'Accept: application/json' -H 'Content-Type: application/json' \
     -d '{"tipo":"Pagos y recibos"}'

4.4 · Venta, agenda y cobro

Entidad Leer Escribir Aviso automático
Cita / agenda ✅ GET /appointments ✅ POST /conversations/{id}/appointments · PATCH · DELETE · /offer ✅ appointment.created, .updated, .cancelled
Pedido de tienda ✅ GET /contacts/{id}/crm-orders ✅ webhooks shop-order y shop-order-v2 ✅ order.created
Cobros pendientes ✅ GET /pending-payments ✅ PATCH · POST /{id}/reminder · POST /contacts/{id}/enlaces-de-pago ✅ payment.completed (pagado por Stripe o marcado a mano)
Campaña ✅ GET /campaigns · /{id} · /report · /reach (a cuántos llegará de verdad, sin bajas, equipo ni proveedores) ⚠️ solo con sesión de persona (campaigns:write no se da a un token) ✅ campaign.finished
Catálogo / ofertas ⚠️ solo con sesión ⚠️ solo con sesión —
Lead nuevo — ✅ webhook lead-v1 (crea contacto y escribe con plantilla; con procedencia apunta además de dónde llegó: §6.4) —
Oportunidades con importe (app «Embudo de ventas», §13) ✅ GET /opportunities · /{id} · /{id}/history · /opportunities/export · GET /opportunity-board ✅ POST /opportunities · PATCH · DELETE · /move · /win · /lose · /reopen ✅ opportunity.created · stage_changed · won · lost

4.5 · Equipo, medición y la IA

Entidad Leer Escribir Aviso automático
Usuarios y equipos ✅ GET /users · GET /teams · /channels/{id}/members ✅ PUT /channels/{id}/members —
Roles y permisos ✅ GET /permissions · GET /roles · GET /users/{id}/effective-permissions · GET /me/permissions (§3) ❌ solo desde el panel —
Analítica ✅ GET /analytics?date_from=&date_to= (las dos fechas son obligatorias) — —
Encuesta CSAT ✅ GET /csat/report — ❌
Conocimiento de la IA ✅ GET /ai-knowledge ✅ POST · PATCH —
Agentes de IA ✅ GET /ai-agents ✅ POST · PATCH —
Proyectos y actuaciones ✅ GET /proyectos ✅ POST · PATCH —
Llamadas de WhatsApp ✅ GET .../call/{id} ✅ POST .../call · /permission · /terminate ❌
Tareas y actividades (app «Tareas», §14) ✅ GET /tasks · /{id} · /tasks/counters · /tasks/export ✅ POST /tasks · PATCH · DELETE · /complete · /cancel · /reopen · /snooze · /tasks/bulk-complete y las demás en bloque (§14.4) · /comments · /steps · POST /activities ✅ task.created · task.completed · task.overdue
Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento