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.
En esta página (5)
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 |
✅ POST /contacts · PATCH /contacts · DELETE · POST /contacts |
✅ contact.created, .updated, .merged, .deleted |
| Etiquetas de contacto | ✅ GET /tags |
✅ POST /tags · PATCH · DELETE · PUT /contacts |
✅ contact.tags_changed |
| Campos propios | ✅ GET /contact-field-defs · GET /contacts |
✅ POST /contact-field-defs · PUT /contacts |
❌ |
| Notas del contacto | ✅ GET /contacts |
✅ POST · PATCH · DELETE |
❌ |
| Duplicados | ✅ GET /contacts |
— | — |
| Persona (varios canales) (§6.7) | ✅ GET /conversations · GET /conversations · el campo persona de cada conversación |
✅ POST /contacts (enlazar) · DELETE /contacts (separar) · POST /contacts |
❌ ninguno: enlazar no mueve el updated_at de nadie |
| Historia del contacto | ✅ GET /contacts |
— | — |
| Ficha económica | ✅ GET /contacts |
— | — |
| Documentos del cliente | ✅ GET /contacts (los archivos de todos sus chats; kind, q, page, per_page) |
— | — |
| Chats del cliente, por todos sus canales | ✅ GET /contacts |
— | — |
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:
curl -s "$API/contacts/4/documents?kind=document&q=presupuesto&per_page=2" \
-H "Authorization: Bearer $TOKEN" -H 'Accept: application/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 (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 (cursor) · /messages |
✅ POST /conversations · /media-messages · /forward · /cta-link · POST /outbound-messages (a un teléfono sin conversación, §6.8) · /conversations (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 |
✅ POST · DELETE |
❌ |
| Ficheros | ✅ GET /media |
✅ POST /conversations |
— |
| 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 (con su etiqueta y su etiqueta_tono) |
✅ POST · PUT · PATCH /settings |
❌ |
| Salud del canal | ✅ GET /channels · GET /channels (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 con proteccion_calidad · POST /channels |
✅ channel.health_changed (con el estado anterior y el nuevo) |
| Plantillas | ✅ GET /channels (con su tipo) |
✅ POST · PUT · DELETE |
✅ template.status_changed (cuando Meta aprueba, rechaza o pausa una) |
✅ /instagram · /instagram |
✅ ice-breakers · persistent-menu · subscribe |
— | |
| Buzón de correo (§15) | ✅ GET /channels · GET /channels (con su bloque email) · GET /channels |
⚠️ POST /channels · /test · POST /channels · PATCH /channels · POST /channels: 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, onull) yetiqueta_tono(un color del 1 al 6, onullpara el de siempre) vienen siempre en cada canal deGET /channelsyGET /channels/{id}. Son independientes: un canal puede tener color y no etiqueta. Sin etiqueta, el panel enseña elnamedel canal.tipo(texto de hasta 40 caracteres, onull: sin tipo) viene en cada plantilla deGET /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 esPUToPATCH /channels/{id}(etiqueta,etiqueta_tono) yPUT /channels/{id}/templates/{id}(tipo): pidenchannels: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, es422. UnPUTde plantilla que solo traetipose guarda sin pasar por Meta: no gasta ninguna de las ediciones que Meta permite.
curl -s "$API/channels/12" -H "Authorization: Bearer $TOKEN" -H 'Accept: application/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:
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:
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 · PATCH · DELETE · /offer |
✅ appointment.created, .updated, .cancelled |
| Pedido de tienda | ✅ GET /contacts |
✅ webhooks shop-order y shop-order-v2 |
✅ order.created |
| Cobros pendientes | ✅ GET /pending-payments |
✅ PATCH · POST /{id} · POST /contacts |
✅ 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} · /opportunities · 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 |
✅ PUT /channels |
— |
| Roles y permisos | ✅ GET /permissions · GET /roles · GET /users · GET /me (§3) |
❌ solo desde el panel | — |
| Analítica | ✅ GET /analytics (las dos fechas son obligatorias) |
— | — |
| Encuesta CSAT | ✅ GET /csat |
— | ❌ |
| 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 ... |
✅ POST ... · /permission · /terminate |
❌ |
| Tareas y actividades (app «Tareas», §14) | ✅ GET /tasks · /{id} · /tasks · /tasks |
✅ POST /tasks · PATCH · DELETE · /complete · /cancel · /reopen · /snooze · /tasks y las demás en bloque (§14.4) · /comments · /steps · POST /activities |
✅ task.created · task.completed · task.overdue |