Witam w poradniku z którego będzie można się dowiedzieć w jaki sposób można wysyłać wiadomości z poziomu PHP do najpopularniejszej w Polsce sieci komunikatorów, sieci Gadu-Gadu. Ta wiedza da nam możliwość tworzenia szybkich i skutecznych systemów powiadamiania internautów o nowych postach czy wydarzeniach na naszych stronach internetowych. Zaczynamy!

Początek przygody

Aby zacząć pisać skrypt do wysyłania wiadomości na GG musimy wpierw pobrać mały plik z klasą do obsługi protokołu. Jest  on do pobrania tutaj. Wypakowywujemy go, dołączamy do naszego skryptu a także tworzymy obiekt tej klasy:

require_once('rfGG.class.php');
$GG = new rfGG(rfGG::VER_77);

Teraz musimy używając aplikacji GG lub innego zgodnego komunikatora np AQQ utworzyć konto dla naszego bota który będzie rozsyłał wiadomości. Nie możemy używać naszego konta. Gdy już mamy nowy numer i hasło możemy przystąpić do próby nawiązania połączenia z serwerem GG.

if ($GG->connect('123456789','hasłobota')) {
   $GG->disconnect();
}

Zmiana statusu i opisu

Klasa rfGG posiada funkcję changeStatus() która służy do zmiany statusu oraz opisu konta bota.

if ($GG->connect('123456789','hasłobota')) {
   $GG->changeStatus(rfGG::STATUS_BUSY_DESCR,'Code is poetry');
   //tutaj jakiś kod...
   $GG->disconnect('nie ma mnie');
}

W tym przykładzie ustawiliśmy status na STATUS_BUSY_DESCR a opis na Code is poetry. Poniżej zamieszczam listę wszystkich statusów oraz ich znaczeń.

• STATUS_NOT_AVAIL – niedostępny
• STATUS_NOT_AVIAL_DESCR – niedostępny z opisem
• STATUS_AVAILABLE - dostępny
• STATUS_AVAILABLE_DESCR – dostępny z opisem
• STATUS_BUSY - zajęty (zaraz wracam)
• STATUS_BUSY_DESCR – zajęty z opisem
• STATUS_INVISIBLE – niewidoczny
• STATUS_INVISIBLE_DESCR – niewidoczny z opisem

Przy statusach z opisem trzeba jako drugi argument funkcji podać tekst który będzie wyświetlany jako opis. Funkcja disconnect() służąca do rozłączania z serwerem automatycznie zmienia status na niedostępny i ewentualnie ustawia przekazany jej argument jako opis. W powyższym przykładzie skorzystaliśmy z tej możliwości i ustawiliśmy opis na nie ma mnie.

Wysyłanie wiadomości

Proszę zapiąć pasy ponieważ przechodzimy do ważnej części poradnika. Zajmijmy się teraz wysyłaniem wiadomości. Gdy już jesteśmy zalogowani w serwerze GG możemy to zrobić za pomocą odpowiedniej funkcji:

if ($GG->connect('123456789','hasłobota')) {
   $GG->sendMessage('300500800',"Treść <b>wiadomości</b>...");
   $GG->disconnect();
}

Funkcja ta to sendMessage() i przyjmuje dwa argumenty, numer odbiorcy oraz treść wysyłanej wiadomości. Jak widać w przykładzie wiadomość może zawierać tagi HTML. Dopuszczone są pogrubienia <b>, pochylenia <i>, podkreślenia <u> oraz złamanie linii za pomocą <br> lub \r\n. Funkcja po próbie wysłania wiadomość zwraca true lub false w zależności czy wszystko się udało. Można to wykorzystać do sprawdzenia powodzenia wysłania komunikatu i ewentualnie wyświetlić błąd przy użyciu getError().

if (!$GG->sendMessage($numer,$tresc)) {
   die($GG->getError());
}

Odbieranie wiadomości

Używana przez nas klasa zezwala również na odbieranie wiadomości. Robi się to za pomocą dwóch funkcji:  getMessages() i getMessageOne(). Najpierw omówimy tą pierwszą gdyż jest bardziej uniwersalna.

require_once('rfGG.class.php');
$GG = new rfGG(rfGG::VER_77);
if ($GG->connect('222333444','password')) {
   $GG->ping();
   $message = $GG->getMessages();
   for($i=0;$i<count($message);$i++){
      echo $message[$i]['sender'].'>'.$message[$i]['msg_text'].'<br>';
   }
   $GG->disconnect('Code is poetry');
}

Jak widać w powyższym kodzie przez przetworzeniem wiadomości wywołaliśmy funkcję ping() która ma za zadanie nawiązać kontakt z serwerem i pobrać czekające na nas dane. Należy tej funkcji używać zawsze przed funkcjami do wyświetlania wiadomości. Później możemy z otrzymaną tablicą wiadomości zrobić co chcemy. W tym przykładzie wyświetlamy numer z którego otrzymano informację oraz jej treść. Zwracana tablica ma zawsze ten sam schemat. Pierwszy jej wymiar to liczba porządkowa kolejnych wiadomości a drugi to elementy o indeksach sender (numer nadawcy), time (czas w formacie timestamp), msg_text (treść) i 2 inne, nie istotne dla nas.

Funkcja getMessageOne() działa podobnie tylko, że zwraca jedną wiadomość. Trzeba więc ją wykonywać wielokrotnie. Zwraca ona tablicę jednowymiarową z elementami o indeksach takich samych jak drugi wymiar poprzedniej funkcji.

Pewne zasady

Na koniec chciałbym zacytować fragment licencji z pliku używanej przez nas klasy:

• 4. Kategorycznie zabrania sie wykorzystywania kodu do rozsylania SPAMU oraz niechcianych wiadomosci.
• 5. Odbiorca wiadomosci musi wyrazic wczesniej zgode na ich otrzymywanie.
• 6. Zabrania sie wykorzystywania kodu do celow niezgodnych z prawem POLSKIM.
• 7. Na uzasadniona prosbe serwisu Gadu-Gadu nalezy usunac lub wylaczyc działanie kodu.

I ja również podpisuje się pod tym ponieważ nikt z nas przecież nie chce otrzymywać spamu na komunikator, prawda?