Tickets
Caixa de entrada partilhada, formulários e automações para pedidos de clientes.
A API de tickets permite que software exterior à Xuda trabalhe um balcão: abrir um ticket, listar e ler tickets, responder, atribuir, mover um ticket entre fases e fechá-lo, e ler os tópicos e a equipa. Os formulários, os fluxos de trabalho, os agentes de IA, as notas internas e as definições ficam no dashboard.
Cada chamada é um POST para https://xuda.ai/cpi/<method> com um corpo JSON que leva a chave de API da sua conta como api_key. Uma chamada funciona no balcão da conta que é dona da chave, ao abrigo do plano desse balcão, e não pode indicar outro balcão. Crie a chave no dashboard, em Programadores, e mantenha-a fora de páginas e de código público.
A resposta é { "code": ..., "data": ... }. Um code positivo é sucesso. Uma recusa é um código negativo com uma frase em data.
name e details são obrigatórios. Um contacto é criado ou reutilizado a partir de email, o ticket é registado com a origem api, e a resposta é uma vista reduzida: número, id, estado, fase, assunto, tópico, requerente, o id do responsável e as datas e horas. Os ids internos e o estado da automatização nunca são devolvidos.
email é opcional quando uma integração ou um agente regista o ticket para si própria: envie apenas um name, e nenhum contacto é criado e nada é enviado por e-mail ao requerente.
Os campos opcionais dão ao ticket um subject, phone, company, um topic_id e subtopic_id dos tópicos do balcão, o seu próprio reference_id, uma priority de 1 (a mais alta) a 4, um type (issue, bug, feature ou task) e attachments.
Para atribuir o novo ticket a alguém, indique-o com assignee_uid ou assignee_email, um dos dois. Tem de pertencer à equipa do espaço de trabalho do balcão, que é o seu proprietário e os membros aceites do espaço de trabalho. Um responsável recusado não regista nenhum ticket.
Encontrar e ler tickets
ticket_api_list lista tickets com os filtros que o dashboard tem: status (open ou closed), source, topic_id, type, assignee_uid, reference_id, uma search de texto livre sobre o assunto, os detalhes e o número do ticket, e um intervalo created_from e created_to. Ordene com sort (date_created_ts, last_activity_ts, status_ts ou priority) e dir, e pagine com limit (até 500) e o bookmark da resposta anterior.
ticket_api_get lê um ticket por ticket_id, com as suas interações públicas. As notas internas e os rascunhos de IA nunca são devolvidos.
ticket_api_topics devolve os tópicos e subtópicos do balcão, para que o seu próprio formulário possa mostrar o mesmo seletor que o formulário alojado. ticket_api_team devolve as pessoas a quem um ticket pode ser atribuído, cada uma com um uid, um nome e um e-mail.
ticket_api_replypublica sempre uma resposta pública, nunca uma nota interna. É o balcão a responder, a não ser que passeas_requester: true, que a publica como mensagem do próprio requerente. Nesse caso o responsável, ou o dono do balcão, é notificado, e não conta como a primeira resposta do balcão.ticket_api_set_stagemove um ticket aberto paranew,in_progress,waiting_customerouresolved. Um ticket fechado é recusado a não ser que passereopen: true, que o abre de novo nessa fase. Indicar a fase que o ticket já tem não altera nada.ticket_api_assignatribui um ticket a uma pessoa da equipa porassignee_uidouassignee_email. Indicar o responsável atual não altera nada. Se mais do que um membro da equipa tiver esse e-mail, a chamada é recusada com-409e passa o uid em vez disso.ticket_api_closefecha o ticket. Oreasonopcional é mostrado ao cliente. Uma resposta do cliente dentro do prazo de reabertura faz o ticket voltar.
Ler a lista do próprio balcão
get_support_tickets lê os tickets de volta para a conta com sessão iniciada que é dona do balcão, e pode ser limitado a um ticket com _id. Tem uma forma diferente da vista ticket_api_*, que é feita para um chamador exterior à Xuda.
Planos e limites
O plano decide o que uma chave pode fazer. Ler (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) precisa de acesso de leitura, e escrever (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) precisa de acesso total. Um plano sem ele responde -402. Cada plano tem também um número de chamadas por minuto, e acima dele uma chamada é respondida com -429 até ao minuto seguinte. O histórico segue a janela de retenção do plano, por isso um ticket mais antigo do que ela não pode ser lido. A página de planos tem os números.
Um novo ticket conta para a quota do mês, tal como por qualquer outra forma de entrada.