# Get inbound WhatsApp statistics by phone number

`GET /v1/whatsapp/stats/inbound/phone-numbers`

Returns how many WhatsApp messages each of your business phone numbers received. Rows are ranked by volume descending and capped at the requested `limit` (default 50, max 200), counted by the time each message reached the number.

Each row contains only a count because a received message has one state. Lifecycle and delivery-latency data do not apply to received messages.

The maximum window is 365 days; a longer range returns 422. Set `timezone` to resolve the period against your local calendar instead of UTC.

## Code samples

### TypeScript

```ts
const stats = await bird.whatsapp.stats.inbound.byPhoneNumber({ from: "2026-05-01", to: "2026-05-31" });
for (const row of stats.data ?? []) {
  console.log(row.phone_number, row.received);
}
```

### Python

```py
stats = client.whatsapp.stats.inbound.by_phone_number(from_="2026-05-01", to="2026-05-31")
for row in stats.data or []:
    print(row.phone_number, row.received)
```

### Go

```go
stats, err := client.Whatsapp.Stats.Inbound.ByPhoneNumber(context.Background(), bird.WhatsappStatsInboundByPhoneNumberParams{
	From: time.Now().AddDate(0, -1, 0),
	To:   time.Now(),
})
if err != nil {
	log.Fatal(err)
}
for _, row := range *stats.Data {
	fmt.Println(*row.PhoneNumber, *row.Received)
}
```

### PHP

```php
$inboundByPhoneNumber = $bird->whatsapp->stats->inbound->byPhoneNumber(['from' => '2026-05-01', 'to' => '2026-05-31']);
foreach ($inboundByPhoneNumber->getData() ?? [] as $row) {
    echo $row->getPhoneNumber(), ' ', $row->getReceived(), PHP_EOL;
}
```

### CLI

```sh
bird whatsapp stats inbound by-phone-number
```

### cURL

```sh
curl -X GET "https://us1.platform.bird.com/v1/whatsapp/stats/inbound/phone-numbers" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "limit=50"
```

## Example response `200`

```json
{
  "period": {
    "from": "2026-05-01",
    "to": "2026-05-25",
    "data_as_of": "2026-05-25T14:03:10Z"
  },
  "data": [
    {
      "phone_number": "+13124495569",
      "received": 182
    }
  ],
  "total": 2
}
```

## Query parameters

- `from` (string): Inclusive start of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Must not be after `to`. Max window 365 days. Defaults to 30 days before `to` when omitted.
- `to` (string): Inclusive end of the window, a calendar day (YYYY-MM-DD). Interpreted in `timezone`, or UTC when omitted. Max window 365 days. Defaults to today in that timezone when omitted.
- `timezone` (string): IANA timezone identifier used to group statistics, for example `Asia/Kathmandu`. The default is UTC. Day and hour boundaries, including the default window when `from` and `to` are omitted, follow this timezone. When this parameter is set, pass `from` and `to` as calendar days or `Z` instants instead of timestamps with explicit UTC offsets.
- `limit` (integer): Maximum number of phone-number rows to return, ranked by received-message volume descending.

## Response body

- `period` (object, required): The window the response covers (echoed back), plus `data_as_of`.
- `period.from` (string, required): Inclusive start of the window, as a calendar day (`YYYY-MM-DD`) or an RFC 3339 hour boundary.
- `period.to` (string, required): Inclusive end of the window, as a calendar day (`YYYY-MM-DD`) or an RFC 3339 hour boundary.
- `period.data_as_of` (nullable string): Latest time reflected in the statistics. More recent events might not be included yet. Null when the freshness boundary is unavailable.
- `data` (array of object, required): Phone-number rows ranked by received-message volume descending, capped at the requested `limit`. A number with no messages in the period is absent rather than zero-filled, because unlike a time bucket it is not part of a continuous axis.
- `data.phone_number` (string, required): The business phone number that received the messages, in E.164 form.
- `data.received` (integer, required): Distinct messages the number received in the period.
- `total` (integer, required): Total distinct phone numbers with received messages in the period, regardless of `limit`. When it exceeds the number of rows returned, the ranking was capped; raise `limit` (up to 200) or narrow the window to see more.

## 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)