API WhatsApp z PHP: Kompletny przewodnik integracji

Q: Jak zintegrować API WhatsApp w PHP?

Utwórz klienta Guzzle skierowanego na interfejs API Unipile REST, wywołaj POST /api/v1/accounts z dostawcą WHATSAPP, aby uzyskać kod QR lub kod parowania, poproś użytkownika o dokończenie procesu na telefonie, a następnie użyj tego samego klienta do wywołań GET, POST i PATCH w celu wysyłania wiadomości, listowania czatów i zarządzania grupami. Nie ma punktu końcowego specyficznego dla języka PHP, każde wywołanie jest normalnym żądaniem HTTP z nagłówkiem X-API-KEY.

Q: Czy można wysłać wiadomość WhatsApp programowo za pomocą PHP?

Tak. Pojedyncze żądanie POST na adres /api/v1/chats/{chat_id}/messages z polem tekstowym w treści wieloczęściowej (multipart) wysyła wiadomość i zwraca message_id.

Q: Czy istnieje oficjalne SDK PHP do Unipile?

Brak aktywnie utrzymywanego pakietu. Pakiet społecznościowy unipile/unipile-php-sdk jest wymieniony na Packagist, ale został oznaczony jako porzucony, bez żadnych commitów od 17 października 2023 roku. Zamiast tego każdy przykład w tym przewodniku wywołuje bezpośrednio interfejs API REST za pomocą Guzzle.

Q: Czy API WhatsApp działa z Laraserve? / Czy API WhatsApp działa z Laravel?

Tak, nic w tym nie jest specyficzne dla frameworka. Te same wywołania można owinąć w fasadę Http, zakolejkowane zadanie oraz routing i kontroler webhooka, co jest idiomatycznym sposobem strukturyzacji tego w kodzie Laravela.

Q: Czy jedna aplikacja PHP może zarządzać kontami WhatsApp dla wielu użytkowników końcowych?

Tak, to standardowy model SaaS. Jeden klucz API Unipile obsługuje całą aplikację, podczas gdy każdy użytkownik końcowy otrzymuje własny identyfikator `account_id` po połączeniu swojego WhatsAppa. Zapisz ten identyfikator obok rekordu swojego tenanta i przekazuj go w wywołaniach wychodzących, aby zapobiec wysyłaniu wiadomości do niewłaściwych tenantów.

Q: Jak dodać kogoś do grupy na WhatsAppie z poziomu PHP?

PATCH /api/v1/chats/{chat_id} z akcją ustawioną na addParticipant i wartością ustawioną na identyfikator WhatsApp uczestnika. Własna funkcja grupowa Cloud API od Meta nie ma odpowiedniego punktu końcowego, a jedynie link do zaproszenia.

Q: Dlaczego emoji psują się w wiadomościach WhatsApp wysyłanych z PHP?

Prawie zawsze dlatego, że ciąg znaków został obcięty za pomocą funkcji substr() zamiast mb_substr(). Zwykłe funkcje ciągów znaków w PHP liczą bajty, a emoji to wielobajtowa sekwencja UTF-8 – obcięta w środku zamienia się w nieprawidłowy znak lub uszkadza ładunek JSON.

Q: Czy Guzzle działa, czy potrzebujesz bezpośrednio cURL?

Guzzle w zupełności wystarcza, jest to klient HTTP zbudowany w oparciu o rozszerzenie cURL języka PHP, a nie jego zamiennik. Bezpośrednie wywołanie curl_init() działa identycznie, jeśli projekt nie może dodać tej zależności.

Spis treści

Podstawy

01 Czym jest API WhatsApp w PHP? 02 Którego API WhatsApp powinieneś używać? 03 Co jest potrzebne przed napisaniem kodu

Połącz i wyślij

04 Połącz konto WhatsAppNajlepszy 05 Wyślij wiadomość za pomocą Guzzle 06 Rozpocznij nową rozmowę 07 Pobierz czaty i wiadomości

Produkcja

08 Odbieraj wiadomości za pomocą webhooka 09 Zintegruj z aplikacją Laravel 10 Zarządzaj grupami WhatsApp

Skala, Koszty i FAQ

11 Obsługa wielu kont użytkowników 12 Częste błędy specyficzne dla PHP 13 Koszt wiadomości FAQ Często zadawane pytania

Przewodnik po WhatsApp API w PHP

API WhatsApp z PHPKompletny przewodnik integracji

Wywołania Guzzle i cURL w celu połączenia konta WhatsApp, wysyłania i odbierania wiadomości, zarządzania grupami i uruchomienia całości w ramach Laravel aplikacja, bez rejestrowania aplikacji Meta Business. To jest API WhatsApp w PHP od początku do końca: połączenie, webhooks, multi-tenant SaaS i rzeczywisty koszt jednej wiadomości.

Zacznij budować za darmo Przejdź do kodu

Brak weryfikacji Meta Business

Guzzle i cURL, brak porzuconego SDK

connect-whatsapp.php

użyj GuzzleHttp\Client;

$client = nowy Klient([
  'base_uri' => 'https://api1.unipile.com:13111',
  'headers' => ['Klucz API X' => $apiKey],
]);

// Dostawca WHATSAPP: brak aplikacji Meta, brak WABA
$res = $client->stanowisko('/api/v1/accounts', [
  'json' => ['provider' => 'WHATSAPP'],
]);

201 Utworzono, zwrócono account_id

Ten sam wzorzec dla

Definicja

Czym jest API WhatsApp w PHP?

The API WhatsApp w PHP to praktyka wywoływania API REST WhatsApp ze środowiska wykonawczego PHP, PHP-FPM, skryptu CLI lub workera kolejki przy użyciu klienta HTTP, takiego jak Guzzle lub cURL. Nie istnieje żadne API WhatsApp zbudowane specjalnie dla PHP: Meta i dostawcy API udostępniają zwykły JSON przez HTTPS, a PHP jest po prostu językiem wykonującym żądanie, w taki sam sposób, w jaki wywołałoby każde inne API webowe.

W praktyce integracja WhatsApp API z PHP to zwykłe wywołanie HTTP: metoda, adres URL, ciało w formacie JSON lub multipart oraz X-API-KEY header. Nic tutaj nie zależy od funkcji dostępnej wyłącznie w PHP ani od punktu końcowego przeznaczonego tylko dla PHP. To, co się zmienia między Cloud API, dostawcą rozwiązania biznesowego (BSP) a połączonym kontem, to nie język, lecz to, do kogo należy numer WhatsApp oraz czy weryfikacja Meta Business znajduje się pomiędzy Tobą a Twoją pierwszą wiadomością. Pełne podsumowanie tego ekosystemu można znaleźć w Przewodnik integracji WhatsApp API.

Zwykły JSON przez HTTPS

Każde wywołanie to cykl żądania i odpowiedzi, który Guzzle lub cURL już potrafią wykonać.

Autoryzacja to statyczny nagłówek

An X-API-KEY wartość, zero tanńca z OAuth, brak pętli odświeżania tokenów do napisania.

Niezależny od środowiska uruchomieniowego

Działa tak samo w PHP-FPM, poleceniu konsolowym Symfony lub zadaniu kolejki Laravel.

Decyzja

Którego API WhatsApp powinieneś używać w PHP?

Istnieją trzy sposoby na wywołanie WhatsApp z backendu PHP: Cloud API od Meta bezpośrednio, a Dostawca Rozwiązań Biznesowych odsprzedawanie do niego dostępu lub powiązane konto poprzez zunifikowane API, takie jak Unipile. Wszystkie trzy zwracają format JSON, który Twój kod PHP przetwarza w taki sam sposób; zmienia się czas konfiguracji, to, czy weryfikacja Meta Business stoi na drodze Twojej pierwszej wiadomości, oraz czy otrzymujesz istniejącą historię konwersacji, czy zaczynasz od zera.

Kryteria

Cloud API (bezpośrednie)

BSP

Powiązane konto

Weryfikacja firm w Meta

Wymagany

Niewymagane

Czas do pierwszej wiadomości

Od kilku dni do kilku tygodni

Szybszy onboarding, te same wymagania pod spodem

Protokół

Numer telefonu

Nowy numer zarejestrowany w WABA

Nowy numer udostępniony przez BSP

Własny numer WhatsApp użytkownika

Dostęp do istniejących konwersacji

Nie, zaczyna się pusty

Tak, pełna historia

Najlepsze dopasowanie

Jeden numer firmowy nadający do wielu klientów

To samo, z zarządzaną warstwą wdrażania

Produkt, w którym każdy użytkownik powiązuje konto WhatsApp, które już posiada

Jeśli Twoja aplikacja PHP to produkt SaaS, w którym każdy klient podpina swój własny numer WhatsApp, powiązane konto całkowicie eliminuje etap weryfikacji przez Meta. Jeśli natomiast wysyłasz wiadomości masowe z numeru jednej firmy, właściwym punktem wyjścia jest Cloud API lub BSP.

Utwórz za pomocą połączonego konta

Konfiguracja

Czego potrzebujesz przed napisaniem jakiegokolwiek kodu w PHP?

Potrzebujesz PHP 8.1 lub nowszy, Kompozytor, the Guzzle klient HTTP i klucz API Unipile. Obecnie nie ma aktywnie utrzymywanego pakietu SDK PHP dla Unipile, więc każdy przykład w tym przewodniku odwołuje się do /api/v1 Bezpośrednio REST API.

PHP 8.1+

Wpisane właściwości i nazwane argumenty pozwalają zachować zwięzłość kodu klienta.

Kompozytor

Standardowy menedżer zależności, wymagany do pobrania Guzzle.

Guzzle 7

Klient HTTP do zapytań w formacie JSON i wieloczęściowych (multipart), z mechanizmem awaryjnym (fallback) opartym na cURL.

Klucz API Unipile

Wysłano jako X-API-KEY na każde żądanie, wygenerowane z Twojego panelu.

terminal

composer require guzzlehttp/guzzle:^7.0

Czy istnieje pakiet SDK dla PHP? Nie taki, który trzeba instalować.

Pakiet społecznościowy, unipile/unipile-php-sdk, istnieje na Packagist, ale jest wymieniony jako porzucony: brak commitów od 17 października 2023 r., 5 gwiazdek na GitHubie i celuje w stary adres bazowy API. Nie uruchamiaj composer require unipile/unipile-php-sdk. Zestaw SDK dla Node.js (unipile-node-sdk) jest oficjalnie utrzymywane i aktualne, ale w przypadku PHP niezawodną ścieżką jest Guzzle bezpośrednio w interfejsie API REST i tego używa każdy poniższy przykład. Zobacz Dokumentacja Guzzle dla opcji klienta użytych tutaj.

Implementacja

Jak połączyć konto WhatsApp z poziomu PHP?

Połączenie konta WhatsApp z poziomu PHP zajmuje jedno POST żądanie z dostawcą ustawionym na WHATSAPP, a następnie jedna akcja użytkownika: użytkownik końcowy skanuje zwrócony kod QR z poziomu WhatsApp > Powiązane urządzenia lub wpisuje kod parowania w telefonie, jeśli zamiast tego o niego poprosiłeś. Żadnej aplikacji deweloperskiej Meta, żadnego WABA, żadnego kroku weryfikacji.

1

Żądaj punktu kontrolnego, domyślnie kod QR

Wywołaj punkt końcowy kont (accounts) używając tylko provider zestaw. Unipile zwraca account_id plusz ładunek punktu kontrolnego zbudowany dla przepływu QR.

connect-qr.php

$response = $client->stanowisko('/api/v1/accounts', [
    'json' => ['provider' => 'WHATSAPP'],
]);

$payload = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$accountId = $payload['id_konta'];

// $payload zawiera również punkt kontrolny do wyrenderowania do
// użytkownik końcowy: kod QR do zeskanowania z poziomu WhatsApp > Połączone urządzenia
// urządzenia. var_dump($payload) – spróbuj jeszcze raz z własnym kluczem
// aby zobaczyć dokładny kształt przed podłączeniem frontend'u.

2

Lub poproś o kod parowania

Podanie parowanie_numeru_telefonu w cyfrach E.164, bez znaku plus, gdy skanowanie kodu QR jest niepraktyczne, na przykład gdy konsultant pomocy technicznej wdraża klienta przez telefon.

connect-pairing.php

$response = $client->stanowisko('/api/v1/accounts', [
    'json' => [
        'provider' => 'WHATSAPP',
        'pairing_phone_number' => '33612345678',
    ],
]);

$payload = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$accountId = $payload['id_konta'];

// Punkt kontrolny w tym miejscu to kod, który Twój interfejs pokazuje użytkownikowi
// wpisz w WhatsApp > Powiązane urządzenia > Połącz z
// zamiast tego numer telefonu.

3

Sondżuj, aż konto zostanie w pełni powiązane

Konto pozostaje w POŁĄCZENIE stan do momentu zeskanowania kodu QR lub wprowadzenia kodu parowania. Sprawdź sources[0].status na koncie.

poll-status.php

$response = $client->uzyskać(""/api/v1/accounts/{$accountId}"");
$account = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$status = $account['źródła'][0]['status'] ?? null;

jeśli ($status === 'OK') {
    // można bezpiecznie wysyłać, odbierać i wyświetlać listę czatów na koncie o identyfikatorze $accountId
}

Odpytywanie w pętli działa, ale marnuje zapytania. Jeśli Twoja aplikacja w PHP ma już punkt końcowy webhooka, zarejestruj go w status_konta" zamiast tego i zareaguj w momencie, gdy status zmieni się na OK. Konfiguracja samego webhooka dla wiadomości przychodzących została omówiona poniżej, ten sam punkt końcowy obsługuje zdarzenia statusu konta.

Zbuduj przepływ połączenia

Główny przepływ

Jak wysłać wiadomość przez WhatsApp za pomocą PHP i Guzzle?

Wysłanie wiadomości z PHP to jedno POST do punktu końcowego wiadomości czatu za pomocą text pole w ciele multipart. Wywołanie zwraca id_wiadomosci natychmiast, gdy WhatsApp to zaakceptuje.

wyslij-wiadomosc.php

$response = $client->stanowisko(""/api/v1/chats/{$chatId}/messages"", [
    'multipart' => [
        ['imię' => 'tekst', 'zawartość' => 'Cześć! Twoje zamówienie zostało wysłane.'],
    ],
]);

$result = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$messageId = $result['message_id'];

To samo wieloczęściowy tablica również niesie załączniki, a voice_message plik lub id_cytatu aby odpowiedzieć na określoną wiadomość, Guzzle dołącza je jako dodatkowe pola wieloczęściowe (multipart) obok text. Aby zapoznać się z pełnym zestawieniem każdego rodzaje wiadomości obsługiwane przez interfejs API WhatsApp, w tym szablony i 24-godzinne okno serwisowe, można znaleźć w naszym dedykowanym przewodniku.

Główny przepływ

Jak rozpocząć nową konwersację z poziomu PHP?

Rozpoczęcie nieistniejącej jeszcze konwersacji oznacza wywołanie punktu końcowego czatów za pomocą account_id i a attendees_ids tablica zamiast istniejącej chat_id. Unipile tworzy czat i, jeśli uwzględnisz text pole, wysyła pierwszą wiadomość w tym samym wywołaniu.

rozpocznij-konwersacje.php

$response = $client->stanowisko('/api/v1/chats', [
    'multipart' => [
        ['imię' => 'id_konta', 'zawartość' => [$accountId],
        ['imię' => 'attendees_ids[]', 'zawartość' => '33612345678@s.whatsapp.net'],
        ['imię' => 'tekst', 'zawartość' => 'Cześć, tu wsparcie techniczne Acme.'],
    ],
]);

$result = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$chatId = $result['chat_id'];

Odbiorca jest identyfikowany przez {phone_number}@s.whatsapp.net, cyfry międzynarodowe, bez wiodącego plusa, bez spacji. Zapisz zwrócone chat_id obok tego rekordu użytkownika: każda wiadomość po pierwszej przechodzi przez punkt końcowy wiadomości z poprzedniej sekcji, a nie przez tę.

Główny przepływ

Jak pobrać czaty i wiadomości w PHP?

Większość poradników dotyczących API WhatsApp kończy się na wysyłaniu wiadomości. Zaplecze w PHP zazwyczaj musi również wyświetlać listę istniejących konwersji użytkownika, przeglądać ich historię oraz sprawdzać, kto bierze udział w czacie. Obejmują to trzy punkty końcowe: GET /api/v1/chats, GET /api/v1/chats/{chat_id}/messagesoraz GET /api/v1/chats/{chat_id}/attendees, wszystkie paginowane za pomocą kursora.

Wymień wszystkie czaty WhatsApp na koncie

list-chats.php

$response = $client->uzyskać('/api/v1/chats', [
    'query' => [
        ''account_id' => $accountId,
        'account_type' => 'WHATSAPP',
        'limit' => 50,
    ],
]);

$data = json_decode($response->Pobierz treść()->pobierzZawartość(), true);
$chats = $data['elementy'];
$nextCursor = $data['kursor'];

Przejrzyj historię jednej konwersacji

list-messages.php

$cursor = null;
$all = [];

do {
    $res = $client->uzyskać(""/api/v1/chats/{$chatId}/messages"", [
        'zapytanie' => array_filter(['kursor' => $cursor, 'ograniczenie' => 100]),
    ]);
    $page = json_decode($res->Pobierz treść()->pobierzZawartość(), true);
    $all = array_merge($all, $page['elementy']);
    $cursor = $page['kursor'];
} podczas ($cursor !== null);

Każdy punkt końcowy listy stosuje tę samą umowę kursora: przekazać odpowiedź z poprzedniego kursor cofnij się, zatrzymaj się, kiedy wróci null. Aby zobaczyć, kto faktycznie bierze udział w konwersacji, wywołaj GET /api/v1/chats/{chat_id}/attendees: zwraca każdego uczestnika id, provider_id i wyświetlaną nazwę, której potrzebujesz, zanim będziesz mógł wykonać połączenie dodajUczestnika lub usuńUczestnika w grupie w dalszej części tego przewodnika.

Produkcja

Jak odbierać wiadomości z WhatsApp za pomocą webhooka w PHP?

Webhook WhatsApp w PHP to publiczny punkt końcowy HTTPS, który Unipile wywołuje z ładunkiem JSON w przypadku zdarzeń takich jak message_received. Twój skrypt odczytuje surową treść (body), potwierdza autentyczność wywołania, szybko odpowiada i przekazuje właściwą pracę do kolejki. Odpytywanie GET /api/v1/chats dla nowych wiadomości działa w przypadku wersji demo, ale nie dla produktu z czymś więcej niż tylko garstką użytkowników.

1. Zarejestruj webhook ze wspólnym kluczem tajnym w niestandardowym nagłówku

register-webhook.php

$client->stanowisko('/api/v1/webhooks', [
    'json' => [
        'source' => 'wiadomości',
        'request_url' => 'https://example.com/webhooks/whatsapp',
        'events' => ['wiadomość_odebrana'],
        'headers' => [
            ['klucz' => 'X-Webhook-Secret', 'wartość' => [$webhookSecret],
        ],
    ],
]);

2. Sprawdź, odpowiedz, a następnie przetwórz

public/webhooks/whatsapp.php

$rawBody = file_get_contents('php://input');
$provided = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';

jeśli (!hash_equals($expectedSecret, $provided)) {
    http_response_code(401);
    Wyjdź;
}

http_response_code(200);
jeśli (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

$payload = json_decode($rawBody, true);

jeśli (($payload['zdarzenie'] ?? null) === 'wiadomość_odebrana') {
    // umieść ładunek $ w tabeli kolejki lub na liście Redis,
    // nigdy nie przetwarzaj webhooka wewnątrz głównego wątku
    kolejkuj_wiadomość_whatsapp($payload);
}

Unipile nie podpisuje treści webhooka za pomocą sekretu HMAC, który obliczasz ponownie, endpoint tworzenia webhooka udostępnia nagłówki zamiast tego tablicę. Dołącz swój własny sekret jako niestandardowy nagłówek podczas rejestracji webhooka, a następnie sprawdź go za pomocą hash_equals(), czyli odporne na timing-attack porównanie ciągów znaków, przed zaufaniem payloadowi. Każde pole w $payload, account_id, typ_konta, wydarzenie, chat_id, id_wiadomosci, message oraz sender.attendee_provider_id, pasuje do dokumentów JSON Unipile dla webhooka obsługującego wiadomości.

Produkcja

Jak zintegrować API WhatsApp z aplikacją Laravel?

Laravel zastępuje trzy rzeczy z powyższych przykładów w czystym PHP: HTTP fasada zamiast napisanego od zera klienta Guzzle, kolejkowane zadanie zamiast przetwarzania w miejscu oraz trasa i kontroler zamiast parsowania php://input ręcznie. Połączenia przez WhatsApp poniżej są identyczne z każdym przykładem zawartym już w tym przewodniku.

1. KonfiguracjaJeden wpis w services.php, wartości z pliku .env

config/services.php

return [
    // ...istniejące usługi
    'unipile' => [
        'base_uri' => środowisko('UNIPILE_BASE_URI', 'https://api1.unipile.com:13111'),
        'klucz_api' => środowisko('UNIPILE_API_KEY'),
        'webhook_secret' => środowisko('UNIPILE_WEBHOOK_SECRET'),
    ],
];

2. Cienka klasa serwisowa nad fasadą Http

app/Services/WhatsappService.php

przestrzeń nazw App\Services;

użyj Illuminate\Support\Facades\Http;

klasa UsługaWhatsApp
{
    chroniony funkcja klient()
    {
        return Http::baseUrl(konfiguracja('services.unipile.base_uri'))
            ->z nagłówkami(['Klucz API X' => konfiguracja('services.unipile.api_key')]);
    }

    publiczny funkcja sendMessage(łańcuch $chatId, łańcuch ($text): tablica
    {
        return $this->klient()
            ->jakoWieloczęściowy()
            ->stanowisko(""/api/v1/chats/{$chatId}/messages"", [
                ['imię' => 'tekst', 'zawartość' => [$text],
            ])
            ->json();
    }
}

3. Kontroler tras i webhooków

trasy/api.php

Trasa::stanowisko('/webhooks/whatsapp', [WhatsappWebhookController::klasa, 'uchwyt']);

app/Http/Controllers/WhatsappWebhookController.php

public function handle(Request $request)
{
    $provided = $request->header('X-Webhook-Secret', '');

    if (!hash_equals(config('services.unipile.webhook_secret'), $provided)) {
        abort(401);
    }

    if ($request->input('event') === 'message_received') {
        ProcessWhatsappMessage::dispatch($request->all());
    }

    return response()->json(['status' => 'received']);
}

4. Zadanie w kolejce, dzięki czemu ścieżka webhooka pozostaje szybka

app/Jobs/ProcessWhatsappMessage.php

klasa PrzetwórzWiadomośćWhatsapp wdraża ShouldQueue
{
    użyj Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    publiczny funkcja __construct(publiczny tablica $payload) {}

    publiczny funkcja klamka(): pustka
    {
        // wyszukaj najemcę na podstawie $this->payload['account_id'],
        // zapisz wiadomość, powiadom właściwego użytkownika
    }
}

Trasa nigdy nie przebiega bezpośrednio przez Guzzle, prowadzi przez UsługaWhatsApp, co sprawia, że połączenia przez WhatsApp można symulować w testach w taki sam sposób, jak w przypadku każdej innej integracji HTTP w Laravelu. Zobacz Dokumentacja klienta HTTP w Laravelu za symulowanie tych żądań w swoim zestawie testowym.

Zbuduj to w Laravelu

Produkcja

Jak zarządzać grupami WhatsApp za pomocą PHP?

Zarządzanie grupą na WhatsAppie za pomocą PHP to prosta sprawa PATCH wywołanie punktu końcowego czatu z akcja pole dodajUczestnika, usuńUczestnikalub pobierzLinkZaproszenia. W przypadku własnych grup Cloud API firmy Meta maksymalna liczba członków w grupie wynosi 8 uczestników i nie udostępnia żadnego punktu końcowego umożliwiającego bezpośrednie dodanie osoby, a jedynie link z zaproszeniem, który można udostępnić.

Dodaj uczestnika

add-participant.php

$client->poprawka(""/api/v1/chats/{$groupChatId}"", [
    'json' => [
        'action' => 'dodajUczestnika',
        'value' => '33612345678@s.whatsapp.net',
    ],
]);

Pobierz link zaproszenia

link-zaproszenia.php

$res = $client->poprawka(""/api/v1/chats/{$groupChatId}"", [
    'json' => ['action' => 'pobierzLinkZaproszenia'],
]);

$link = json_decode($res->Pobierz treść()->pobierzZawartość(), true)['link_zaproszenia'];

usuńUczestnika przybiera taki sam kształt jak dodajUczestnika, z identyfikatorem WhatsApp uczestnika w wartość. Jest to jedyna operacja, której własny interfejs API grup firmy Meta w ogóle nie udostępnia – dodanie osoby odbywa się wyłącznie za pośrednictwem linku zaproszeniowego po stronie tej osoby. Informacje na temat wszystkich ograniczeń, w tym limitu 10 000 grup na numer oraz funkcji, które nadal nie są obsługiwane, można znaleźć w API grupy WhatsApp odniesienie.

Zarządzanie grupami budowlanymi

Skala

Jak zarządzać wieloma kontami użytkowników w ramach jednej aplikacji PHP?

Produkt PHP typu SaaS nie posiada jednego konta WhatsApp, lecz jedno konto na każdego klienta. Istnieje tylko jedna platforma Unipile X-API-KEY dla całej aplikacji, ale odrębny account_id dla każdego użytkownika końcowego, który połączy swój WhatsApp. Schemat polega na zapisywaniu tego account_id obok własnego wiersza najemcy i przekazywać go jawnie przy każdym wywołaniu, które w przeciwnym razie mogłoby obejmować różne konta.

route-by-tenant.php

// Wewnątrz procedury obsługi webhooka: znajdź, do którego tenanta to
// ta wiadomość dotyczy momentu przed zrobieniem z nią czegokolwiek.
$stmt = $pdo->przygotuj('SELECT id FROM tenants WHERE unipile_account_id = ?');
$stmt->wykonaj([$payload['id_konta']]);
$tenantId = $stmt->pobierzKolumnę();

jeśli ($tenantId === fałszywy) {
    // nieznane account_id, odrzuć zamiast zgadywać tenant
    http_response_code(404);
    Wyjdź;
}

// Wychodzące: przekazaj account_id, aby nieaktualny lub ponownie użyty chat_id mógł
// nigdy nie wysyłaj przez numer WhatsApp niewłaściwego najemcy.
$client->stanowisko(""/api/v1/chats/{$chatId}/messages"", [
    'multipart' => [
        ['imię' => 'tekst', 'zawartość' => [$text],
        ['imię' => 'id_konta', 'zawartość' => [$expectedAccountId],
    ],
]);

Opcjonalny account_id pole w punkcie końcowym wiadomości istnieje specjalnie po to, aby zapobiec wysyłaniu w czacie poza tym kontem, należy traktować je jako obowiązkowe w kodzie wielodostępnym, mimo że interfejs API tego nie wymaga. Zaszyfruj przechowywane account_id dane przechowywane w stanie spoczynku, podobnie jak wszelkie inne dane uwierzytelniające klientów: same w sobie nie są poufne, ale stanowią klucz łączący tabelę użytkowników z prawdziwymi rozmowami danej osoby w WhatsApp.

Pułapki

Jakie są najczęstsze błędy specyficzne dla języka PHP?

Większość błędów API WhatsApp w bazie kodu PHP wynika z samego PHP, a nie z samego API. Te pięć powtarza się regularnie w integracjach produkcyjnych.

Obcinanie wiadomości za pomocą funkcji substr() zamiast mb_substr()

PHP-a substr() liczy bajty, a nie znaki. Emoji to wielobajtowa sekwencja UTF-8, po przepołowieniu wysyłasz uszkodzony znak lub niepoprawny JSON. Zawsze używaj funkcji wielobajtowych dla generowanego przez użytkownika tekstu na WhatsAppie.

Naprawić

$safe = mb_substr($text, 0, 4096, 'UTF-8');

Błąd cURL 60 w systemie Windows i XAMPP

"Problem z certyfikatem SSL: nie można uzyskać certyfikatu lokalnego wystawcy. Kompilacje PHP dla systemu Windows oraz XAMPP są często dostarczane bez aktualnego zestawu urządzeń CA skonfigurowanego w pliku php.ini, przez co wywołania HTTPS biblioteki Guzzle kończą się niepowodzeniem, mimo że kod jest poprawny.

Napraw, php.ini

curl.cainfo = "C:\php\extras\cacert.pem"
openssl.cafile = "C:\php\extras\cacert.pem"

max_execution_time zabija webhook zanim zdąż odpowiedzieć

Domyślny czas 30 sekund w zupełności wystarcza, dopóki handler nie wykona powolnego połączenia wychodowego przed udzieleniem odpowiedzi. Jeśli Unipile nie otrzyma szybkiej odpowiedzi, ponawia próbę, a powolny handler zaczyna przetwarzać tę samą wiadomość dwukrotnie. Najpierw wyślij odpowiedź, a dopiero potem wykonaj pracę, jak pokazano w powyższej sekcji dotyczącej webhooków.

Brak opóźnienia zwrotnego (backoff) przy odpowiedziach 429 lub 5xx

Ciasny podczas Pętla, która ponawia próbę natychmiast w przypadku niepowodzenia, zamienia jeden limit żądań w awarię na własne życzenie. Odczekaj i zwiększaj czas oczekiwania przy każdym kolejnym niepowodzeniu.

Naprawić

dla ($attempt = 1; $attempt <= 5; $attempt++) {
    próbuj {
        return $client->stanowisko($uri, $options);
    } połów (ConnectException | ServerException $e) {
        usleep((2 ** $attempt) * 100_000); // 0,2 s, 0,4 s, 0,8 s...
    }
}

Logowanie surowej odpowiedzi i nazywanie tego debugowaniem

Jeśli budujesz ciało JSON ręcznie zamiast pozwolić Guzzle json opcja obsłuż to, dodaj JSON_UNESCAPED_UNICODE do json_encode(). Bez tego emoji oraz nazwy z akcentami wyświetlają się jako znaki ucieczki \u sekwencje w Twoich logach, co jest technicznie poprawnym JSON-em, ale jest nieczytelne, gdy próbujesz debugować prawdziwą rozmowę.

Koszt

Ile kosztuje wysyłanie wiadomości WhatsApp z poziomu PHP?

Nic w kodzie PHP nie zmienia ceny. Meta nalicza opłaty za wiadomość od 1 lipca 2025 r., a nie na konwersację. Jedyną rzeczą, którą kontroluje Twój kod, jest czas: odpowiedź o dowolnej treści można wysłać tylko w ciągu 24-godzinnego okna serwisowego po wiadomości użytkownika, a od 1 października 2026 r. jest ona bezpłatna tylko dla pierwszych 1000 wiadomości serwisowych na numer miesięcznie.

Szablony narzędziowe i uwierzytelniania są od 1 października 2026 r. rozliczane przy każdym dostarczeniu, w oknie serwisowym i poza nim.

Szablony marketingowe są rozliczane niezależnie od okna.

Stawki za wiadomość zależą od kraju odbiorcy i kategorii wiadomości, a nie od biblioteki klienta, za pomocą której je wysyłasz.

Oznaczaj znacznikiem czasu każdą wiadomość przychodzącą otrzymywaną przez Twój webhook PHP i utrzymuj dla każdej konwersji wartość "okno otwarte do", która jest jedynym danym wejściowym, jakiego faktycznie potrzebuje Twoja logika rozliczeniowa. W przypadku bieżącego cennik WhatsApp za każdą wiadomość Zobacz pełne zestawienie cen według krajów i kategorii.

API WhatsApp z PHP – FAQ

Konkretne odpowiedzi na tematy: łączenie, wysyłanie, Laravel i porzucone PHP SDK.

01 Jak zintegrować API WhatsApp w PHP?

Utwórz klienta Guzzle skierowanego na REST API Unipile, wywołaj POST /api/v1/accounts z dostawcą WHATSAPP aby uzyskać kod QR lub kod parowania, poproś użytkownika o dokończenie tej czynności na telefonie, a następnie użyj tego samego klienta do GET, POST oraz PATCH wywołania do wysyłania wiadomości, wyświetlania listy czatów i zarządzania grupami. Nie ma punktu końcowego specyficznego dla PHP, każde wywołanie to zwykłe żądanie HTTP z X-API-KEY nagłówek. Ten połącz konto WhatsApp Sekcja powyżej omawia dokładny kod.

02 Czy można wysłać wiadomość WhatsApp programowo za pomocą PHP?

Tak. Pojedynczy POST do /api/v1/czaty/{chat_id}/wiadomości with a text pole w ciele wieloczęściowym (multipart) wysyła wiadomość i zwraca id_wiadomosci, zobacz wyślij sekcję powyżej dla dokładnego wywołania Guzzle.

03 Czy do korzystania z WhatsAppa za pomocą PHP wymagana jest weryfikacja Meta Business?

Tylko jeśli korzystasz bezpośrednio z interfejsu Cloud API od Meta lub z dostawcy rozwiązań biznesowych (Business Solution Provider), który na nim bazuje. Połączenie konta WhatsApp przez Unipile podpina istniejący numer WhatsApp użytkownika za pomocą kodu QR lub kodu parowania i w ogóle nie wymaga weryfikacji biznesowej Meta.

04 Czy istnieje oficjalne SDK PHP do Unipile?

Brak aktywowanej wersji. Pakiet społecznościowy, unipile/unipile-php-sdk, jest w serwisie Packagist, ale jest oznaczony porzucony, z żadnym commitem od 17 października 2023 r. i 5 gwiazdkami na GitHubie. Zamiast tego każdy przykład w tym przewodniku wywołuje bezpośrednio REST API za pośrednictwem Guzzle, co robił również porzucony SDK wewnętrznie.

05 Jak odbierać wiadomości WhatsApp w PHP bez publicznego serwera?

Nie możesz odbierać webhooków bez publicznie dostępnego adresu URL HTTPS, tak właśnie działają wywołania zwrotne HTTP. Podczas lokalnego programowania utwórz tunel do lokalnego portu za pomocą usługi takiej jak ngrok i skieruj go na webhooka request_url pod adresem HTTPS tunelu. Odpytywanie punktu końcowego wiadomości jest rozwiązaniem zapasowym, gdy publiczny punkt końcowy rzeczywiście nie jest możliwy, kosztem opóźnienia i dodatkowych żądań.

06 Czy API WhatsApp działa z Laraserve? / Czy API WhatsApp działa z Laravel?

Tak, nic w tym nie jest specyficzne dla frameworka. Sekcja Laravel powyżej owija takie same wywołania będące odpowiednikami Guzzle w HTTP Fasada, zakolejkowane zadanie oraz ruta i kontroler webhooka – oto idiomatyczny sposób ich strukturyzacji w bazie kodu Laravel.

07 Czy jedna aplikacja PHP może zarządzać kontami WhatsApp dla wielu użytkowników końcowych?

Tak, to jest standardowy model SaaS. Jeden klucz API Unipile obsługuje całą aplikację, podczas gdy każdy użytkownik końcowy otrzymuje swój własny. account_id po połączeniu ich WhatsAppa. Zapisz to ID obok rekordu najemcy i przekaż je przy połączeniach wychodzących, aby zapobiec wysyłaniu między najemcami, zobacz sekcja wielodostępna powyżej.

08 Jak dodać kogoś do grupy na WhatsAppie z poziomu PHP?

PATCH /api/v1/chats/{chat_id} z {"action": "addParticipant", "value": "@s.whatsapp.net"}. Własna funkcja grup Cloud API od Meta nie ma odpowiednika w postaci punktu końcowego, a jedynie link zaproszenia, co jest jedną z wyraźniejszych różnic między budowaniem bezpośrednio na platformie Meta a skorzystaniem z Unipile. Szczegóły w sekcja grup powyżej.

09 Dlaczego emoji psują się w wiadomościach WhatsApp wysyłanych z PHP?

Prawie zawsze dlatego, że ciąg znaków został obcięty z substr() zamiast mb_substr(). Zwykłe funkcje ciągów znaków w PHP liczą bajty, a emoji to wielobajtowa sekwencja UTF-8 – ucięta w połowie zamienia się w nieprawidłowy znak lub całkowicie psuje ładunek JSON.

10 Czy Guzzle działa, czy potrzebujesz bezpośrednio cURL?

Guzzle wystarcza, jest to klient HTTP zbudowany w oparciu o rozszerzenie cURL języka PHP, a nie jego zamiennik. Każde zapytanie w tym przewodniku używa Guzzle; surowy curl_init() call działa dokładnie tak samo, jeśli projekt nie może dodać zależności, ciała w formacie JSON i multipart są w obu przypadkach takie same.

11 Ile kosztuje wysłanie wiadomości WhatsApp z poziomu PHP?

Tak samo jak w przypadku wysyłania w inny sposób. Meta nalicza opłaty za wiadomość od 1 lipca 2025 r. w oparciu o kategorię i kraj odbiorcy, a nie o bibliotekę kliencką użytą do wywołania interfejsu API. Zobacz sekcja kosztów powyżej i kompletny przewodnik cenowy dla aktualnych stawek.

12 Czy 24-godzinne okno serwisowe WhatsApp jest nadal aktualne w przypadku korzystania z języka PHP?

Tak, to nigdzie nie znika, określa po prostu, kiedy można wysłać odpowiedź o dowolnej treści zamiast płatnego szablonu. Odpowiedź w ciągu 24 godzin od ostatniej wiadomości użytkownika wlicza się do 1000 bezpłatnych wiadomości serwisowych na numer miesięcznie, natomiast kod PHP ignorujący to okno czasowe po prostu płaci za szablony, za które nie musiał płacić.

Masz jeszcze pytania dotyczące tworzenia tego w PHP? Nasz zespół jest tutaj, aby pomóc.

Porozmawiaj z ekspertem

Przewodnik po WhatsApp API w PHP

Gotowy na zintegrowanie API WhatsApp ze swoją aplikacją PHP?

Każdy punkt końcowy w tym przewodniku, connect, send, receive, groups, działa na tym samym koncie Unipile, które możesz utworzyć w tej chwili. Żadnej weryfikacji Meta Business, żadnego porzuconego SDK, po prostu Guzzle i REST API, które Twoja aplikacja PHP już potrafi wywoływać.

Skonfiguruj integrację z WhatsApp Przeczytaj dokumentację API

Automatyzacja zamiast integracji z istniejącą aplikacją? Przeczytaj ta sama integracja w Pythonie.