Inline search lets a user type a query against your API from inside a chat, and pick from results your API returns.

It is a two-step exchange: the server sends you an inlineSearch event with the user's query, and you reply with inlineSearchAnswer carrying the results.

user types a query
      │
      ▼
nandbox server  ── inlineSearch ──►  your API
      ▲                              │
      └── inlineSearchAnswer ──────┘

inlineSearch — Server → API

Delivered when a user performs an inline search against your API.

Field Type Returned Description
method String Yes "inlineSearch"
keywords String Yes What the user typed.
from User Yes The user performing the search.
chat Chat Conditional The chat the search was performed in.
app_id String Yes Unique identifier for the App.

SDK Mapping — inlineSearch

SDK Response Callback
Java onInlineSearh(InlineSearch inlineSearch)
JavaScript onInlineSearch(inlineSearch)
Python on_inline_search(self, inline_search)

⚠️ The Java callback is spelled onInlineSearh — missing the second c. This is a long-standing typo in the Java SDK, not a mistake in this page.

inlineSearchAnswer — API → Server

Reply to an inlineSearch with the results to show the user.

Field Type Required Description
method String Yes "inlineSearchAnswer"
chat_id Number Yes The chat the search came from.
to_user_id Number Optional The user to answer. Defaults to chat_id when omitted.
results Array of Result Yes The results to display. Maximum 50 — more than that is rejected.

Inside each results entry

Field Type Required Description
id String Conditional A media file id. When this matches an uploaded file, the server fills in the rest of the entry for you.
type String Conditional Media type of the result. Only needed when id is not a known media id.

💡 The server enriches your results. For every entry whose id is a known media file, it adds filename, url, width, height, size, duration, image, type, name and version before delivering them. You only need to supply the id.

Preconditions for API Functionality

The following tables outline the preconditions that must be met for the API to function correctly. Failure to meet these conditions may result in errors or unexpected behavior.

Action Requirement Description
Answer an inline search At most 50 results A results array longer than 50 entries is rejected with an error.
Answer an inline search Uploaded media To have the server enrich a result, its id must be a media file already uploaded.