Skip to main content
Glama

Turbo Notify: WhatsApp for AI agents

List what happened on the organization's WhatsApp numbers

list_events
Read-onlyIdempotent

Poll everything that happened on the organization's WhatsApp numbers: messages, contacts, groups, numbers, quotas.

This is how an agent learns about inbound messages without hosting a webhook endpoint.

Events come back newest first, so polling for new ones uses ending_before, not starting_after. Typical loop: call with no cursor and remember the id of the FIRST event in the page (the newest one); next time, pass that id as ending_before to get only what has happened since. An empty page means you are caught up.

starting_after does the opposite: it walks BACKWARD into history, which is what you want for reading older events, and never what you want for noticing something new. Passing the last id you handled to starting_after in a loop returns steadily older events and never reaches the present.

request_id returns everything that came of one earlier call. A write tool's result carries request_id when the platform issued one; keep it and you can ask later what became of that specific send.

number_id restricts to one number and keeps matching its events after the number is renamed. number_alias restricts to one number by the alias it had when the event happened, so a rename hides the older events; the two can be combined. Either one excludes storage.* and media.unavailable events, which belong to the organization rather than to any one number.

Most events carry a number_alias telling you which number they belong to, and number_id (num_…), the same number's permanent identifier. The alias is the one at the time of the event and can be renamed later; the number_id cannot. You need one of them: message, contact and group ids are unique but not self-addressing, so an id alone does not tell you which number's tools to use with it, and both work as number_alias in the other tools. Read the fields defensively rather than assuming they are there: storage.* and media.unavailable belong to the organization as a whole and have no single number to name, so on those the keys are absent rather than empty.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many events to return, 1-100. Defaults to 25.
number_idNoRestrict results to one number by its `id` (`num_…`, as returned by `list_numbers`). It keeps matching the number's events after the number is renamed, unlike `number_alias`, which matches the alias the number had when the event happened. Can be combined with `number_alias`. Absent means every number. Setting it excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number.
event_typeNoFilter to exactly one event type, e.g. `message.received`. Common ones: `message.sent`, `message.delivered`, `message.read`, `message.received`, `message.reacted`, `message.edited` (a text or caption edit, or a calendar event that was edited or canceled), `message.calendar_responded` (a guest answered a calendar event), `message.quota.warning`, `number.connected`, `number.disconnected`, `contact.created`, `contact.quota.warning`, `group.joined`, `group.participants_added`. Use `event_types` instead to filter on more than one at once.
request_idNoReturn only the events that came of one earlier call (`req_…`). A write tool's result carries `request_id` when the platform issued one; keep it and you can ask later what became of that send.
created_gteNoOnly events created at or after this instant. ISO 8601 with an offset, e.g. `2026-09-01T00:00:00Z`.
created_lteNoOnly events created at or before this instant. ISO 8601 with an offset, e.g. `2026-09-10T00:00:00Z`.
event_typesNoFilter to several event types at once, e.g. `message.sent` and `message.delivered`. Same vocabulary as `event_type`. The API accepts at most 20.
number_aliasNoRestrict results to one number by the alias it had when the event happened, so events from before a rename are missed. Use `number_id` to follow a number across renames. **Absent means every number**, which is the usual choice. Note this is a filter, not a subject: unlike the messaging tools it does not default to `main`. Setting it also excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number.
ending_beforeNoCatch up: return events NEWER than this id. Pass the newest id you have already handled to see only what has happened since. This is the one to poll with.
starting_afterNoRead further back: return events OLDER than this id. This is the one for reading back through older events, and the wrong one for noticing something new.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / number_alias / description
      Previous value: -"Restrict results to one inbox by the alias it had when the event happened, so events from before a rename are missed. Use `number_id` to follow a number across renames. **Absent means every number**, which is the usual choice. Note this is a filter, not a subject: unlike the messaging tools it does not default to `main`. Setting it also excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number."New value: +"Restrict results to one number by the alias it had when the event happened, so events from before a rename are missed. Use `number_id` to follow a number across renames. **Absent means every number**, which is the usual choice. Note this is a filter, not a subject: unlike the messaging tools it does not default to `main`. Setting it also excludes `storage.*` and `media.unavailable` events, which belong to the organization rather than to any one number."
    • changedInput schema / properties / starting_after / description
      Previous value: -"Read further back: return events OLDER than this id. This is the one for walking a backlog, and the wrong one for noticing something new."New value: +"Read further back: return events OLDER than this id. This is the one for reading back through older events, and the wrong one for noticing something new."
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, yet the description still adds real context: reverse-chronological ordering, empty-page semantics, and the fact that setting `number_id`/`number_alias` silently excludes `storage.*` and `media.unavailable` events. It also warns to read fields defensively because those keys are absent rather than empty on organization-level events — a behavior no annotation conveys. It stops short of describing page-size/pagination limits beyond the `limit` default.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then bolded, well-segmented guidance blocks for cursors, request_id, and number filters. It is on the long side and re-states some material that already appears verbatim in the schema (the number_id vs number_alias rename semantics appear in both places), which is the main thing keeping it from a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, zero-required polling tool with an output schema, the description covers everything an agent needs to call it correctly: ordering, cursor direction, catch-up loop, filter interactions, and defensive field reading. Return-value shape is rightly left to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds the cursor-usage recipe and the empty-page interpretation that the schema does not spell out as a workflow. It also explains why `number_id` or `number_alias` is needed at all (message/contact/group ids aren't self-addressing), which is meaning the schema's field docs don't fully convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource — 'Poll everything that happened on the organization's WhatsApp numbers: messages, contacts, groups, numbers, quotas' — and immediately frames it as the webhook-free way to learn about inbound messages. That framing distinguishes it from point-lookup siblings like list_messages or get_message without the agent needing to open another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit polling recipe (no cursor, remember the FIRST/newest id, pass it as `ending_before`, empty page = caught up) and explicitly rules out the wrong pattern: passing the last handled id to `starting_after` 'never reaches the present.' It also scopes `request_id` to post-hoc inspection of an earlier write call and states when the number filters are and aren't appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.