> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get All Contacts
> Retrieve a list of all contacts in the WhatsApp instance with pagination and sorting options.
Retrieve a paginated list of all contacts in your WhatsApp instance.
This endpoint allows you to:
* Fetch all contacts from your WhatsApp instance
* Paginate through large contact lists
* Sort contacts by name or ID
* Control the number of contacts returned
This is useful for syncing contacts with your CRM, building contact lists, or displaying contacts in your application.
## Use Cases
### Contact Synchronization
Sync all your WhatsApp contacts with your CRM or external database.
### Contact Management
Build a contact management interface with pagination and sorting capabilities.
### Bulk Operations
Retrieve contact lists for bulk messaging or data analysis operations.
### Export Contacts
Export your WhatsApp contacts for backup or migration purposes.
## Query Parameters
### limit
* **Type**: Integer
* **Range**: 1-1000
* **Default**: 100
* **Description**: Number of contacts to return per request
### offset
* **Type**: Integer
* **Minimum**: 0
* **Default**: 0
* **Description**: Number of contacts to skip (for pagination)
### sort\_by
* **Type**: String
* **Options**: `id`, `name`
* **Default**: `name`
* **Description**: Field to sort contacts by
### sort\_order
* **Type**: String
* **Options**: `asc`, `desc`
* **Default**: `asc`
* **Description**: Sort order (ascending or descending)
## Response Examples
### Successful Response
When contacts are retrieved successfully:
```json theme={null}
{
"message": "Contacts retrieved successfully.",
"data": [
{
"id": "100875997589545@lid",
"name": "Maria",
"pushname": "Maria Doe"
},
{
"id": "10226367471836@lid",
"name": "John",
"pushname": "John Doe"
}
]
}
```
## Pagination Example
To paginate through contacts, use the `limit` and `offset` parameters:
```bash theme={null}
# First page (contacts 1-100)
GET /{instance}/contacts/get-all?limit=100&offset=0
# Second page (contacts 101-200)
GET /{instance}/contacts/get-all?limit=100&offset=100
# Third page (contacts 201-300)
GET /{instance}/contacts/get-all?limit=100&offset=200
```
## Best Practices
Use pagination with reasonable limits (e.g., 100-200) to avoid timeouts and improve performance.
The `pushname` is the name the user has set in their WhatsApp profile, while `name` is the name saved in your phone's contacts.
Large contact lists may take time to retrieve. Consider implementing progressive loading in your UI.
## Integration Example
### Fetching All Contacts with Pagination
```javascript theme={null}
async function getAllContacts(instance, apiKey) {
let allContacts = [];
let offset = 0;
const limit = 100;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://app.hypersender.com/api/whatsapp/v2/${instance}/contacts/get-all?limit=${limit}&offset=${offset}`,
{
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();
allContacts = allContacts.concat(data.data);
// Check if there are more contacts
hasMore = data.data.length === limit;
offset += limit;
}
return allContacts;
}
```
The `chatId` can be in any format `+20123456789`, `20123456789`, `0123456789`, or `123456789`
## OpenAPI
````yaml v2/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/get-all
openapi: 3.1.0
info:
version: v2.0
title: Hypersender WhatsApp API Docs
description: >
The Hypersender WhatsApp API is a powerful api to send and recieve messages
using your own whatsapp number.
Without the high costs of Meta's Whatsapp business API.
In this Docs you'll learn how to use and integrate Hypersnder Whatsapp API
into your existing system/service or application using simple API endpoints.
## What's New in V2?
**Queued Responses:** All requests in V2 are now queued for improved
reliability and performance. When you make a request, you'll receive an
immediate response with a `queued_request_uuid` that you can use to check
the status of your request.
**Example Response:**
```json
{
"queued": true,
"message": "Processing your request...",
"queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
"queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/{queued_request_uuid}"
}
```
Use the `queued_request_link` or the **Get Queued Request** endpoint to
check the actual message response once it's processed.
**What you can Do?**
- Send Text and basic Url messages.
- Send Media through Link or uploaded file.
- Send Audio through Link or uploaded file.
- Send Contact Card
- Send Location
- Send Poll votes
**You can also**
- React to a message
- Forward messages to other chats
- Acknowledge messages (mark as read)
- Star and unstar messages
**Quick Demo**
**Learn how to use Hypersender whatsapp API to send a message using Postman:**
[Demo Link](https://app.hypersender.com/send-whatsapp-message-in-postman) **to easily interact with our API.**
**postman collection**
You can download our [Postman
Collection](https://docs.hypersender.com/whatsapp-postman-collection.json)
to easily interact with our API.
## Servers (Endpoints)
- Production (activated):
[https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
servers:
- url: https://app.hypersender.com/api/whatsapp/v2
description: Production
security:
- Authorization: []
paths:
/{instance}/contacts/get-all:
get:
tags:
- Contacts
summary: Get all contacts
description: >-
Retrieve a list of all contacts in the WhatsApp instance with pagination
and sorting options.
parameters:
- name: Accept
in: header
description: application/json
schema:
type: string
example: application/json
- name: Content-Type
in: header
description: application/json
schema:
type: string
example: application/json
- name: instance
in: path
description: Instance UUID copied from hypersender dashboard
required: true
schema:
type: string
example: '{{ instance_id }}'
- name: limit
in: query
description: Number of contacts to return (1-1000)
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
example: 100
- name: offset
in: query
description: Number of contacts to skip
required: false
schema:
type: integer
minimum: 0
default: 0
example: 0
- name: sort_by
in: query
description: Sort by id or name
required: false
schema:
type: string
enum:
- id
- name
default: name
example: name
- name: sort_order
in: query
description: 'Sort order: asc or desc'
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
example: asc
responses:
'200':
description: Contacts retrieved successfully
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Contacts retrieved successfully.
data:
type: array
items:
type: object
properties:
id:
type: string
description: Contact ID
example: 100875997589545@lid
name:
type: string
description: Contact name
example: Maria
pushname:
type: string
description: Contact push name
example: Maria Doe
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
security:
- Authorization: []
components:
schemas:
NotFoundError:
type: object
title: NotFoundError
example:
message: Resource not found.
properties:
message:
type: string
x-examples:
Example 1:
message: Resource not found.
x-stoplight:
id: ar3vz55asbxme
ServerError:
type: object
title: ServerError
properties:
message:
type: string
example:
message: Internal Server Error
x-stoplight:
id: 2fhq2gihsfreh
securitySchemes:
Authorization:
type: http
scheme: bearer
````