# `bird whatsapp agents list`

## Usage

```bash
bird whatsapp agents list [flags]
```

## Description

One row per WhatsApp number your workspace connected itself, saying whether WhatsApp allows an agent on it and, when one has been onboarded, whether it is answering and who it may answer. Filter with `has_agent` and `eligible` to find the numbers to act on.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Examples

```bash
bird whatsapp agents list
bird whatsapp agents list | jq -r '.data[].whatsapp_number_id'
bird whatsapp agents list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--eligible`           | Filter by whether WhatsApp allows an agent on the number, as of the number's last read from WhatsApp (meta\_synced\_at on the number). true lists the numbers an agent can be onboarded on; false the ones WhatsApp has refused. A number WhatsApp has not yet answered for matches neither. WhatsApp says not to cache eligibility, so a number read an hour ago can have changed since; onboarding asks WhatsApp afresh. Omit to return numbers whatever their reading. |
| `--has-agent`          | Filter by whether an agent has been onboarded on the number. true lists numbers with an agent, whether it is answering or not; false lists numbers without one. Omit to return both.                                                                                                                                                                                                                                                                                      |
| `--response-schema`    | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `--waba`               | Filter to the numbers on one WhatsApp Business Account, by the waba returned on the row.                                                                                                                                                                                                                                                                                                                                                                                  |
| `--whatsapp-number-id` | Filter to one WhatsApp number. The one way to read a number's eligibility before it has an agent.                                                                                                                                                                                                                                                                                                                                                                         |

#### Pagination

| Name               | Description                                                                                                                                                                                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev\_cursor or refresh\_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev\_cursor returns the preceding page. refresh\_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since. |
| `--limit <n>`      | Maximum number of items to return per page. Allowed range: 1 to 100.                                                                                                                                                                                                                                                                                    |
| `--order`          | Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field. Possible values: asc, desc.                                                                                                                                                                                           |
| `--sort`           | Field to sort by. Possible values: created\_at.                                                                                                                                                                                                                                                                                                         |
| `--starting-after` | Cursor from the next\_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.                                                                                                                                                                                                          |

## Related

| Name                                                                        | Description                           |
| --------------------------------------------------------------------------- | ------------------------------------- |
| [`bird whatsapp agents create`](/docs/cli/reference/whatsapp-agents-create) | Onboard an agent on a WhatsApp number |
| [`bird whatsapp agents delete`](/docs/cli/reference/whatsapp-agents-delete) | Delete a WhatsApp number's agent      |
| [`bird whatsapp agents get`](/docs/cli/reference/whatsapp-agents-get)       | Get a WhatsApp number's agent         |
| [`bird whatsapp agents test`](/docs/cli/reference/whatsapp-agents-test)     | Send an agent a test message          |

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)