Tickets
Gemeinsames Postfach, Formulare und Automatisierungen für Kundenanfragen.
Die Ticket-API lässt Software außerhalb von Xuda einen Desk bedienen: ein Ticket öffnen, Tickets auflisten und lesen, antworten, zuweisen, ein Ticket zwischen Phasen verschieben und schließen sowie die Themen und das Team lesen. Formulare, Workflows, KI-Agenten, interne Notizen und die Einstellungen bleiben im Dashboard.
Jeder Aufruf ist ein POST an https://xuda.ai/cpi/<method> mit einem JSON-Body, der den API-Schlüssel deines Kontos als api_key enthält. Ein Aufruf wirkt auf den Desk des Kontos, dem der Schlüssel gehört, unter dem Tarif dieses Desks, und kann keinen anderen Desk benennen. Erstelle den Schlüssel im Dashboard unter Entwickler und halte ihn aus Seiten und öffentlichem Code heraus.
Die Antwort ist { "code": ..., "data": ... }. Ein positiver code ist Erfolg. Eine Ablehnung ist ein negativer Code mit einem Satz in data.
name und details sind Pflicht. Aus email wird ein Kontakt erstellt oder wiederverwendet, das Ticket wird mit der Quelle api angelegt, und die Antwort ist eine schmale Ansicht: Nummer, ID, Status, Phase, Betreff, Thema, anfragende Person, die ID des Zuständigen und die Zeitstempel. Interne IDs und der Zustand der Automatisierung werden nie zurückgegeben.
email ist optional, wenn eine Integration oder ein Agent das Ticket für sich selbst anlegt: Sende nur einen name, dann wird kein Kontakt erstellt und der anfragenden Person nichts gemailt.
Optionale Felder geben dem Ticket einen subject, phone, company, eine topic_id und subtopic_id aus den Themen des Desks, deine eigene reference_id, eine priority von 1 (höchste) bis 4, einen type (issue, bug, feature oder task) und attachments.
Um das neue Ticket jemandem zu übergeben, nenne die Person mit assignee_uid oder assignee_email, eines von beiden. Sie muss im Workspace-Team des Desks sein, das sind sein Eigentümer und die angenommenen Mitglieder des Workspace. Ein abgelehnter Zuständiger legt kein Ticket an.
Tickets finden und lesen
ticket_api_list listet Tickets mit den Filtern auf, die das Dashboard hat: status (open oder closed), source, topic_id, type, assignee_uid, reference_id, eine Freitext-search über Betreff, Details und Ticketnummer sowie einen Bereich created_from und created_to. Sortiere mit sort (date_created_ts, last_activity_ts, status_ts oder priority) und dir, und blättere mit limit (bis zu 500) und dem bookmark aus der vorigen Antwort.
ticket_api_get liest ein Ticket über ticket_id, mit seinen öffentlichen Interaktionen. Interne Notizen und KI-Entwürfe werden nie zurückgegeben.
ticket_api_topics gibt die Themen und Unterthemen des Desks zurück, damit dein eigenes Formular dieselbe Auswahl zeigen kann wie das gehostete Formular. ticket_api_team gibt die Personen zurück, denen ein Ticket zugewiesen werden kann, jeweils mit einer uid, einem Namen und einer E-Mail.
ticket_api_replypostet immer eine öffentliche Antwort, nie eine interne Notiz. Es antwortet der Desk, es sei denn, du übergibstas_requester: true, das sie als eigene Nachricht der anfragenden Person postet. In diesem Fall wird der Zuständige oder der Eigentümer des Desks benachrichtigt, und es zählt nicht als erste Antwort des Desks.ticket_api_set_stageverschiebt ein offenes Ticket aufnew,in_progress,waiting_customeroderresolved. Ein geschlossenes Ticket wird abgelehnt, es sei denn, du übergibstreopen: true, das es in dieser Phase wieder öffnet. Die Phase zu nennen, die das Ticket schon hat, ändert nichts.ticket_api_assigngibt ein Ticket überassignee_uidoderassignee_emailan eine Person im Team. Den aktuellen Zuständigen zu nennen ändert nichts. Wenn mehr als ein Teammitglied diese E-Mail hat, wird der Aufruf mit-409abgelehnt, und du übergibst stattdessen die uid.ticket_api_closeschließt das Ticket. Der optionalereasonwird dem Kunden angezeigt. Eine Antwort des Kunden innerhalb des Wiedereröffnungsfensters bringt das Ticket zurück.
Die eigene Liste des Desks lesen
get_support_tickets liest Tickets für das angemeldete Konto zurück, dem der Desk gehört, und lässt sich mit _id auf ein Ticket beschränken. Es hat eine andere Form als die Ansicht ticket_api_*, die für einen Aufrufer außerhalb von Xuda gebaut ist.
Tarife und Limits
Der Tarif bestimmt, was ein Schlüssel darf. Lesen (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) braucht Lesezugriff, und Schreiben (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) braucht vollen Zugriff. Ein Tarif ohne ihn antwortet mit -402. Jeder Tarif hat außerdem eine Anzahl Aufrufe pro Minute, und darüber wird ein Aufruf bis zur nächsten Minute mit -429 beantwortet. Der Verlauf folgt dem Aufbewahrungsfenster des Tarifs, daher kann ein Ticket, das älter ist, nicht gelesen werden. Die Seite Tarife nennt die Zahlen.
Ein neues Ticket zählt auf das Monatskontingent, wie bei jedem anderen Zugangsweg.