List what happened on the organization's WhatsApp numbers
list_eventsPoll 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
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many events to return, 1-100. Defaults to 25. | |
| number_id | No | Restrict 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_type | No | Filter 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_id | No | Return 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_gte | No | Only events created at or after this instant. ISO 8601 with an offset, e.g. `2026-09-01T00:00:00Z`. | |
| created_lte | No | Only events created at or before this instant. ISO 8601 with an offset, e.g. `2026-09-10T00:00:00Z`. | |
| event_types | No | Filter 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_alias | No | 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. | |
| ending_before | No | Catch 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_after | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||