Riferimento eventi

È possibile iscriversi a sei tipi di evento per endpoint. Ogni richiesta usa lo stesso envelope — event, timestamp, guild_id e data — e cambia solo l'oggetto data.

Event	Fires when
`ticket.created`	Un ticket viene aperto
`ticket.closed`	Un ticket viene chiuso
`ticket.updated`	Qualsiasi altra cosa cambia su un ticket aperto
`message.sent`	Un membro o lo staff scrive in un ticket
`blacklist.added`	Un membro viene inserito in blacklist
`blacklist.removed`	Una voce della blacklist viene rimossa

I campi che non possono essere risolti vengono inviati come null invece di essere omessi — così puoi fare affidamento sul fatto che le chiavi esistano. Un username è null quando Discord non ha restituito l'utente.

Campi condivisi

Ogni evento ticket include questi campi:

Field	Type	Description
`ticket_id`	`string`	L'id leggibile del ticket dal tuo pattern, ad esempio `ticket-1042`
`ticket_num_id`	`number`	Il numero progressivo del ticket, ad esempio `1042`
`channel_id`	`string`	Il canale Discord del ticket
`category`	`string \| null`	Nome della categoria, `null` se il ticket non ne ha una
`user`	`object \| null`	Il proprietario del ticket come `{ id, username }`

ticket.created

Inviato subito dopo la creazione del canale del ticket.

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Questo evento viene inviato quando il ticket viene aperto, quindi prima che il membro abbia scritto qualsiasi cosa. Se ti serve il primo messaggio, ascolta anche message.sent.

ticket.closed

{
  "event": "ticket.closed",
  "timestamp": "2026-08-26T07:45:02.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1041",
    "ticket_num_id": 1041,
    "channel_id": "998877665544332211",
    "category": "💸 Payment",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "closed_by": { "id": "112233445566778899", "username": "Staff_01" },
    "reason": "Issue resolved",
    "closed_at": "2026-08-26T07:45:02.000Z"
  }
}

Field	Type	Description
`closed_by`	`object`	Chi lo ha chiuso. Le chiusure automatiche riportano il bot
`reason`	`string \| null`	Il motivo della chiusura, `null` se non ne è stato fornito uno

ticket.updated

Il contenitore generale per le modifiche a un ticket aperto. action ti dice cosa è cambiato, changes contiene i dettagli di quella specifica azione.

{
  "event": "ticket.updated",
  "timestamp": "2026-08-26T14:02:19.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1038",
    "ticket_num_id": 1038,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "action": "ticket_priority:add",
    "changes": { "priority": "high" },
    "reason": null,
    "updated_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

Possibili valori di `action`

`action`	Meaning	`changes` contains
`ticket_claim:add`	Un membro dello staff ha preso in carico il ticket	(empty)
`ticket_unclaim:add`	La presa in carico è stata rilasciata	(empty)
`ticket_priority:add`	La priorità è cambiata	`priority`
`ticket_rename:add`	Il canale è stato rinominato	`new_name`
`ticket_remind:add`	È stato inviato un promemoria	(empty)
`ticket_feedback:add`	Il membro ha valutato il ticket	`star_count`, `feedback`
`ticket_schedule_close:add`	È stata programmata una chiusura	`duration`, `schedule_time`
`ticket_request_close:add`	Lo staff ha chiesto al membro di chiudere	`duration`, `request_duration_time`
`ticket_request_close_accept:add`	Il membro ha accettato	(empty)
`ticket_request_close_deny:add`	Il membro ha rifiutato	(empty)
`ticket_close_cancel:add`	Una chiusura in corso è stata annullata	(empty)
`ticket_additional_access:add`	Un utente o un ruolo è stato aggiunto al ticket	`entity_type`, `entity_id`, `reason`
`ticket_additional_access:remove`	Un utente o un ruolo è stato rimosso	`entity_type`, `entity_id`, `reason`

Considera questo elenco come aperto. Nuove azioni vengono aggiunte man mano che TicketWave cresce, e arrivano come ticket.updated. Gestisci solo le azioni che ti interessano e ignora le altre invece di generare un errore sui valori sconosciuti.

Rispondere a un passo del ticket non produce nessun evento. Un ticket con molti passaggi altrimenti inonderebbe il tuo endpoint mentre il membro sta ancora compilando il modulo.

message.sent

Inviato per ogni messaggio umano all'interno di un ticket aperto. I messaggi dei bot — incluso TicketWave stesso — vengono ignorati.

{
  "event": "message.sent",
  "timestamp": "2026-08-26T22:10:55.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1040",
    "ticket_num_id": 1040,
    "channel_id": "998877665544332211",
    "message_id": "1234567890123456789",
    "content": "Hello, how can I help you?",
    "author": { "id": "112233445566778899", "username": "Staff_01" },
    "is_staff": true,
    "sent_at": "2026-08-26T22:10:55.000Z"
  }
}

Field	Type	Description
`content`	`string`	Il testo grezzo del messaggio. Vuoto per i messaggi con solo allegati
`author`	`object`	`{ id, username }` del mittente
`is_staff`	`boolean`	`true` se il mittente ha un ruolo di supporto configurato

Questo è l'evento con il volume più alto di gran lunga — un server molto attivo produce una richiesta per ogni messaggio. Iscriviti solo se hai davvero bisogno dei dati a livello di messaggio e assicurati che il tuo ricevitore risponda rapidamente.

blacklist.added

Non è legato a un ticket, quindi questo payload non ha ticket_id.

{
  "event": "blacklist.added",
  "timestamp": "2026-08-26T18:33:47.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "user": { "id": "111223344556677889", "username": "BadActor" },
    "reason": "Spam",
    "added_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

blacklist.removed

{
  "event": "blacklist.removed",
  "timestamp": "2026-08-26T18:40:12.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "user": { "id": "111223344556677889", "username": "BadActor" },
    "removed_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

Eventi di test

Il pulsante Send test event invia una richiesta reale e firmata il cui data è semplicemente:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T12:00:00.000Z",
  "guild_id": "123456789012345678",
  "data": { "test": true }
}

L'event è il primo tipo a cui l'endpoint è iscritto. Controlla data.test se vuoi saltare le consegne di test nella logica di produzione.

Prossimi passi

Example Server (Gestisci questi payload in Express)
Webhooks (Firma, retry e cronologia delle consegne)

Event Reference