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.
En esta página (4)
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 |
Una tarea, con su contacto, su responsable, su oportunidad, su código de cierre, version y can (qué puedes hacer con ella) |
PATCH /tasks |
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 |
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 · /reopen |
Cancelar una pendiente (reason opcional) · devolver a pendiente una hecha o cancelada (due_at opcional) |
DELETE /tasks |
Borrarla. Si estaba hecha, sale también de la historia del contacto |
POST /tasks |
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 |
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 |
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 |
# 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 conZ. Las pestañas y los días dedue_from/due_toson 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_atyoccurred_at; también eldue_atdereopen). Fuera de ahí la respuesta es 422VALIDATION_ERRORcon 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: truey una referenciafu_<id>en vez de un número. Se leen conGET /tasks/fu_<id>; cualquier escritura sobre uno da 409FOLLOW_UP_READ_ONLYcon su conversación, que es donde se gestionan. Si solo quieres tareas, pidesource=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: 422DISPOSITION_IN_USE. company_ides la empresa del contacto de la tarea: sale de su contacto, no se guarda en la tarea, y viajanullsi el contacto no está en ninguna empresa o si la app «Empresas» está apagada. Con la app encendida, la tarea trae ademáscompany({id, name}) y la lista admite el filtrocompany_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, convia(complete,bulk_completeoactivity). 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.actores{"kind": "system", "id": null}ydatallevatask(constatus: "pending"),contactyconversation, con la misma forma quetask.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):
{"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) ostopped(detenida: sale de Hoy, Próximas y Vencidas, de los contadores y de los avisos; solo en tareas, nunca en un seguimiento). La prioridad esalta,mediaobaja; la lista la filtra conpriority=y la ordena consort=priority(o-priority). Los dos se cambian conPATCH /tasks/{id}. - Posponer.
POST /tasks/{id}/snoozeconuntil(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 ofu_<id>; más de 100:422 BULK_LIMIT_EXCEEDED):POST /tasks/bulk-complete(§14.1),/bulk-snooze(conuntil),/bulk-cancel,/bulk-assign(conassignee_user_id) y/bulk-progress(conprogress). Las cuatro nuevas pidenIdempotency-Key. Si un id no existe, es de otra cuenta o no puedes editarlo:422 VALIDATION_ERRORenids.Ny no cambia nada. Lo que ya estaba hecho o cancelado no se toca y sale enskipped(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}/commentsyGET /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. Contasks:write:POST /tasks/{id}/commentsyDELETE …/comments/{comentario}; y los pasos (una lista de cosas por hacer dentro de la tarea, hasta 100):POST /tasks/{id}/steps,PATCHyDELETE …/steps/{paso}yPUT /tasks/{id}/steps/orderpara 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}/replycon{"text": "…"}. Es la única ruta de Tareas que escribe a un cliente, y es el mismo envío de la bandeja: pidetasks:writeymessages:send,Idempotency-Keyobligatoria, 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: contesta422 WINDOW_EXPIREDconrequires_template: true. Responde201conmessage_idyconversation_id. - «Mi día»:
GET /tasks/my-day(sin parámetros) da, siempre en este orden, cuatro bloques de lo tuyo:today,overdue,waitingyawaiting_payment, cada uno con sucounty suquery: los parámetros exactos deGET /tasksque lo listan. - Escribir la tarea como la dirías:
POST /tasks/parsecon{"text": "llamar a Lucía mañana a las 10"}(ylanguagesi 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 conPOST /tasks. 30 por minuto. - Preferencias de quien llama:
GETyPUT /tasks/preferences:view(list,boardocalendar),daily_summary(enabled, apagado de serie;channels,emailopush; ytime) ydefault_remind_before_minutes. El resumen diario no sale por WhatsApp: aún no está disponible (422si lo pides).