Tickets
Casella condivisa, moduli e automazioni per le richieste dei clienti.
L'API dei ticket permette a un software esterno a Xuda di lavorare un help desk: aprire un ticket, elencare e leggere i ticket, rispondere, assegnare, spostare un ticket tra le fasi e chiuderlo, e leggere gli argomenti e il team. Moduli, flussi di lavoro, agenti AI, note interne e impostazioni restano nella dashboard.
Ogni chiamata è una POST a https://xuda.ai/cpi/<method> con un corpo JSON che porta la chiave API del tuo conto come api_key. Una chiamata lavora sull'help desk del conto che possiede la chiave, secondo il piano di quell'help desk, e non può nominarne un altro. Crea la chiave nella dashboard in Sviluppatori e tienila fuori da pagine e codice pubblico.
La risposta è { "code": ..., "data": ... }. Un code positivo indica successo. Un rifiuto è un codice negativo con una frase in data.
name e details sono obbligatori. Un contatto viene creato o riutilizzato a partire da email, il ticket viene registrato con l'origine api, e la risposta è una vista ridotta: numero, id, stato, fase, oggetto, argomento, richiedente, l'id dell'assegnatario e i timestamp. Gli id interni e lo stato dell'automazione non vengono mai restituiti.
email è facoltativa quando un'integrazione o un agente registra il ticket per sé: invia solo un name, e non viene creato alcun contatto e non viene inviato nulla al richiedente.
I campi facoltativi danno al ticket un subject, phone, company, un topic_id e un subtopic_id tra gli argomenti dell'help desk, un tuo reference_id, una priority da 1 (la più alta) a 4, un type (issue, bug, feature o task) e attachments.
Per affidare il nuovo ticket a qualcuno, indicalo con assignee_uid o assignee_email, uno dei due. Deve far parte del team del workspace dell'help desk, cioè il suo proprietario e i membri accettati del workspace. Un assegnatario rifiutato non fa registrare alcun ticket.
Trova e leggi i ticket
ticket_api_list elenca i ticket con i filtri che ha la dashboard: status (open o closed), source, topic_id, type, assignee_uid, reference_id, una search a testo libero su oggetto, dettagli e numero del ticket, e un intervallo created_from e created_to. Ordina con sort (date_created_ts, last_activity_ts, status_ts o priority) e dir, e scorri con limit (fino a 500) e il bookmark della risposta precedente.
ticket_api_get legge un ticket per ticket_id, con le sue interazioni pubbliche. Le note interne e le bozze dell'AI non vengono mai restituite.
ticket_api_topics restituisce gli argomenti e i sottoargomenti dell'help desk, così il tuo modulo può mostrare lo stesso selettore del modulo ospitato. ticket_api_team restituisce le persone a cui si può assegnare un ticket, ciascuna con un uid, un nome e un'email.
ticket_api_replypubblica sempre una risposta pubblica, mai una nota interna. È l'help desk che risponde, a meno che tu non passias_requester: true, che la pubblica come messaggio del richiedente stesso. In quel caso l'assegnatario, o il proprietario dell'help desk, riceve una notifica, e non conta come prima risposta dell'help desk.ticket_api_set_stagesposta un ticket aperto anew,in_progress,waiting_customeroresolved. Un ticket chiuso viene rifiutato a meno che tu non passireopen: true, che lo riapre in quella fase. Indicare la fase che il ticket ha già non cambia nulla.ticket_api_assignaffida un ticket a una persona del team tramiteassignee_uidoassignee_email. Indicare l'assegnatario attuale non cambia nulla. Se più di un membro del team ha quell'email, la chiamata viene rifiutata con-409e passi invece l'uid.ticket_api_closechiude il ticket. Ilreasonfacoltativo viene mostrato al cliente. Una risposta del cliente entro la finestra di riapertura riporta indietro il ticket.
Leggi l'elenco dell'help desk stesso
get_support_tickets rilegge i ticket per il conto con accesso effettuato che possiede l'help desk, e può essere limitato a un ticket con _id. Ha una forma diversa dalla vista ticket_api_*, che è pensata per chi chiama dall'esterno di Xuda.
Piani e limiti
Il piano decide che cosa può fare una chiave. Leggere (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) richiede l'accesso in lettura, e scrivere (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) richiede l'accesso completo. Un piano che non lo prevede risponde -402. Ogni piano ha inoltre un numero di chiamate al minuto, e oltre quel numero una chiamata riceve -429 fino al minuto successivo. La cronologia segue la finestra di conservazione del piano, quindi un ticket più vecchio di essa non può essere letto. La pagina dei piani ha le cifre.
Un nuovo ticket conta rispetto al limite del mese, come da qualsiasi altro canale di accesso.