The
menuCallback method represents a unified response triggered when a user interacts with any type of menu โ whether it's an inline menu, a chat-attached (keypad) menu, or a custom component (also known as a workflow-driven menu ). When a user interacts with a cell (such as submitting a form, selecting an option, or pressing a button), this method is sent to the API to reflect the action and pass captured values.This method returns context about:
- The triggering menu and cell
- The source of the interaction
- The user and chat
- API and app metadata
- A structured list of cell interactions (
values) based on the menu
The callback allows the API to:
- Identify which cell was pressed
- Receive any values associated with the cell (e.g., form input, selection)
- Continue or branch the workflow based on user interaction
Top-Level Fields
Field | Type | Required | Description |
method | String | Yes | "menuCallback" โ indicates a unified menu interaction. |
source | String | Yes | Origin of the interaction: "chat", "inline", or "workflow". |
api_id | String | Yes | Identifier of the API (bot) that owns the interaction. |
app_id | String | Yes | Identifier of the app where the menu was displayed. |
from | User | Yes | User context (includes user id, type). |
chat | Chat | Conditional | Chat context (includes chat id, type). |
message | Conditional | Present only if source = "inline" โ the message to which the inline menu was attached includes message_id , message reference and gmid | |
menu_group | String | Yes | Menu group ID that the currently interacted cell belongs to. Used to organize related menus under one context or workflow. |
menu_id | String | Yes | Unique identifier of the specific menu containing the current interacted cell. |
cell_id | String | Yes | Unique identifier of the current interacted cell. |
callback | String | Yes | Callback id of the current interacted cell. |
submit | String | Conditional | Defines the API submission scope when the current interacted cell is triggered
โข cell โ sends only the current cellโs value.
โข menu โ sends values of all cells in the current menu.
โข all โ sends all values filled or triggered across all menus. |
date | Long | Yes | Unix Epoch timestamp in milliseconds of when the interaction occurred. |
cells | Array of Cell Interactions | Yes | List of interacted cells with their submitted values |
reference | String | Optional | Unique identifier for the request. This reference will be echoed in the response. |
Cell Interactions Array (Per Cell Interaction)
Each object in
Cell Interactions corresponds to a user interaction with a cell. The structure is consistent for inputs, toggles, choices, and button presses.Field | Type | Required | Description |
ใ
ค | ใ
ค | ใ
ค | ใ
ค |
menu_id | String | Yes | Unique identifier for the menu the cell belongs to. |
cell_id | String | Yes | Unique identifier of the interacted cell. |
callback | String | Yes | Callback id of the interacted cell. |
form | String | Yes | Type of UI component ( button, dropdown, switch, etc.). |
style | String | Optional | Visual style of the cell ( filled, outlined, etc.). |
label | String | Optional | Display the label of the cell. |
version | String | Optional | System-generated random version after each cell update. |
value_type | Value Type | Yes | Type of the returned value ( string, boolean, number, array, object). |
value | Value | Yes | The submitted or selected value for the cell. |
Inside value object:
Field | Type | Required | Description |
id | String | Yes | Option or cell identifier (for pressed buttons or selected choices). |
value | Any | Yes | The actual value sent by the user. Use "pressed" for action buttons to avoid confusion with boolean values. |
label | String | option | Option lable if any. |
value_type object:
Key | Type | Required | Description |
data | String | โ
Yes | The actual structure of the value stored or submitted.Examples: string, number, boolean, date, array, object, location. |
input | String | Optional | Defines the UI input behavior used for the field in a form.Examples: text, password, textarea, email, phone, time, slider. |
search | String | Optional | Indicates the search/indexing strategy for the value.Examples: keyword, text, range, enum, tag. |
Example:
json"value_type": { "data": "string", "input": "password", "search": "keyword" }
Accepted value_type.data Definitions
value_type | Use Case | Expected Value Format |
string | Text inputs, dropdowns | "example" |
boolean | Switch, checkbox | true / false |
number | Quantity, price, rating | 5, 12.5 |
array | Multi-choice fields | ["opt1", "opt2"] |
object | Custom structured data | { id: ..., value: ... } |
location | Map location input | { latitude: "xx", longitude: "yy" } |
contact | Phone/contact share | { phone: "+15556667777", name: "Jone Peter" } |
date | Date/time picker | "2025-04-04T12:30:00Z" (ISO 8601) |
Full menuCallback Example with All Data Types
json{ "method": "menuCallback", "source": "workflow", "api_id": "api_123", "app_id": "app_456", "chat": { "id": "90090", "type": "User" }, "user": { "id": "90089", "type": "Mobile" }, "date": 1743699509087, "cells": [ { "menu_id": "menu_text", "cell_id": "full_name", "form": "text_field", "style": "outlined", "label": "Full Name", "value_type": { "data":"string"}, "value": [ { "id": "full_name", "value": "Alice Johnson" } ] }, { "menu_id": "menu_toggle", "cell_id": "subscribe", "form": "switch", "style": "standard", "label": "Subscribe to newsletter", "value_type": { "data":"boolean"}, "value": [ { "id": "subscribe", "value": true } ] }, { "menu_id": "menu_number", "cell_id": "quantity", "form": "number_input", "style": "outlined", "label": "Quantity", "value_type": { "data":"number", "value": [ { "id": "quantity", "value": 3 } ] }, { "menu_id": "menu_multi", "cell_id": "sizes", "form": "multi_chip", "style": "standard", "label": "Sizes Available", "value_type": { "data":"string"}, "value": [ { "id": "size_m", "value": "Medium", "option_label": "Medium" }, { "id": "size_l", "value": "Large", "option_label": "Large" } ] }, { "menu_id": "menu_location", "cell_id": "pickup_point", "form": "location", "style": "map", "label": "Pickup Location", "value_type": { "data":"location"}, "value": [ { "id": "pickup_point", "value": { "latitude": "40.712776", "longitude": "-74.005974" } } ] }, { "menu_id": "menu_contact", "cell_id": "user_phone", "form": "phone_number", "style": "standard", "label": "Phone Number", "value_type": { "data":"contact"}, "value": [ { "id": "user_phone", "value": { "phone": "+15556667777", "name": "+15556667777", } } ] }, { "menu_id": "menu_calendar", "cell_id": "appointment", "form": "date_picker", "style": "calendar", "label": "Appointment Date", "value_type": { "data":"date"}, "value": [ { "id": "appointment", "value": "2025-04-04T12:30:00Z" } ] }, { "menu_id": "menu_submit", "cell_id": "btn_submit", "form": "button", "style": "filled", "label": "Submit", "value_type": { "data":"string"}, "value": [ { "id": "btn_submit", "value": "pressed" } ] } ] }