Setup

• Widget ID: "omnibar"
• Add it to the widgets + widgetConfigs fields on initialSetup
• Example:

{
  "...": "...",
  "widgets": [
    {"...":  "..."},
    {"id": "omnibar"}
  ],
  "widgetConfigs": [
    {"...":  "..."},
    {"id": "omnibar", "visibility": "visible" }
  ]
}
Copy

Requests:

omnibar_getConfig

• "NewTab Messages".OmnibarGetConfigRequest
• Used to fetch the initial config data (during the first render)
• returns "NewTab Messages".OmnibarConfig

{
   "mode": "search"
}
Copy

omnibar_getSuggestions

• "NewTab Messages".OmnibarGetSuggestionsRequest
• Used to fetch search suggestions based on user input
• requires term parameter (the search term to get suggestions for)
• returns "NewTab Messages".SuggestionsData

{
   "suggestions": {
      "topHits": [
         {
            "kind": "bookmark",
            "title": "Example Site",
            "url": "https://example.com",
            "isFavorite": true,
            "score": 0.95
         }
      ],
      "duckduckgoSuggestions": [
         {
            "kind": "phrase",
            "phrase": "example search term"
         }
      ],
      "localSuggestions": [
         {
            "kind": "historyEntry",
            "title": "Previous Visit",
            "url": "https://previous.com",
            "score": 0.8
         }
      ]
   }
}
Copy

Subscriptions:

omnibar_onConfigUpdate

• "NewTab Messages".OmnibarOnConfigUpdateSubscription
• The omnibar widget configuration updates
• returns "NewTab Messages".OmnibarConfig

Notifications:

omnibar_setConfig

• "NewTab Messages".OmnibarSetConfigNotification
• Sent when the user changes the omnibar mode (search vs AI)
• sends "NewTab Messages".OmnibarConfig
• example payload:

{
   "mode": "ai"
}
Copy

omnibar_submitSearch

• "NewTab Messages".OmnibarSubmitSearchNotification
• Sent when the user submits a search query
• requires term (the search term) and target (where to open the search)
• example payload:

{
   "term": "duckduckgo privacy",
   "target": "same-tab"
}
Copy

omnibar_submitChat

• "NewTab Messages".OmnibarSubmitChatNotification
• Sent when the user submits a chat message to Duck.ai
• requires chat (the chat message) and target (where to open the chat)
• example payload:

{
   "chat": "How do I enable privacy protection?",
   "target": "new-tab"
}
Copy

omnibar_openSuggestion

• "NewTab Messages".OmnibarOpenSuggestionNotification
• Sent when the user selects a suggestion from the dropdown
• requires suggestion (the selected suggestion) and target (where to open it)
• example payload:

{
   "suggestion": {
      "kind": "bookmark",
      "title": "DuckDuckGo",
      "url": "https://duckduckgo.com",
      "isFavorite": true,
      "score": 1.0
   },
   "target": "same-tab"
}
Copy

Suggestion Types

The omnibar supports various types of suggestions:

• bookmark: Saved bookmarks with title, URL, favorite status, and relevance score
• openTab: Currently open browser tabs with title, tab ID, and relevance score
• phrase: Search phrase suggestions from DuckDuckGo
• website: Direct website URL suggestions
• historyEntry: Previously visited pages from browser history with title, URL, and relevance score
• internalPage: Internal browser pages (settings, etc.) with title, URL, and relevance score

Open Targets

All actions that open content support these target options:

• "same-tab": Replace current tab content
• "new-tab": Open in a new tab
• "new-window": Open in a new browser window