Kind 31989: Handler Recommendation

Overview

A Handler Recommendation event is used by users to recommend applications that can handle specific types of events. This kind helps bridge the gap when a client encounters an unknown event kind by allowing users to discover appropriate applications that can handle those events.

Specification

Property	Value
Kind Number	31989
Event Range	Replaceable (by d tag)
Defined in	NIP-89

Content Format

The content field can be empty or contain additional information about the recommendation.

Tags

Tag Name	Description	Format	Required
d	Supported event kind	["d", "<event-kind-number>"]	Yes
a	Application reference	["a", "<handler-event-identifier>", "<relay-url>", "<platform>"]	Yes

The d tag specifies the event kind that this recommendation is for.

The a tag references the handler application with:

• <handler-event-identifier>: Typically in the format 31990:<app-pubkey>:<d-identifier>
• <relay-url>: A relay hint where the handler information (kind 31990) can be found
• <platform>: The platform where this recommendation applies (e.g., "web", "ios", "android")

Multiple a tags can be included to recommend different applications for different platforms.

Client Behavior

Clients should query for these events when a user encounters an unknown event kind. Clients can:

1. Look for kind 31989 events with a d tag matching the unknown event kind
2. Filter these events based on the recommenders (e.g., the user's follows)
3. Use the a tag information to fetch the handler information (kind 31990)
4. Present the user with options to open the unknown event in a specialized application

Relay Behavior

Relays treat this kind like any other event. These events are replaceable by the d tag, so relays should replace old events with newer ones that have the same pubkey and d tag value.

Use Cases

• Recommending a specialized track player app for handling audio tracks (kind 31337)
• Recommending a marketplace app for handling marketplace listings
• Recommending a calendar app for handling event invitations
• Helping users discover appropriate applications for specialized content types

Example

{
  "kind": 31989,
  "pubkey": "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245",
  "tags": [
    ["d", "31337"],
    ["a", "31990:1743058db7078661b94aaf4286429d97ee5257d14a86d6bfa54cb0482b876fb0:abcd", "wss://relay.example.com", "web"],
    ["a", "31990:8f35c6ff1a1cf48a4b37d36a5b7c65f6f32a5b587ad7c71db7c343a69b1a16a1:efgh", "wss://relay.example.com", "ios"]
  ],
  "content": "These are my recommended apps for handling code snippets (kind:31337)",
  "created_at": 1671217411
}

References

• NIP-89: Recommended Application Handlers

Related Kinds

• Kind 31990: Handler Information
• Kind 1337: Code Snippet

Notes

The purpose of this event kind is to enable a more interconnected ecosystem where specialized applications can handle specific types of content. This allows general-purpose clients to focus on common use cases while still enabling users to interact with specialized content through appropriate applications.