API de Tarefas

Tarefas são os itens a fazer e acompanhamentos vinculados à sua conta — opcionalmente associados a um contato, negócio ou campanha. Elas avançam pelos estágios do seu quadro de tarefas (suas colunas kanban) e possuem um tipo e uma prioridade. Este guia aborda como gerenciá-las via API.

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

Todos os exemplos abaixo mostram a forma de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — ambos funcionam 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 seus tipos de tarefa configurados (consulte Listar tipos de tarefa).
priority — none, low, normal, high ou urgent.
stage — o id de uma etapa no seu quadro de tarefas (consulte Listar etapas de tarefa). Quando omitido na criação, a tarefa é colocada na sua primeira etapa.
remind_before_minutes — quantos minutos antes de due_date enviar um lembrete. 0 significa no horário de vencimento; omita ou envie null para nenhum lembrete. Deve ser um número inteiro de 0 a 1440 (1 dia) — qualquer valor maior será rejeitado. O lembrete precisa de um due_date para ser disparado, e reagendar a tarefa move o lembrete junto com ela.

Criar uma tarefa

POST /tasks — apenas title é obrigatório.

Nota: due_date aceita um carimbo de data/hora ISO 8601, incluindo um horário do dia. Combine-o com remind_before_minutes para que o lembrete seja entregue nas suas configurações de notificação de Tarefas. contact_id, deal_id e campaign_id vinculam a tarefa a esses registros. assigned_to é o id de usuário de um membro da equipe.

Definindo o assigned_to corretamente. Deve ser o ID de usuário do proprietário da conta ou de um membro ativo da equipe na mesma conta. Este endpoint atualmente não verifica isso, portanto, um ID que não pertence a ninguém é aceito e armazenado exatamente como você o enviou — você ainda recebe um 201. Copie o ID em vez de redigitá-lo: esses IDs misturam l com L e a letra O com o dígito 0, e um caractere errado é o suficiente. Para verificar o que você realmente enviou, abra a tarefa no painel: o campo Responsável no registro 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 — retorna 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 (timestamps 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 retorna 404.

Atualizar uma tarefa

PUT /tasks/{taskId} — envie apenas os campos que deseja 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 o estágio de concluídas do seu quadro. Um campo opcional notes registra uma nota de fechamento.

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)

Mova uma tarefa para outro estágio — POST /tasks/{taskId}/move com new_stage_id (o estágio de destino) e new_position (a posição baseada em zero dentro desse estágio; 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 }'

Reordene tarefas dentro de um estágio — POST /tasks/reorder com stage_id e os IDs das tarefas em 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 contato

GET /tasks/contact/{contactId} — cada tarefa vinculada a um contato.

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 estágios de tarefa

GET /tasks/stages — as colunas do seu quadro, em ordem. Use um id de estágio como o 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 estágios de tarefa

PUT /tasks/stages — substitua a configuração de estágio do seu quadro. Envie o array stages completo e ordenado.

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 tarefa

GET /tasks/types — os tipos de tarefa configurados em sua conta (usados como o 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, ele cria uma tarefa do tipo faq_update. O POST /tasks/{taskId}/approve-faq transforma essa sugestão em uma FAQ real na base de conhecimento do agente de IA que a gerou e conclui a tarefa. Você pode substituir a pergunta/resposta no corpo.

Adicione "send_follow_up": true para também fazer com que a IA envie a resposta ao contato vinculado à tarefa imediatamente, como uma mensagem natural naquele chat (a mesma coisa que a opção Enviar a resposta ao contato agora faz no aplicativo). A resposta é enviada pelo agente de IA que gerencia esse contato.

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 informa o que aconteceu com a mensagem: not_requested (flag não definida), published (enviada), queued (o bot estava respondendo a esse contato, a resposta será enviada assim que ele terminar), skipped_no_contact (a tarefa não possui contato vinculado), skipped_no_campaign (nenhum agente ou campanha pôde responder por esse contato) ou skipped_error. A FAQ é criada em todos os casos.

Consulte a API de FAQs para gerenciar a FAQ resultante.

Excluir 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 Contatos — vincule tarefas ao contato correto
API de Webhooks — seja notificado sobre Task Created, Task Updated e Task Completed
Referência da API — o explorador de endpoints interativo completo

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 contato #

Configuração do quadro de tarefas #

Listar estágios de tarefa #

Atualizar estágios de tarefa #

Listar tipos de tarefa #

Aprovar uma sugestão de FAQ #

Excluir 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 contato

Configuração do quadro de tarefas

Listar estágios de tarefa

Atualizar estágios de tarefa

Listar tipos de tarefa

Aprovar uma sugestão de FAQ

Excluir uma tarefa

Próximos passos