API de tareas

Las tareas son los pendientes y seguimientos asociados a tu cuenta, vinculados opcionalmente a un contacto, trato o campaña. Se mueven a través de las etapas de tu tablero de tareas (tus columnas kanban) y tienen un tipo y una prioridad. Esta guía cubre cómo gestionarlas a través de la API.

URL base — https://api.youraiconnector.com/v1
Autenticación — tu clave de API (consulta Autenticación)
Errores y paginación — consulta Errores y paginación

Todos los ejemplos a continuación muestran la forma de consulta ?apiKey= en cURL y el encabezado X-API-Key en JavaScript y Python; cualquiera de los dos funciona en todos los endpoints.

El objeto de tarea

{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}

type — to_do, faq_update o sus tipos de tarea configurados (consulte Listar tipos de tarea).
priority — none, low, normal, high o urgent.
stage — el id de una etapa en su tablero de tareas (consulte Listar etapas de tarea). Si se omite al crear, la tarea se coloca en su primera etapa.
remind_before_minutes — cuántos minutos antes de due_date enviar un recordatorio. 0 significa en la fecha de vencimiento; omítalo o envíe null para no recibir recordatorios. Debe ser un número entero de 0 a 1440 (1 día); cualquier valor mayor será rechazado. El recordatorio necesita un due_date para activarse, y reprogramar la tarea mueve el recordatorio junto con ella.

Crear una tarea

POST /tasks — solo se requiere title.

Nota: due_date acepta una marca de tiempo ISO 8601, incluida una hora del día. Combínelo con remind_before_minutes para que el recordatorio se entregue según su configuración de notificaciones de Tareas. contact_id, deal_id y campaign_id vinculan la tarea a esos registros. assigned_to es el id de usuario de un miembro del equipo.

Configurar assigned_to correctamente. Debe ser el id de usuario del propietario de la cuenta o de un miembro activo del equipo en la misma cuenta. Actualmente, este endpoint no realiza esa comprobación, por lo que se acepta y almacena un id que no pertenece a nadie tal cual lo enviaste; aun así, obtendrás un 201. Copia el id en lugar de volver a escribirlo: estos ids mezclan l con L y la letra O con el dígito 0, y basta con un carácter incorrecto. Para comprobar lo que enviaste realmente, abre la tarea en el panel de control: el campo Asignado a en el registro de la tarea vuelve a mostrar el id sin procesar cuando no coincide con nadie, y el selector de asignado en Editar tarea muestra Sin asignar.

cURL

curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])

Respuesta (201)

{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }

Listar tareas

GET /tasks — devuelve las tareas de tu cuenta, con filtros opcionales.

Parámetros de consulta (todos opcionales): stage, priority, contact_id, deal_id, assigned_to, due_before, due_after (marcas de tiempo ISO), status, include.

Solo abiertas o finalizadas. Añada status=open para obtener solo las tareas que no están en una etapa de Finalizado (una tarea sin etapa, o una etapa que haya eliminado desde entonces, cuenta como abierta), o status=completed para solo aquellas en una etapa de Finalizado. Omítalo para obtener todas las tareas. Cualquier otro valor devuelve un 400.

Nombrar el contacto vinculado. Una tarea lleva su contacto como referencia, por lo que listar un tablero y mostrar a quién se refiere cada tarea solía significar obtener cada contacto por separado. Añada include=contact y cada tarea se devolverá con contact_name, contact_phone, contact_email y contact_channel completados a partir del contacto vinculado. Las tareas sin contacto, o cuyo contacto haya sido eliminado, simplemente no llevan los campos.

cURL

curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"

# with the linked contact resolved
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&include=contact"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]

Respuesta (200)

{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }

Buscar tareas

POST /tasks/search — coincidencia de texto completo en el título y la descripción, con los mismos filtros opcionales que al listar. "include": "contact" en el cuerpo también funciona aquí, y completa el nombre, teléfono, correo electrónico y canal del contacto vinculado en cada coincidencia.

curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'

const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)

Obtener una tarea

GET /tasks/{taskId}

curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });

res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})

Una tarea que no existe en su cuenta devuelve 404.

Actualizar una tarea

PUT /tasks/{taskId} — envíe solo los campos que desea cambiar (title, description, type, priority, stage, due_date, remind_before_minutes, contact_id, deal_id, assigned_to, tags, notes).

curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});

requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)

Completar una tarea

POST /tasks/{taskId}/complete — mueve la tarea a la etapa de completadas de su tablero. Un campo opcional notes registra una nota de cierre.

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});

requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)

Mover y reordenar (kanban)

Mover una tarea a otra etapa — POST /tasks/{taskId}/move con new_stage_id (la etapa de destino) y new_position (la posición basada en cero dentro de esa etapa; obligatorio, debe ser un número entero no negativo):

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'

Reordenar tareas dentro de una etapa — POST /tasks/reorder con stage_id y los identificadores de las tareas en su nuevo orden:

curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'

await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});

requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)

Tareas para un contacto

GET /tasks/contact/{contactId} — cada tarea vinculada a un contacto.

curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });

res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})

Configuración del tablero de tareas

Listar etapas de tareas

GET /tasks/stages — las columnas de su tablero, en orden. Utilice un id de etapa como campo stage al crear o mover tareas.

curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"

{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }

Actualizar etapas de tareas

PUT /tasks/stages — reemplace la configuración de etapas de su tablero. Envíe la matriz stages ordenada completa.

curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'

Listar tipos de tareas

GET /tasks/types — los tipos de tareas configurados en su cuenta (utilizados como campo type).

curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"

Aprobar una sugerencia de preguntas frecuentes

Cuando el bot de IA propone una nueva pregunta frecuente, crea una tarea de tipo faq_update. POST /tasks/{taskId}/approve-faq convierte esa sugerencia en una pregunta frecuente real en la base de conocimientos del agente de IA que la generó y completa la tarea. Puedes sobrescribir la pregunta/respuesta en el cuerpo.

Añada "send_follow_up": true para que la IA también envíe la respuesta al contacto vinculado a la tarea de inmediato, como un mensaje natural en ese chat (lo mismo que hace el interruptor Enviar la respuesta al contacto ahora en la aplicación). La respuesta se envía a través del agente de IA que gestiona ese contacto. El ajuste del bot del contacto se mantiene como estaba: en un contacto donde la IA está pausada, se envía esta única respuesta y la IA permanece pausada.

curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'

{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }

follow_up_status le indica qué sucedió con el mensaje: not_requested (indicador no establecido), published (enviado), queued (el bot estaba respondiendo a ese contacto, la respuesta se envía tan pronto como termine), skipped_no_contact (la tarea no tiene un contacto vinculado), skipped_no_campaign (ningún agente o campaña pudo responder por ese contacto) o skipped_error. La FAQ se crea en todos los casos.

Consulte la API de preguntas frecuentes para gestionar la pregunta frecuente resultante.

Eliminar una tarea

DELETE /tasks/{taskId}

curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"

await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });

requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})

Próximos pasos

API de contactos — vincule tareas al contacto correcto
API de webhooks — reciba notificaciones sobre Task Created, Task Updated y Task Completed
Referencia de la API — el explorador interactivo completo de endpoints

API de tareas #

El objeto de tarea #

Crear una tarea #

Listar tareas #

Buscar tareas #

Obtener una tarea #

Actualizar una tarea #

Completar una tarea #

Mover y reordenar (kanban) #

Tareas para un contacto #

Configuración del tablero de tareas #

Listar etapas de tareas #

Actualizar etapas de tareas #

Listar tipos de tareas #

Aprobar una sugerencia de preguntas frecuentes #

Eliminar una tarea #

Próximos pasos #

API de tareas

El objeto de tarea

Crear una tarea

Listar tareas

Buscar tareas

Obtener una tarea

Actualizar una tarea

Completar una tarea

Mover y reordenar (kanban)

Tareas para un contacto

Configuración del tablero de tareas

Listar etapas de tareas

Actualizar etapas de tareas

Listar tipos de tareas

Aprobar una sugerencia de preguntas frecuentes

Eliminar una tarea

Próximos pasos