Saltar al contenido

Apartado 14 de 15 · Apps y canales

Tareas y actividades: lo que el equipo tiene que hacer

Crea tareas, registra llamadas y reuniones, complétalas con su resultado y expórtalas desde la API de Chatendo: rutas, permisos, fechas, seguimientos y avisos.

Revisado el API 1.158.0 10 min de lectura

En esta página (4)
  1. 14.1 · Las rutas
  2. 14.2 · Lo que conviene saber
  3. 14.3 · Los avisos task.created, task.completed y task.overdue
  4. 14.4 · Estado, prioridad, posponer y el cajón de la tarea

Con la app «Tareas» encendida en la cuenta, cada tarea lleva un tipo (call, meeting, email, whatsapp u other), un título, la fecha y hora en que vence, un responsable del equipo y un cliente (o ninguno, si es una tarea personal), y puede ir ligada a una oportunidad del embudo (§13) y a una conversación. Una actividad es una llamada o una reunión que ya ocurrió fuera de Chatendo, apuntada con su resultado. Con la app apagada, todas estas rutas contestan 403 APP_INACTIVE y no cambian nada.

Las tareas son internas: solo una ruta escribe a un cliente, POST /tasks/{id}/reply (§14.4). Ninguna otra manda WhatsApp, plantillas, correo a un contacto ni llamadas: Chatendo no hace telefonía. Los avisos de una tarea van solo a su responsable (campana, móvil y correo, según sus preferencias), y lo que sale hacia fuera son los avisos a los servidores que tú hayas dado de alta.

Permisos del token: tasks:read («Leer tareas»: lista, una tarea, contadores y exportar) y tasks:write («Gestionar tareas»: crear, editar, completar, cancelar, reabrir, posponer, borrar y registrar actividades; la respuesta al cliente pide además messages:send). Además, el rol de quien creó el token tiene que tener la clave tareas.* de cada ruta, y su alcance recorta lo que ve: las suyas (es el responsable o la creó), las de su equipo o todas. Lo que no alcanza da 404, igual que lo que no existe. Exportar (tareas.exportar) es, de serie, solo del propietario y de los administradores.

14.1 · Las rutas

Ruta Para qué
GET /tasks Lista paginada (page, per_page ≤ 100). Pestaña tab: today (por defecto: de ahora a medianoche), upcoming (de mañana en adelante), overdue (ya vencidas), done, cancelled o all; las tres de pendientes no se pisan. channel=email deja solo lo que viene de una conversación de correo, y cada fila lleva su channel. scope: mine (por defecto, el responsable eres tú), team (tú y tu equipo) o all (todo lo que alcanzas). Filtros: type, source (task, follow_up o all), progress (el estado), priority (alta, media o baja), assignee_user_id (un id, me o none), contact_id, opportunity_id, due_from / due_to (días de la cuenta), q. Orden sort (con - delante, al revés), siempre estable
POST /tasks Alta. Obligatorios type, title y due_at, y contact_id salvo con personal: true (si no, 422 CONTACT_REQUIRED). Opcionales: notes, assignee_user_id (por defecto, quien la crea), opportunity_id y conversation_id (del mismo contacto), remind_before_minutes (de 1 a 10 080) y priority (alta, media —la de serie— o baja)
GET /tasks/{id} Una tarea, con su contacto, su responsable, su oportunidad, su código de cierre, version y can (qué puedes hacer con ella)
PATCH /tasks/{id} Editar tipo, título, notas, vencimiento, responsable, oportunidad, conversación, aviso previo y resultado. Con version, si alguien la cambió antes: 409 VERSION_CONFLICT con cómo está ahora
POST /tasks/{id}/complete Completarla: fija done_at (ahora, o el done_at que mandes) y admite outcome_text y disposition_code_id. Si ya no está pendiente: 409 TASK_NOT_PENDING
POST /tasks/{id}/cancel · /reopen Cancelar una pendiente (reason opcional) · devolver a pendiente una hecha o cancelada (due_at opcional)
DELETE /tasks/{id} Borrarla. Si estaba hecha, sale también de la historia del contacto
POST /tasks/bulk-complete Completar hasta 100 de una vez (ids, y si quieres un mismo outcome_text y disposition_code_id). Devuelve las completadas y las que se saltó porque ya no estaban pendientes; más de 100: 422 BULK_LIMIT_EXCEEDED
GET /tasks/counters Cuántas pendientes hay vencidas, hoy y próximas (scope como en la lista), con la zona horaria de la cuenta y cuándo acaba el día
GET /tasks/export CSV (;, UTF-8 con BOM) con los mismos filtros, filas y orden que la lista. Más de 20 000 filas: 422 EXPORT_TOO_LARGE
POST /activities Registrar una llamada (call) o reunión (meeting) que ya ocurrió: obligatorios type, title, occurred_at, contact_id y outcome_text; opcionales disposition_code_id, conversation_id, opportunity_id, notes y assignee_user_id. Se guarda como tarea hecha y sale en la historia del contacto
Terminal
# Alta: llamar el lunes a las 10 (hora de Madrid), con aviso 30 minutos antes
curl -X POST https://TU-DOMINIO/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Idempotency-Key: alta-tarea-0001" \
  -d '{"type":"call","title":"Llamar para confirmar la visita","due_at":"2026-10-20T10:00:00+02:00","contact_id":4120,"remind_before_minutes":30}'

# Completarla con su resultado (version, la que te devolvió el alta)
curl -X POST https://TU-DOMINIO/api/v1/tasks/5101/complete \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Idempotency-Key: completar-tarea-5101" \
  -d '{"outcome_text":"Confirma la visita del jueves a las 10.","disposition_code_id":3,"version":1}'

# Registrar una llamada que ya se hizo desde el móvil
curl -X POST https://TU-DOMINIO/api/v1/activities \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Idempotency-Key: actividad-0001" \
  -d '{"type":"call","title":"Llamada de seguimiento del presupuesto","occurred_at":"2026-10-18T11:40:00+02:00","contact_id":4120,"outcome_text":"Le encaja el precio; espera la aprobación de su socio el lunes."}'

14.2 · Lo que conviene saber

  • Las fechas viajan en UTC. Puedes mandarlas con su desfase (+02:00) y te vuelven con Z. Las pestañas y los días de due_from / due_to son los de la zona de la cuenta, que devuelven los contadores.
  • Las fechas que mandas van de las 00:00 UTC del 9 de enero de 1970 a las 00:00 UTC del 18 de enero de 2038, los dos bordes incluidos (due_at, done_at y occurred_at; también el due_at de reopen). Fuera de ahí la respuesta es 422 VALIDATION_ERROR con el error en ese campo («La fecha tiene que estar entre las 00:00 UTC del 09/01/1970 y las 00:00 UTC del 18/01/2038.»), y no se guarda nada.
  • Los seguimientos de las conversaciones salen en la misma lista, en solo lectura: los de la persona del token, con source: follow_up, read_only: true y una referencia fu_<id> en vez de un número. Se leen con GET /tasks/fu_<id>; cualquier escritura sobre uno da 409 FOLLOW_UP_READ_ONLY con su conversación, que es donde se gestionan. Si solo quieres tareas, pide source=task. Los seguimientos y sus rutas (/reminders) siguen igual que antes.
  • El resultado es outcome_text (texto libre) y, si encaja, disposition_code_id: uno de los códigos de cierre de tu cuenta (GET /disposition-codes, §4.2). Un código que usa alguna tarea no se puede borrar: 422 DISPOSITION_IN_USE.
  • company_id es la empresa del contacto de la tarea: sale de su contacto, no se guarda en la tarea, y viaja null si el contacto no está en ninguna empresa o si la app «Empresas» está apagada. Con la app encendida, la tarea trae además company ({id, name}) y la lista admite el filtro company_id.
  • Las escrituras admiten Idempotency-Key: un reintento con la misma clave no crea dos tareas.
  • Parámetro o campo que la ruta no conoce: 422 (UNKNOWN_QUERY_PARAM, UNKNOWN_BODY_FIELD). Errores siempre {message, code}.

14.3 · Los avisos task.created, task.completed y task.overdue

Se dan de alta como los demás (§5.1) y usan el mismo sobre y la misma firma (§5.3). Solo salen con la app encendida y siempre después de guardar:

  • task.created: al crear una tarea y al registrar una actividad.
  • task.completed: al completar una tarea (una a una o en lote, un aviso por tarea) y al registrar una actividad, con via (complete, bulk_complete o activity). Una actividad manda los dos, en ese orden, así que con escuchar uno de los dos ves todas las tareas.
  • task.overdue: una tarea pendiente ha pasado su vencimiento sin hacerse. No lo lanza ninguna ruta: sale del barrido de cada minuto, una vez por tarea y vencimiento aunque el barrido pase dos veces; si se cambia la fecha y vuelve a vencer, sale otra vez. Solo de lo vencido en las últimas 72 horas (encender la app no dispara las viejas) y sin mirar el horario ni las preferencias de aviso de nadie. actor es {"kind": "system", "id": null} y data lleva task (con status: "pending"), contact y conversation, con la misma forma que task.created.
  • Editar, cancelar, reabrir o borrar no avisa. Un seguimiento nunca avisa por aquí.

Cuerpo de task.completed (los campos son los que manda Chatendo; los valores, de ejemplo):

JSON
{"event_id": "evt_01JAB3C4D5E6F7G8H9J0K1M2P8",
 "id": "evt_01JAB3C4D5E6F7G8H9J0K1M2P8",
 "type": "task.completed",
 "event": "task.completed",
 "occurred_at": "2026-10-20T08:12:00Z",
 "tenant_id": 4,
 "actor": {"kind": "api", "id": 31},
 "data": {
   "task": {"id": 5101, "type": "call", "title": "Llamar para confirmar la visita",
            "notes": "Pregunta por la segunda sede", "status": "done",
            "due_at": "2026-10-20T08:00:00Z", "assignee_user_id": 31, "created_by_user_id": 31,
            "contact_id": 4120, "personal": false, "opportunity_id": 7702,
            "conversation_id": null, "company_id": null, "created_via": "task",
            "done_at": "2026-10-20T08:12:00Z",
            "outcome_text": "Confirma la visita del jueves a las 10.",
            "disposition": {"id": 3, "label": "Presupuesto enviado"},
            "remind_before_minutes": 30,
            "created_at": "2026-10-18T10:05:00Z", "updated_at": "2026-10-20T08:12:00Z"},
   "contact": {"id": 4120, "external_id": null, "phone_e164": "+34600000001", "name": "Lucía Ferrer"},
   "conversation": null,
   "via": "complete"}}

14.4 · Estado, prioridad, posponer y el cajón de la tarea

  • Estado (progress) y prioridad (priority). Una tarea pendiente está todo (por hacer, la de serie), in_progress (en curso), waiting (esperando), awaiting_payment (pendiente de cobro) o stopped (detenida: sale de Hoy, Próximas y Vencidas, de los contadores y de los avisos; solo en tareas, nunca en un seguimiento). La prioridad es alta, media o baja; la lista la filtra con priority= y la ordena con sort=priority (o -priority). Los dos se cambian con PATCH /tasks/{id}.
  • Posponer. POST /tasks/{id}/snooze con until (obligatorio, con su zona y en el futuro) mueve el vencimiento de una pendiente y vuelve a armar el aviso previo; no cambia el estado. Hecha o cancelada: 409 TASK_NOT_PENDING.
  • En bloque, hasta 100 ids (ids, que pueden ser números o fu_<id>; más de 100: 422 BULK_LIMIT_EXCEEDED): POST /tasks/bulk-complete (§14.1), /bulk-snooze (con until), /bulk-cancel, /bulk-assign (con assignee_user_id) y /bulk-progress (con progress). Las cuatro nuevas piden Idempotency-Key. Si un id no existe, es de otra cuenta o no puedes editarlo: 422 VALIDATION_ERROR en ids.N y no cambia nada. Lo que ya estaba hecho o cancelado no se toca y sale en skipped (not_pending), así que repetir la llamada no hace daño.
  • El cajón de la tarea. Con tasks:read: GET /tasks/{id}/history (qué le ha pasado, lo más nuevo primero; solo lo posterior al 12-11-2026 más su alta), GET /tasks/{id}/comments y GET /tasks/{id}/steps. Los comentarios son notas internas del equipo: nunca llegan al cliente, ni salen en la exportación, en la historia del contacto ni en los avisos. Con tasks:write: POST /tasks/{id}/comments y DELETE …/comments/{comentario}; y los pasos (una lista de cosas por hacer dentro de la tarea, hasta 100): POST /tasks/{id}/steps, PATCH y DELETE …/steps/{paso} y PUT /tasks/{id}/steps/order para reordenarlos. GET /tasks/{id}/origin (solo para un seguimiento, fu_<id>) dice de dónde salió: los mensajes que leyó la revisión automática.
  • Responder al cliente desde la tarea: POST /tasks/{id}/reply con {"text": "…"}. Es la única ruta de Tareas que escribe a un cliente, y es el mismo envío de la bandeja: pide tasks:write y messages:send, Idempotency-Key obligatoria, y el rol de quien creó el token tiene que poder contestar en esa conversación. Sin conversación: 422 TASK_WITHOUT_CONVERSATION. Fuera de las 24 horas solo vale una plantilla y esta ruta no la manda: contesta 422 WINDOW_EXPIRED con requires_template: true. Responde 201 con message_id y conversation_id.
  • «Mi día»: GET /tasks/my-day (sin parámetros) da, siempre en este orden, cuatro bloques de lo tuyo: today, overdue, waiting y awaiting_payment, cada uno con su count y su query: los parámetros exactos de GET /tasks que lo listan.
  • Escribir la tarea como la dirías: POST /tasks/parse con {"text": "llamar a Lucía mañana a las 10"} (y language si no es español). Devuelve lo que entendió (tipo, contacto, fecha y hora) o, si hay dos contactos posibles, los candidatos para elegir; no crea nada: se crea con POST /tasks. 30 por minuto.
  • Preferencias de quien llama: GET y PUT /tasks/preferences: view (list, board o calendar), daily_summary (enabled, apagado de serie; channels, email o push; y time) y default_remind_before_minutes. El resumen diario no sale por WhatsApp: aún no está disponible (422 si lo pides).
Escríbenos por WhatsApp Te contesta nuestro agente de IA al momento