Interaction lifecycle

Status Stable · Last verified 2026-07-11 · API v10 · Source Receiving & responding

Every interaction follows the same shape. Get the timing right and the rest of the section is straightforward.

The five interaction types

The incoming type field (verified against the API reference):

Interaction type	Value	Sent when
PING	1	Endpoint handshake (HTTP endpoints only)
APPLICATION_COMMAND	2	A slash / user / message command is used
MESSAGE_COMPONENT	3	A button or select menu is used
APPLICATION_COMMAND_AUTOCOMPLETE	4	The user is typing an autocomplete option
MODAL_SUBMIT	5	A modal is submitted

The lifecycle

1. RECEIVE   Discord delivers the interaction (HTTP POST to your endpoint, or a
             gateway INTERACTION_CREATE event).
2. VERIFY    (HTTP endpoint only) Verify the Ed25519 signature over the raw body.
             → /interactions/signature-verification/
3. ACK ≤3s   Send an initial response WITHIN 3 SECONDS, or Discord shows
             "This interaction failed."
4. RESPOND   Either reply now, or DEFER (show a loading state) and edit later.
5. FOLLOW UP Use the interaction token (valid ~15 minutes) to edit the response
             or send additional messages.

[!NOTE] Verified — the two hard numbers You must send an initial response within 3 seconds of receiving an interaction, and interaction tokens are valid for 15 minutes for editing the response and sending follow-ups. Source: Receiving & responding.

Acknowledge fast, work slowly: deferral

If your handler needs more than ~3 seconds (an API call, a database query), don’t block — defer, then edit the response when the work is done:

• For commands, reply with DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE (type 5) — the user sees a “thinking…” loading state; then PATCH the original response.
• For components, reply with DEFERRED_UPDATE_MESSAGE (type 6) — no visible loading state; then edit the original message.

Response type numbers and the follow-up endpoints are on Responses & follow-ups.

The PING handshake (HTTP endpoints)

When you set or change an Interactions Endpoint URL, Discord sends a type: 1 (PING) request. Your app must return HTTP 200 with {"type": 1} (PONG). Saving the URL fails unless this — and signature verification — succeeds.

Retries and idempotency

Interactions can be redelivered (e.g. network hiccups). Design handlers to be safe to run twice: don’t double-charge, double-post, or double-mutate on a repeated interaction id. Prefer idempotent writes keyed by the interaction or resource id.

Follow-up count nuance

[!NOTE] Verified For user-installed applications not installed to the server where the interaction happens, apps are limited to 5 follow-up messages per interaction. Source: Receiving & responding.

Failure modes to recognize

Symptom	Cause
“This interaction failed”	No initial response within 3s (or a non-200 from your endpoint)
Endpoint URL won’t save	PING not answered with PONG, or signature verification failing
Follow-up returns 404	Token expired (>15 min) or wrong application_id/token
Duplicate side effects	Handler not idempotent on redelivery

Next

• Signature verification — required before you can trust an HTTP interaction.
• Responses & follow-ups — the exact response types and endpoints.