List Conversation Numbers

Fetch the customer numbers this WhatsApp number has conversations with, each with its 24-hour window status and name.

Last updated 14 Aug 2026

Endpoint

GET /numbers.php

Requires the Authorization: Bearer header described in Authentication.

Query parameters

Field	Type	Required	Description
`number`	string	yes	Your own connected WhatsApp number (the one this API key is bound to), digits only after stripping non-digit characters. Required even though the key only ever works for one number - it catches a caller using the wrong key/number pairing with a clear error instead of silently returning the wrong number's data.

Example request

curl "https://your-riffre-domain.com/api/v1/numbers.php?number=911234567890" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY"

Success response

200 OK:

{
  "numbers": [
    {
      "number": "919876543210",
      "name": "Asha Rao",
      "window_open": true,
      "window_expires_at": "2026-08-14 18:42:00",
      "last_message_at": "2026-08-14 12:42:00"
    },
    {
      "number": "919812345678",
      "name": null,
      "window_open": false,
      "window_expires_at": "2026-08-11 09:03:00",
      "last_message_at": "2026-08-10 09:03:00"
    }
  ]
}

Field	Description
`number`	The customer's WhatsApp number, digits only.
`name`	The contact's name as provided by WhatsApp, or `null` if none has been received yet.
`window_open`	`true` if the 24-hour customer service window is currently open, meaning a free-form (non-template) message can be sent. `false` means only a template message will be delivered.
`window_expires_at`	When the current window expires (or last expired), or `null` if there has been no inbound message yet.
`last_message_at`	Timestamp of the most recent message in either direction.

Returns up to the 250 most recently active conversations, most recent first.

Errors specific to this endpoint

`error` slug	HTTP status	Cause
`a_number_query_parameter_is_required`	422	`number` is missing or empty.
`this_api_key_is_not_authorized_for_that_number`	403	`number` does not match the WhatsApp number this API key is bound to.

For the full error shape and general status codes, see Errors.