Your AI Connector Docs

API-ul de sarcini

Sarcinile sunt activitățile și acțiunile de follow-up atașate contului tău — opțional legate de un contact, o tranzacție sau o campanie. Acestea trec prin etapele panoului tău de sarcini (coloanele tale kanban) și au un tip și o prioritate. Acest ghid acoperă gestionarea lor prin intermediul API-ului.

Toate exemplele de mai jos arată forma de interogare ?apiKey= în cURL și antetul X-API-Key în JavaScript și Python — oricare dintre ele funcționează pe fiecare endpoint.

Obiectul sarcină 

{
  "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 sau tipurile de sarcini configurate de tine (vezi List task types).
  • priority — none, low, normal, high sau urgent.
  • stage — id-ul unei etape de pe panoul de sarcini (vezi List task stages). Dacă este omis la creare, sarcina va fi plasată în prima etapă.
  • remind_before_minutes — numărul de minute înainte de due_date pentru trimiterea unui memento. 0 înseamnă la ora scadentă; omite-l sau trimite null pentru a nu primi niciun memento. Trebuie să fie un număr întreg de la 0 la 1440 (1 zi) — orice valoare mai mare va fi respinsă. Mementoul are nevoie de un due_date pentru a fi declanșat, iar reprogramarea sarcinii va muta și mementoul odată cu aceasta.

Crearea unei sarcini

POST /tasks — doar title este obligatoriu.

Notă: due_date acceptă un marcaj temporal ISO 8601, incluzând ora din zi. Asociază-l cu remind_before_minutes pentru a primi mementoul conform setărilor de notificare pentru Sarcini. contact_id, deal_id și campaign_id leagă sarcina de acele înregistrări. assigned_to este id-ul de utilizator al unui membru al echipei.

Configurarea corectă a assigned_to. Acesta trebuie să fie ID-ul de utilizator al proprietarului contului sau al unui membru activ al echipei din același cont. Acest endpoint nu verifică acest lucru în prezent, așa că un ID care nu aparține nimănui este acceptat și stocat exact așa cum l-ați trimis — veți primi totuși un 201. Copiați ID-ul în loc să îl tastați din nou: aceste ID-uri combină l cu L și litera O cu cifra 0, iar un singur caracter greșit este suficient. Pentru a verifica ce ați trimis efectiv, deschideți sarcina în tabloul de bord: câmpul Assignee (Responsabil) din înregistrarea sarcinii revine la afișarea ID-ului brut atunci când acesta nu corespunde nimănui, iar selectorul de responsabili din Edit task (Editare sarcină) afișează Unassigned (Neatribuit).

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

Răspuns (201)

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

Listarea sarcinilor

GET /tasks — returnează sarcinile pentru contul tău, cu filtre opționale.

Parametri de interogare (toți opționali): stage, priority, contact_id, deal_id, assigned_to, due_before, due_after (marcaje temporale 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"]

Răspuns (200)

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

Căutare sarcini

POST /tasks/search — potrivire text integral în titlu și descriere, cu aceleași filtre opționale ca la listare.

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

Obținerea unei sarcini

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

O sarcină care nu există în contul tău returnează 404.

Actualizarea unei sarcini

PUT /tasks/{taskId} — trimite doar câmpurile pe care dorești să le modifici (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."},
)

Finalizarea unei sarcini

POST /tasks/{taskId}/complete — mută sarcina în etapa de finalizare a panoului tău. Un câmp opțional notes înregistrează o notă de închidere.

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

Mutare și reordonare (kanban)

Mută o sarcină într-o altă etapă — POST /tasks/{taskId}/move cu new_stage_id (etapa de destinație) și new_position (poziția bazată pe zero în cadrul acelei etape; obligatoriu, trebuie să fie un număr întreg non-negativ):

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

Reordonează sarcinile în cadrul unei etape — POST /tasks/reorder cu stage_id și ID-urile sarcinilor în noua lor ordine:

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

Sarcini pentru un contact

GET /tasks/contact/{contactId} — fiecare sarcină legată de un contact.

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

Configurarea panoului de sarcini

Listează etapele sarcinilor

GET /tasks/stages — coloanele panoului tău, în ordine. Folosește un id de etapă ca și câmp stage atunci când creezi sau muți sarcini.

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

Actualizează etapele sarcinilor

PUT /tasks/stages — înlocuiește configurația etapelor panoului tău. Trimite matricea completă și ordonată stages.

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

Listează tipurile de sarcini

GET /tasks/types — tipurile de sarcini configurate în contul tău (folosite ca și câmp type).

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

Aprobă o sugestie pentru Întrebări frecvente (FAQ)

Atunci când botul AI propune o nouă întrebare frecventă (FAQ), acesta creează o sarcină de tip faq_update. POST /tasks/{taskId}/approve-faq transformă acea sugestie într-o întrebare frecventă reală în baza de cunoștințe a agentului AI care a generat-o și finalizează sarcina. Puteți suprascrie întrebarea/răspunsul în corpul mesajului.

Adăugați "send_follow_up": true pentru a face ca AI-ul să trimită răspunsul direct către contactul asociat sarcinii, sub forma unui mesaj natural în acel chat (același lucru pe care îl face comutatorul Trimite răspunsul către contact acum din aplicație). Răspunsul este transmis prin intermediul agentului AI care gestionează acel contact.

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 vă indică ce s-a întâmplat cu mesajul: not_requested (indicatorul nu este setat), published (trimis), queued (botul era în plin proces de răspuns către acel contact, răspunsul este trimis imediat ce termină), skipped_no_contact (sarcina nu are niciun contact asociat), skipped_no_campaign (niciun agent sau campanie nu a putut răspunde pentru acel contact) sau skipped_error. Întrebarea frecventă este creată în fiecare caz.

Consultă API-ul pentru Întrebări frecvente pentru a gestiona întrebarea frecventă rezultată.

Șterge o sarcină

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

Pașii următori

  • API Contacte — asociază sarcinile cu persoana de contact potrivită
  • API Webhooks — primește notificări despre Task Created, Task Updated și Task Completed
  • Referință API — exploratorul complet și interactiv al endpoint-urilor