API de Tarefas

As tarefas são os afazeres e seguimentos associados à sua conta — opcionalmente ligados a um contacto, negócio ou campanha. Estas movem-se através das etapas do seu quadro de tarefas (as suas colunas kanban) e possuem um tipo e uma prioridade. Este guia aborda a sua gestão através da API.

URL Base — https://api.youraiconnector.com/v1
Autenticação — a sua chave de API (ver Autenticação)
Erros e paginação — ver Erros e Paginação

Todos os exemplos abaixo mostram o formato de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — qualquer um funciona em todos os endpoints.

O objeto de tarefa

{
  "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 ou os seus tipos de tarefa configurados (consulte Listar tipos de tarefa).
priority — none, low, normal, high ou urgent.
stage — o id de uma fase no seu quadro de tarefas (consulte Listar fases de tarefa). Quando omitido na criação, a tarefa é colocada na sua primeira fase.
remind_before_minutes — quantos minutos antes de due_date enviar um lembrete. 0 significa na hora de conclusão; omita-o ou envie null para não receber lembretes. Deve ser um número inteiro de 0 a 1440 (1 dia) — qualquer valor superior será rejeitado. O lembrete necessita de um due_date para ser ativado, e reagendar a tarefa move o lembrete juntamente com a mesma.

Criar uma tarefa

POST /tasks — apenas title é obrigatório.

Nota: due_date aceita um carimbo de data/hora ISO 8601, incluindo a hora do dia. Combine-o com remind_before_minutes para que o lembrete seja entregue nas suas definições de notificação de Tarefas. contact_id, deal_id e campaign_id associam a tarefa a esses registos. assigned_to é o id de utilizador de um membro da equipa.

Obter o assigned_to correto. Deve ser o ID de utilizador do proprietário da conta ou de um membro ativo da equipa na mesma conta. Este endpoint não verifica isso atualmente, pelo que um ID que não pertence a ninguém é aceite e armazenado exatamente como o enviou — continuará a receber um 201. Copie o ID em vez de o escrever novamente: estes IDs misturam l com L e a letra O com o dígito 0, e um caráter errado é suficiente. Para verificar o que enviou realmente, abra a tarefa no painel: o campo Responsável no registo da tarefa volta a mostrar o ID bruto quando não corresponde a ninguém, e o seletor de responsável em Editar tarefa mostra Não atribuído.

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"])

Resposta (201)

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

Listar tarefas

GET /tasks — devolve as tarefas da sua conta, com filtros opcionais.

Parâmetros de consulta (todos opcionais): stage, priority, contact_id, deal_id, assigned_to, due_before, due_after (carimbos de data/hora ISO).

cURL

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

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"]

Resposta (200)

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

Pesquisar tarefas

POST /tasks/search — correspondência de texto completo no título e na descrição, com os mesmos filtros opcionais da listagem.

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"},
)

Obter uma tarefa

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"})

Uma tarefa que não existe na sua conta devolve 404.

Atualizar uma tarefa

PUT /tasks/{taskId} — envie apenas os campos que pretende alterar (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."},
)

Concluir uma tarefa

POST /tasks/{taskId}/complete — move a tarefa para a fase de concluídas do seu quadro. Um campo opcional notes regista uma nota de encerramento.

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 e reordenar (kanban)

Mover uma tarefa para outra fase — POST /tasks/{taskId}/move com new_stage_id (a fase de destino) e new_position (a posição baseada em zero dentro dessa fase; obrigatório, deve ser um número inteiro não 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 tarefas dentro de uma fase — POST /tasks/reorder com stage_id e os IDs das tarefas na sua nova ordem:

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"]},
)

Tarefas para um contacto

GET /tasks/contact/{contactId} — todas as tarefas associadas a um 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"})

Configuração do quadro de tarefas

Listar fases das tarefas

GET /tasks/stages — as colunas do seu quadro, por ordem. Utilize um id de fase como campo stage ao criar ou mover tarefas.

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 }] }

Atualizar fases das tarefas

PUT /tasks/stages — substituir a configuração de fases do seu quadro. Envie a matriz stages completa e ordenada.

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 tarefas

GET /tasks/types — os tipos de tarefas configurados na sua conta (utilizados como campo type).

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

Aprovar uma sugestão de FAQ

Quando o bot de IA propõe uma nova FAQ, cria uma tarefa do tipo faq_update. O POST /tasks/{taskId}/approve-faq transforma essa sugestão numa FAQ real na base de conhecimento do agente de IA que a gerou e conclui a tarefa. Pode substituir a pergunta/resposta no corpo da mensagem.

Adicione "send_follow_up": true para que a IA envie também a resposta ao contacto associado à tarefa imediatamente, como uma mensagem natural nessa conversa (o mesmo que o botão Enviar a resposta ao contacto agora faz na aplicação). A resposta é enviada através do agente de IA que gere esse contacto.

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 indica-lhe o que aconteceu à mensagem: not_requested (sinalizador não definido), published (enviada), queued (o bot estava a meio de uma resposta a esse contacto, a resposta será enviada assim que terminar), skipped_no_contact (a tarefa não tem nenhum contacto associado), skipped_no_campaign (nenhum agente ou campanha pôde responder por esse contacto) ou skipped_error. A FAQ é criada em todos os casos.

Consulte a API de FAQs para gerir a FAQ resultante.

Eliminar uma tarefa

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 passos

API de Contactos — associe tarefas ao contacto correto
API de Webhooks — receba notificações sobre Task Created, Task Updated e Task Completed
Referência da API — o explorador interativo completo de endpoints

API de Tarefas #

O objeto de tarefa #

Criar uma tarefa #

Listar tarefas #

Pesquisar tarefas #

Obter uma tarefa #

Atualizar uma tarefa #

Concluir uma tarefa #

Mover e reordenar (kanban) #

Tarefas para um contacto #

Configuração do quadro de tarefas #

Listar fases das tarefas #

Atualizar fases das tarefas #

Listar tipos de tarefas #

Aprovar uma sugestão de FAQ #

Eliminar uma tarefa #

Próximos passos #

API de Tarefas

O objeto de tarefa

Criar uma tarefa

Listar tarefas

Pesquisar tarefas

Obter uma tarefa

Atualizar uma tarefa

Concluir uma tarefa

Mover e reordenar (kanban)

Tarefas para um contacto

Configuração do quadro de tarefas

Listar fases das tarefas

Atualizar fases das tarefas

Listar tipos de tarefas

Aprovar uma sugestão de FAQ

Eliminar uma tarefa

Próximos passos