Skip to main content
GET
/
{instance}
/
contacts
/
get-all
Get all contacts
curl --request GET \
  --url https://app.hypersender.com/api/whatsapp/v2/{instance}/contacts/get-all \
  --header 'Authorization: Bearer <token>'
{
  "message": "Contacts retrieved successfully.",
  "data": [
    {
      "id": "100875997589545@lid",
      "name": "Maria",
      "pushname": "Maria Doe"
    }
  ]
}
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: 
{
  "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: 
# 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

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

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Accept
string

application/json

Example:

"application/json"

​
Content-Type
string

application/json

Example:

"application/json"

Path Parameters

​
instance
string
required

Instance UUID copied from hypersender dashboard

Example:

"{{ instance_id }}"

Query Parameters

​
limit
integer
default:100

Number of contacts to return (1-1000)

Required range: 1 <= x <= 1000
Example:

100

​
offset
integer
default:0

Number of contacts to skip

Required range: x >= 0
Example:

0

​
sort_by
enum<string>
default:name

Sort by id or name

Available options:
id,
name
Example:

"name"

​
sort_order
enum<string>
default:asc

Sort order: asc or desc

Available options:
asc,
desc
Example:

"asc"

Response

Contacts retrieved successfully

​
message
string
Example:

"Contacts retrieved successfully."

​
data
object[]