Aufgaben-API

Aufgaben sind die To-dos und Nachverfolgungen, die mit Ihrem Konto verknüpft sind – optional verbunden mit einem Kontakt, einem Deal oder einer Kampagne. Sie durchlaufen die Phasen Ihres Aufgaben-Boards (Ihre Kanban-Spalten) und besitzen einen Typ sowie eine Priorität. Dieser Leitfaden beschreibt deren Verwaltung über die API.

Basis-URL — https://api.youraiconnector.com/v1
Authentifizierung — Ihr API-Schlüssel (siehe Authentifizierung)
Fehler & Paginierung — siehe Fehler & Paginierung

Alle nachstehenden Beispiele zeigen die ?apiKey=-Abfrageform in cURL und den X-API-Key-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Das Aufgaben-Objekt

{
  "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 oder Ihre konfigurierten Aufgabentypen (siehe Aufgabentypen auflisten).
priority — none, low, normal, high oder urgent.
stage — die ID einer Phase auf Ihrem Aufgabenboard (siehe Aufgabenphasen auflisten). Wenn dies beim Erstellen weggelassen wird, landet die Aufgabe in Ihrer ersten Phase.
remind_before_minutes — wie viele Minuten vor due_date eine Erinnerung gesendet werden soll. 0 bedeutet zum Fälligkeitszeitpunkt; lassen Sie es weg oder senden Sie null für keine Erinnerung. Muss eine ganze Zahl von 0 bis 1440 (1 Tag) sein — alles, was größer ist, wird abgelehnt. Die Erinnerung benötigt ein due_date, um ausgelöst zu werden, und eine Terminverschiebung der Aufgabe verschiebt die Erinnerung mit.

Aufgabe erstellen

POST /tasks — nur title ist erforderlich.

Hinweis: due_date akzeptiert einen ISO 8601-Zeitstempel, einschließlich einer Tageszeit. Kombinieren Sie dies mit remind_before_minutes, damit die Erinnerung gemäß Ihren Aufgaben-Benachrichtigungseinstellungen zugestellt wird. contact_id, deal_id und campaign_id verknüpfen die Aufgabe mit diesen Datensätzen. assigned_to ist die Benutzer-ID eines Teammitglieds.

Richtiges assigned_to. Es sollte die Benutzer-ID des Kontoinhabers oder eines aktiven Teammitglieds auf demselben Konto sein. Dieser Endpunkt überprüft dies derzeit nicht, daher wird eine ID, die niemandem gehört, akzeptiert und genau so gespeichert, wie Sie sie gesendet haben – Sie erhalten trotzdem eine 201. Kopieren Sie die ID, anstatt sie abzutippen: Diese IDs mischen l mit L und den Buchstaben O mit der Ziffer 0, und ein falsches Zeichen reicht bereits aus. Um zu überprüfen, was Sie tatsächlich gesendet haben, öffnen Sie die Aufgabe im Dashboard: Das Feld Bearbeiter im Aufgabendatensatz zeigt die rohe ID an, wenn sie zu niemandem passt, und die Auswahl für den Bearbeiter unter Aufgabe bearbeiten zeigt Nicht zugewiesen an.

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

Antwort (201)

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

Aufgaben auflisten

GET /tasks — gibt die Aufgaben für Ihr Konto zurück, mit optionalen Filtern.

Abfrageparameter (alle optional): stage, priority, contact_id, deal_id, assigned_to, due_before, due_after (ISO-Zeitstempel).

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

Antwort (200)

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

Aufgaben suchen

POST /tasks/search — Volltextsuche in Titel und Beschreibung, mit denselben optionalen Filtern wie bei der Auflistung.

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

Eine Aufgabe abrufen

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

Eine Aufgabe, die nicht in Ihrem Konto existiert, gibt 404 zurück.

Eine Aufgabe aktualisieren

PUT /tasks/{taskId} — senden Sie nur die Felder, die Sie ändern möchten (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."},
)

Eine Aufgabe abschließen

POST /tasks/{taskId}/complete — verschiebt die Aufgabe in die Phase „Abgeschlossen“ Ihres Boards. Ein optionales Feld notes protokolliert eine Abschlussnotiz.

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

Verschieben & neu anordnen (Kanban)

Verschieben einer Aufgabe in eine andere Phase — POST /tasks/{taskId}/move mit new_stage_id (der Zielphase) und new_position (dem nullbasierten Slot innerhalb dieser Phase; erforderlich, muss eine nicht-negative Ganzzahl sein):

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

Neuordnen von Aufgaben innerhalb einer Phase — POST /tasks/reorder mit stage_id und den Aufgaben-IDs in ihrer neuen Reihenfolge:

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

Aufgaben für einen Kontakt

GET /tasks/contact/{contactId} — jede Aufgabe ist mit einem Kontakt verknüpft.

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

Konfiguration des Aufgaben-Boards

Auflisten der Aufgabenphasen

GET /tasks/stages — die Spalten Ihres Boards in der entsprechenden Reihenfolge. Verwenden Sie eine Phasen-id als stage-Feld beim Erstellen oder Verschieben von Aufgaben.

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

Aktualisieren der Aufgabenphasen

PUT /tasks/stages — Ersetzen der Phasenkonfiguration Ihres Boards. Senden Sie das vollständige sortierte stages-Array.

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

Auflisten der Aufgabentypen

GET /tasks/types — die in Ihrem Konto konfigurierten Aufgabentypen (verwendet als type-Feld).

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

Genehmigen eines FAQ-Vorschlags

Wenn der KI-Bot eine neue FAQ vorschlägt, erstellt er eine Aufgabe vom Typ faq_update. POST /tasks/{taskId}/approve-faq wandelt diesen Vorschlag in eine echte FAQ in der Wissensdatenbank des KI-Agenten um, der ihn erstellt hat, und schließt die Aufgabe ab. Sie können die Frage/Antwort im Textkörper überschreiben.

Fügen Sie "send_follow_up": true hinzu, damit die KI die Antwort auch sofort an den mit der Aufgabe verknüpften Kontakt sendet, als natürliche Nachricht in diesem Chat (dasselbe, was der Schalter Antwort jetzt an den Kontakt senden in der App bewirkt). Die Antwort wird über den KI-Agenten gesendet, der diesen Kontakt bearbeitet.

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 teilt Ihnen mit, was mit der Nachricht passiert ist: not_requested (Flag nicht gesetzt), published (gesendet), queued (der Bot war gerade dabei, diesem Kontakt zu antworten; die Antwort wird gesendet, sobald er fertig ist), skipped_no_contact (die Aufgabe hat keinen verknüpften Kontakt), skipped_no_campaign (kein Agent oder keine Kampagne konnte für diesen Kontakt antworten) oder skipped_error. Das FAQ wird in jedem Fall erstellt.

Siehe die FAQs-API, um die resultierende FAQ zu verwalten.

Löschen einer Aufgabe

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

Nächste Schritte

Kontakte-API — Verknüpfen Sie Aufgaben mit dem richtigen Kontakt
Webhooks-API — Lassen Sie sich über Task Created, Task Updated und Task Completed benachrichtigen
API-Referenz — Der vollständige interaktive Endpunkt-Explorer

Aufgaben-API #

Das Aufgaben-Objekt #

Aufgabe erstellen #

Aufgaben auflisten #

Aufgaben suchen #

Eine Aufgabe abrufen #

Eine Aufgabe aktualisieren #

Eine Aufgabe abschließen #

Verschieben & neu anordnen (Kanban) #

Aufgaben für einen Kontakt #

Konfiguration des Aufgaben-Boards #

Auflisten der Aufgabenphasen #

Aktualisieren der Aufgabenphasen #

Auflisten der Aufgabentypen #

Genehmigen eines FAQ-Vorschlags #

Löschen einer Aufgabe #

Nächste Schritte #

Aufgaben-API

Das Aufgaben-Objekt

Aufgabe erstellen

Aufgaben auflisten

Aufgaben suchen

Eine Aufgabe abrufen

Eine Aufgabe aktualisieren

Eine Aufgabe abschließen

Verschieben & neu anordnen (Kanban)

Aufgaben für einen Kontakt

Konfiguration des Aufgaben-Boards

Auflisten der Aufgabenphasen

Aktualisieren der Aufgabenphasen

Auflisten der Aufgabentypen

Genehmigen eines FAQ-Vorschlags

Löschen einer Aufgabe

Nächste Schritte