Tickets
Gedeelde inbox, formulieren en automatiseringen voor klantverzoeken.
Met de ticket-API kan software buiten Xuda een bureau bedienen: een ticket openen, tickets tonen en lezen, beantwoorden, toewijzen, een ticket tussen fasen verplaatsen en sluiten, en de onderwerpen en het team lezen. Formulieren, workflows, AI-agents, interne notities en de instellingen blijven in het dashboard.
Elke aanroep is een POST naar https://xuda.ai/cpi/<method> met een JSON-body die je API-sleutel van het account meeneemt als api_key. Een aanroep werkt op het bureau van het account dat de sleutel bezit, onder het abonnement van dat bureau, en kan geen ander bureau noemen. Maak de sleutel in het dashboard onder Ontwikkelaars en houd hem uit pagina's en openbare code.
Het antwoord is { "code": ..., "data": ... }. Een positieve code is gelukt. Een weigering is een negatieve code met een zin in data.
name en details zijn verplicht. Een contact wordt gemaakt of hergebruikt op basis van email, het ticket wordt aangemaakt met de bron api, en het antwoord is een beperkt overzicht: nummer, id, status, fase, onderwerp, topic, aanvrager, de id van de toegewezen persoon en de tijdstempels. Interne id's en de status van automatisering worden nooit teruggegeven.
email is optioneel als een integratie of een agent het ticket voor zichzelf aanmaakt: stuur alleen een name, en er wordt geen contact gemaakt en niets naar de aanvrager gemaild.
Optionele velden geven het ticket een subject, phone, company, een topic_id en subtopic_id uit de onderwerpen van het bureau, je eigen reference_id, een priority van 1 (hoogste) tot 4, een type (issue, bug, feature of task) en attachments.
Om het nieuwe ticket aan iemand te geven, noem je die met assignee_uid of assignee_email, een van de twee. Die moeten in het werkruimteteam van het bureau zitten, dat is de eigenaar en de geaccepteerde leden van de werkruimte. Een geweigerde toegewezen persoon maakt geen ticket aan.
Tickets zoeken en lezen
ticket_api_list toont tickets met de filters die het dashboard heeft: status (open of closed), source, topic_id, type, assignee_uid, reference_id, een vrije-tekst search over onderwerp, details en ticketnummer, en een bereik created_from en created_to. Sorteer met sort (date_created_ts, last_activity_ts, status_ts of priority) en dir, en pagineer met limit (tot 500) en de bookmark uit het vorige antwoord.
ticket_api_get leest één ticket op ticket_id, met zijn openbare interacties. Interne notities en AI-concepten worden nooit teruggegeven.
ticket_api_topics geeft de onderwerpen en subonderwerpen van het bureau, zodat je eigen formulier dezelfde keuzelijst kan tonen als het gehoste formulier. ticket_api_team geeft de mensen aan wie een ticket kan worden toegewezen, elk met een uid, een naam en een e-mailadres.
ticket_api_replyplaatst altijd een openbaar antwoord, nooit een interne notitie. Het is het bureau dat antwoordt, tenzij jeas_requester: truemeegeeft, wat het plaatst als het eigen bericht van de aanvrager. In dat geval krijgt de toegewezen persoon, of de eigenaar van het bureau, een melding, en het telt niet als de eerste reactie van het bureau.ticket_api_set_stageverplaatst een open ticket naarnew,in_progress,waiting_customerofresolved. Een gesloten ticket wordt geweigerd, tenzij jereopen: truemeegeeft, wat het in die fase weer opent. De fase noemen die het ticket al heeft, verandert niets.ticket_api_assigngeeft een ticket aan een persoon in het team opassignee_uidofassignee_email. De huidige toegewezen persoon noemen verandert niets. Als meer dan één teamlid dat e-mailadres heeft, wordt de aanroep geweigerd met-409en geef je in plaats daarvan de uid mee.ticket_api_closesluit het ticket. De optionelereasonwordt aan de klant getoond. Een antwoord van de klant binnen de heropeningstermijn brengt het ticket terug.
De eigen lijst van het bureau lezen
get_support_tickets leest tickets terug naar het aangemelde account dat het bureau bezit, en kan met _id tot één ticket worden beperkt. Het heeft een andere vorm dan het overzicht van ticket_api_*, dat is gebouwd voor een aanroeper buiten Xuda.
Abonnementen en limieten
Het abonnement bepaalt wat een sleutel mag. Lezen (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) vraagt leestoegang, en schrijven (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) vraagt volledige toegang. Een abonnement zonder die toegang antwoordt -402. Elk abonnement heeft ook een aantal aanroepen per minuut, en daarboven wordt een aanroep tot de volgende minuut met -429 beantwoord. De geschiedenis volgt de bewaartermijn van het abonnement, dus een ticket dat ouder is kan niet worden gelezen. De pagina abonnementen heeft de cijfers.
Een nieuw ticket telt mee voor het tegoed van de maand, zoals bij elke andere ingang.