Get contacts

List the contacts of your workspace.

آزمایش رایگان را شروع کنید همهٔ نقاط پایانی

List the contacts of your workspace.

Official WhatsApp Cloud API numbers: served from your LetsBot workspace (the same contacts you see in Live Chat), with search, an incremental-sync filter (updated_since) and cursor pagination. The response says "source": "archive" and includes channel, the number whose key made the request.

QR (WhatsApp Web) numbers: unchanged — the phone's address book as the WhatsApp session reports it (id = WhatsApp id, name, notify = profile name, image when available). The filters below do not apply there.

Contacts are workspace-wide: one customer is one contact whichever of your numbers they wrote to.

Each contact (official numbers)

id — the WhatsApp chat id (<number>@s.whatsapp.net); contact_id — the LetsBot contact id.
phone — the customer's number, or null when WhatsApp only gave us a private identity (a customer who hides their number behind a username).
name, notify (WhatsApp profile name), lb_name (name saved in LetsBot), email, image.
platform, is_group, is_archived, is_blocked.
last_message_date, created_at, updated_at — ISO-8601, UTC.

Pagination: ordered by contact_id. Repeat the request with cursor=<next_cursor> until next_cursor is null.

Errors: 422 for an invalid parameter or cursor; 401 for a missing or wrong key; 402 when the subscription or API add-on is not active.

پارامترهای پرس‌وجو

پارامتر	الزامی	نمونه	توضیح
`search`	خیر	`Karim`	Optional, at least 2 characters. Matches the contact's name, saved name, WhatsApp profile name or number.
`phone`	خیر	`{{phone}}`	Optional. One contact by number (international format, digits; a leading `+` is accepted).
`updated_since`	خیر	`2026-09-01`	Optional. Only contacts created or changed since this moment. `YYYY-MM-DD` or an ISO-8601 datetime, read in `timezone`. For an incremental sync, store the newest `updated_at` you received and pass it next time.
`timezone`	خیر	`UTC`	Optional, default `UTC`. IANA timezone used to read `updated_since`. Returned timestamps are always UTC.
`include_groups`	خیر	`1`	Optional. `1` also returns WhatsApp groups. By default only people are returned.
`platform`	خیر	`all`	Optional. Default: the platform of the channel whose key you use (WhatsApp for a WhatsApp number). `messenger`, `instagram`, `telegram`, ... for one platform, or `all`.
`limit`	خیر	`50`	Optional. Page size, default 50, maximum 200.
`cursor`	خیر		Optional. Pass `next_cursor` from the previous response, unchanged, to get the next page. `null` means there are no more pages.

نمونه درخواست

curl -G "https://letsbot.net/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_LB_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://letsbot.net/api/v1/contacts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_LB_API_KEY",
    "Accept": "application/json",
  },
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init('https://letsbot.net/api/v1/contacts');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_LB_API_KEY',
        'Accept: application/json',
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($data);

import requests

response = requests.request(
    "GET",
    "https://letsbot.net/api/v1/contacts",
    headers={
        "Authorization": "Bearer YOUR_LB_API_KEY",
        "Accept": "application/json",
    },
)

print(response.json())

پاسخ‌ها

200 — official number (first page)200

{
    "success": true,
    "Status": true,
    "source": "archive",
    "channel": {
        "id": 2,
        "global_id": "8f0c2a4e-5b1d-4c3a-9e7f-0a1b2c3d4e5f",
        "phone": "966500000000",
        "platform": "whatsapp",
        "is_official": true
    },
    "data": [
        {
            "id": "966512345678@s.whatsapp.net",
            "contact_id": 184,
            "phone": "966512345678",
            "name": "Karim Store",
            "notify": "Karim",
            "lb_name": "Karim Store",
            "email": null,
            "image": null,
            "platform": "whatsapp",
            "is_group": false,
            "is_archived": false,
            "is_blocked": false,
            "last_message_date": "2026-09-29T09:14:02+00:00",
            "created_at": "2026-05-02T11:40:00+00:00",
            "updated_at": "2026-09-29T09:14:02+00:00"
        }
    ],
    "next_cursor": "eyJpIjoxODR9"
}

هر وقت آماده بودید، ما آماده‌ایم

این نقطهٔ پایانی را روی شمارهٔ خودتان امتحان کنید

API در دورهٔ آزمایشی رایگان کار می‌کند. حساب بسازید، شمارهٔ واتس‌اپ خود را وصل کنید و کلیدتان را از API ← داده‌های احراز هویت کپی کنید.

آزمایش رایگان را شروع کنید همهٔ نقاط پایانی

Get contacts

نقاط پایانی مرتبط

این نقطهٔ پایانی را روی شمارهٔ خودتان امتحان کنید