Interactions Laravel Package

Getting Started

Begin by installing the package via Composer: composer require discord/interactions. For production security, also install simplito/elliptic-php and ensure the gmp PHP extension is enabled—signature validation will silently fail otherwise. Your first step is creating a webhook endpoint (e.g., /discord/interactions) that validates the request signature using Interaction::verifyKey(), then responds with InteractionResponseType::PONG for slash commands. This establishes the minimal viable interaction handler for basic slash commands.

Implementation Patterns

• Middleware-first validation: Wrap verifyKey() in a Laravel middleware to centralize signature checks and prevent boilerplate duplication. Extract raw body via Request::getContent() before middleware like TrimStrings modifies it.
• Typed interaction parsing: Use Interaction::fromPayload() to convert raw payloads into structured objects, then switch on InteractionType (e.g., APPLICATION_COMMAND, MODAL_SUBMIT) to route logic to dedicated handlers.
• Modal & autocomplete flows: For modals, respond with InteractionResponseType::MODAL and define title/custom_id/components via InteractionResponseData. For autocomplete, return filtered choices using InteractionResponseType::APPLICATION_COMMAND_AUTOCOMPLETE_RESULT.
• Deferred responses: For long-running tasks, respond immediately with DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE (flags like EPHEMERAL可选), then post follow-up messages using Laravel’s HTTP client + Discord webhook URL from the interaction token.

Gotchas and Tips

• Signature validation requires exact raw body bytes—never re-encode the payload or use json_decode() before passing to verifyKey(). Even trailing newlines break verification.
• The package lacks Laravel integration out-of-the-box: no service provider, no facade. You must manually wire validation, routing, and response delivery (e.g., via a dedicated DiscordInteractionController).
• Interaction tokens expire after 15 minutes—use deferred responses proactively for operations >2s to avoid 504 Gateway Timeout.
• Enums like InteractionResponseFlags use bitmasks: combine them with bitwise OR (EPHEMERAL | crossposted) when constructing response data.
• The last release (2022-02-09) means compatibility with newer Discord API features (e.g., context menus, modals with dynamic data) isn’t guaranteed—test thoroughly against Discord’s latest docs before adopting.