Tickets
Boîte de réception partagée, formulaires et automatisations pour les demandes clients.
L'API de tickets permet à un logiciel extérieur à Xuda de faire fonctionner un bureau : ouvrir un ticket, lister et lire des tickets, répondre, confier, déplacer un ticket entre les étapes et le fermer, et lire les sujets et l'équipe. Les formulaires, les workflows, les agents IA, les notes internes et les paramètres restent dans le tableau de bord.
Chaque appel est un POST vers https://xuda.ai/cpi/<method> avec un corps JSON qui porte la clé API de votre compte comme api_key. Un appel agit sur le bureau du compte qui possède la clé, selon le forfait de ce bureau, et ne peut pas désigner un autre bureau. Créez la clé dans le tableau de bord sous Développeurs, et gardez-la hors des pages et du code public.
La réponse est { "code": ..., "data": ... }. Un code positif signifie un succès. Un refus est un code négatif avec une phrase dans data.
name et details sont obligatoires. Un contact est créé ou réutilisé à partir de email, le ticket est déposé avec la source api, et la réponse est une vue restreinte : numéro, identifiant, statut, étape, objet, sujet, demandeur, l'identifiant du responsable et les horodatages. Les identifiants internes et l'état de l'automatisation ne sont jamais renvoyés.
email est facultatif quand une intégration ou un agent dépose le ticket pour lui-même : envoyez seulement un name, et aucun contact n'est créé et rien n'est envoyé par e-mail au demandeur.
Des champs facultatifs donnent au ticket un subject, phone, company, un topic_id et un subtopic_id parmi les sujets du bureau, votre propre reference_id, une priority de 1 (la plus haute) à 4, un type (issue, bug, feature ou task) et des attachments.
Pour confier le nouveau ticket à quelqu'un, nommez la personne avec assignee_uid ou assignee_email, l'un des deux. Elle doit faire partie de l'équipe de l'espace de travail du bureau, c'est-à-dire son propriétaire et les membres acceptés de l'espace de travail. Un responsable refusé ne dépose aucun ticket.
Trouver et lire des tickets
ticket_api_list liste les tickets avec les filtres du tableau de bord : status (open ou closed), source, topic_id, type, assignee_uid, reference_id, un search en texte libre sur l'objet, les détails et le numéro de ticket, et une plage created_from et created_to. Triez avec sort (date_created_ts, last_activity_ts, status_ts ou priority) et dir, et paginez avec limit (jusqu'à 500) et le bookmark de la réponse précédente.
ticket_api_get lit un ticket par ticket_id, avec ses interactions publiques. Les notes internes et les brouillons de l'IA ne sont jamais renvoyés.
ticket_api_topics renvoie les sujets et sous-sujets du bureau, pour que votre propre formulaire puisse afficher le même sélecteur que le formulaire hébergé. ticket_api_team renvoie les personnes à qui un ticket peut être confié, chacune avec un uid, un nom et une adresse e-mail.
ticket_api_replypublie toujours une réponse publique, jamais une note interne. C'est le bureau qui répond, sauf si vous passezas_requester: true, ce qui la publie comme message du demandeur lui-même. Dans ce cas, le responsable, ou le propriétaire du bureau, est notifié, et elle ne compte pas comme première réponse du bureau.ticket_api_set_stagedéplace un ticket ouvert versnew,in_progress,waiting_customerouresolved. Un ticket fermé est refusé sauf si vous passezreopen: true, ce qui le rouvre à cette étape. Nommer l'étape que le ticket a déjà ne change rien.ticket_api_assignconfie un ticket à une personne de l'équipe parassignee_uidouassignee_email. Nommer le responsable actuel ne change rien. Si plusieurs membres de l'équipe ont cette adresse e-mail, l'appel est refusé avec-409et vous passez l'uid à la place.ticket_api_closeferme le ticket. Lereasonfacultatif est montré au client. Une réponse du client dans le délai de réouverture ramène le ticket.
Lire la liste propre du bureau
get_support_tickets relit les tickets pour le compte connecté qui possède le bureau, et peut être limitée à un ticket avec _id. Sa forme diffère de la vue ticket_api_*, qui est conçue pour un appelant extérieur à Xuda.
Forfaits et limites
Le forfait décide de ce qu'une clé peut faire. La lecture (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) demande un accès en lecture, et l'écriture (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) demande un accès complet. Un forfait qui ne l'a pas répond -402. Chaque forfait a aussi un nombre d'appels par minute, et au-delà un appel reçoit -429 jusqu'à la minute suivante. L'historique suit la fenêtre de conservation du forfait, donc un ticket plus ancien ne peut pas être lu. La page des forfaits donne les chiffres.
Un nouveau ticket compte dans le quota du mois, comme par n'importe quel autre point d'entrée.