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.

plain text
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.

Response

⚠️ No acknowledgement is returned. The results are delivered straight to the user.

SDK Mapping — `inlineSearchAnswer`

SDK	Request Method
Java	Build an `InlineSearchAnswer` and call `api.send(message);`
JavaScript	Build an `InlineSearchAnswer` and call `api.send(...)`
Python	Build an `InlineSearchAnswer` and call `napi.send(...)`

Example

Event received

json
{
  "method": "inlineSearch",
  "keywords": "invoice",
  "app_id": "90090684293000559",
  "from": { "id": "90091784056528980", "type": "Mobile" },
  "chat": { "id": "90090684293000559", "type": "User" }
}

Answer sent

json
{
  "method": "inlineSearchAnswer",
  "chat_id": 90090684293000559,
  "to_user_id": 90091784056528980,
  "results": [
    { "id": "5121960361126208" },
    { "id": "5121960361126209" }
  ]
}

INLINE SEARCH