Platforma BotAPI GG

Dokumentacja

Poniżej opisana jest biblioteka BotAPI - zarówno w wersji PHP jak i Python - przy pomocy której najprościej jest stworzyć własnego bota.

Jeśli chcesz poznać protokół BotAPI aby stworzyć własną bibliotekę, przejdź do opisu protokołu.

Podstawowe pojęcia

  • Botmaster - serwer botów, łączący się z siecią GG i przekazujący wiadomości między użytkownikami a skryptem bota.
  • Autoryzacja - proces pobierania adresu Botmastera oraz tokena wymaganego do wysyłania wiadomości metodą PUSH oraz zmiany statusu/opisu bota.
  • Wiadomości przychodzące (PULL) - gdy użytkownik GG pisze na numer bota, Botmaster wywołuje (z odpowiednimi parametrami) skrypt udostępniony przez właściciela bota. Odpowiedź wygenerowana przez skrypt jest automatyczne przekazywana do użytkownika GG. Autoryzacja nie jest wymagana.
  • Wiadomości wychodzące (PUSH) - wiadomości wysyłane na żądanie twórcy bota do użytkowników bota. Wymagają autoryzacji.
  • Skrypt bota - skrypt po stronie twórcy bota korzystający z BotAPI.

Spis treści

  1. Opis biblioteki BotAPI 2
    1. Opis klasy MessageBuilder
      1. Konstruktor MessageBuilder
      2. Dodanie tekstu - metoda addText
      3. Dodanie obrazka - metoda addImage
      4. Ustawienie odbiorców wiadomości - metoda setRecipients
      5. Dodanie kodu HTML do wiadomości - metoda addRawHtml
      6. Zastąpienie wiadomości HTML - metoda setRawHtml
      7. Zastąpienie wiadomości tekstowej - metoda setAlternativeText
      8. Wysłanie wiadomości - metoda reply
      9. Wyczyszczenie obiektu - metoda clear
    2. Opis klasy PushConnection
      1. Konstruktor PushConnection
      2. Wysłanie wiadomości - metoda push
      3. Zmiana statusu/opisu bota - metoda setStatus
      4. Pobieranie obrazków wysyłanych do bota - metoda getImage
      5. Sprawdzanie czy numer GG jest botem - metoda isBot
    3. Możliwe zwroty HTTP dla żądań PUSH
  2. Opis protokołu BotAPI 2
    1. Autoryzacja
    2. Wiadomości przychodzące
    3. Pakiet z wiadomością protokołową
    4. Wysłanie wiadomości PUSH
    5. Tagi wspierane w wiadomości HTML
    6. Struktura z obrazkiem
    7. Obsługa obrazków
    8. Formatowanie wiadomości tekstowej
    9. Zmiana statusu/opisu bota
    10. Sprawdzenie czy numer GG jest botem

1. Opis biblioteki BotAPI 2

Biblioteka umożliwia autoryzację, tworzenie wiadomości, formatowanie, dołączanie i odbieranie obrazka, wysyłanie oraz odpowiadanie na wiadomości. W wersji PHP biblioteka wymaga zainstalowanego cURL.

Biblioteka składa się z dwóch klas:

  • MessageBuilder - służy do tworzenia wiadomości zgodnych z BotAPI
  • PushConnection - nawiązuje połączenie, przeprowadza autoryzację, wysyła wiadomości oraz zmienia status/opis

Należy wyróżnić dwa typy wiadomości:

  • PULL - wysyłane przez bota jako odpowiedź na wiadomość od użytkownika (metoda reply z klasy MessageBuilder),
  • PUSH - wysyłane przez właściciela bota do użytkownika bota (np. subskrypcje) (metoda push z klasy PushConnection).

W zakładce pobierz znajduje się najnowsza wersja biblioteki wraz z przykładami. Jest ona dostępna na licencji LGPL w wersji 3.

1.1. Opis klasy MessageBuilder

Klasa MessageBuilder pozwala na przygotowanie wiadomości, która zostanie wysłana użytkownikowi – zarówno w przypadku wiadomości PULL, jak i PUSH. Umożliwia ustawienie formatowania tekstu (pogrubienie, pochylenie, podkreślenie, kolor) oraz dodanie do wiadomości obrazka. Gwarantuje ona, że zarówno użytkownikom starszych wersji komunikatora, jak i nowych zostanie dostarczona poprawnie sformatowana wiadomość. Należy zaznaczyć, że nowe wersje komunikatora GG korzystają z podzbioru znaczników HTML do formatowania wiadomości.

Metody addText oraz addBBcode dbają o odpowiednie sformatowanie wiadomości końcowej wysyłanej użytkownikowi. Wraz z metodą addImage zapewniają użytkownikowi biblioteki wszystko, co potrzebne do przygotowania wiadomości. Osoba korzystająca z klasy MessageBuilder może jednak skorzystać z dodatkowych metod takich jak addRawHtml, setRawHtml oraz setAlternativeText, które zostaną opisane później.

We wszystkich metodach używających łańcuchów tekstowych musi być użyte kodowanie UTF-8.

Poniżej znajduje się bardzo prosty przykład użycia klasy MessageBuilder:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  
$M = new MessageBuilder();
  switch(
file_get_contents("php://input")){// zmienna ta zawiera wiadomość wysłaną przez użytkownika do bota
    
case "cześć"$M->addText('Cześć :) Twój numer GG to '.$_GET['from']); break;
    case 
"co słychać?"$M->addText('wszystko w porządku'); break;
    case 
"co robisz?"$M->addText('nudzę się...'); break;
    default: 
$M->addText('nie rozumiem, co masz na myśli');
  }
  
$M->reply();

Klasa MessageBuilder składa się z poniższych metod:

1.1.1. Konstruktor MessageBuilder

tworzy nowy obiekt tej klasy. Przykładowe użycie:

PHPPython
$M = new MessageBuilder();

1.1.2. Dodanie tekstu - metoda addText

umożliwia dodanie tekstu z opcjonalnym formatowaniem

PHPPython
addText(string $text[, string $formatBits=FORMAT_NONE[, int $R=0[, int $G=0[, int $B=0]]]])


Parametry:

  • text - tekst dodawany do wiadomości,
  • formatBits (opcjonalny) - formatowanie to suma bitowa flag FORMAT_BOLD_TEXT, FORMAT_ITALIC_TEXT, FORMAT_UNDERLINE_TEXT, FORMAT_NEW_LINE oznaczających odpowiednio pogrubienie, pochylenie, podkreślenie oraz przejście do nowej linii na końcu tekstu. Domyślnie ustawiana jest flaga FORMAT_NONE o wartości 0,
  • R, G, B (opcjonalne) - następnie mogą wystąpić trzy liczby o wartości od 0 do 255 oznaczające odpowiednio natężenie koloru czerwonego, zielonego i niebieskiego. Domyślnie przyjmują wartość 0 oznaczającą kolor czarny.

Metodę addText można wywoływać wielokrotnie. Kolejne treści będą dodawane do wiadomości obiektu klasy MessageBuilder.
Aby dodać przejście do nowej linii w tekście można użyć znaku \n.

Przykłady:

PHPPython
$M->addText('zwykły tekst'FORMAT_NONE);                                                 // zwykły tekst
$M->addText('tekst podkreślony i pochylony'FORMAT_UNDERLINE_TEXT|FORMAT_ITALIC_TEXT);   // tekst podkreślony i pochylony
$M->addText('Ala ma kota'FORMAT_BOLD_TEXT01280);                                  // Ala ma kota
$M->addText('czerwony tekst'FORMAT_NONE25500);                                    // czerwony tekst

1.1.3. Dodanie obrazków - metoda addImage

pozwala na dodanie obrazków do wiadomości

PHPPython
addImage(string $file[, bool $isFile=IMG_FILE])

Pierwszy parametr określa ścieżkę do pliku z obrazkiem bądź dane binarne obrazka. Jeśli jako pierwszy parametr podamy dane binarne obrazka, to drugi parametr musi przyjąć wartość IMG_RAW. W przypadku podania ścieżki do pliku z obrazkiem drugiego parametru można nie podawać i przyjmie automatycznie wartość IMG_FILE. Pliki z obrazkami mogą mieć rozrzerzenia BMP,GIF,JPG,PNG. Waga obrazka nie może przekroczyć 255 kilobajtów.

Wysłanie obrazka wymaga dokonania autoryzacji za pomocą klasy PushConnection opisanej w punkcie 1.2.1

Pzykłady:

PHPPython
<?php
require_once('MessageBuilder.php');
require_once(
'PushConnection.php');
PushConnection::$BOTAPI_LOGIN='wojtek@gg.pl';
PushConnection::$BOTAPI_PASSWORD='hasło';
$P = new PushConnection(123456);
$M = new MessageBuilder();
$M->addText("Obrazek JPG:");
$M->addImage('obrazek.jpg');
$M->reply();
PHPPython
$M->addImage($imgDataIMG_RAW);   // zakładamy, że $imgData zawiera dane binarne z obrazkiem

1.1.4. Ustawienie odbiorców wiadomości - metoda setRecipients

pozwala na ustawienie listy odbiorców wiadomości w przypadku wysyłania wiadomości do wielu odbiorców. Jeśli wiadomość ma być wysłana jako odpowiedź do osoby piszącej do bota (wiadomość PULL), nie trzeba ustawiać odbiorcy tą metodą.

PHPPython
setRecipients(int $gg_number)
PHPPython
setRecipients(array(int $gg_number))

Metoda ta umożliwia dodanie pojedynczego odbiorcy (pierwszy przypadek) lub tablicy odbiorców (drugi przypadek). Botmaster przyjmie do 1000 odbiorców w jednym żądaniu PUSH lub do 250 odbiorców w przypadku żądania PULL.

Przykłady:

PHPPython
$M->setRecipients(12345);
PHPPython
$M->setRecipients(array(12345234563456745678));

1.1.5. Dodanie kodu HTML do wiadomości - metoda addRawHtml

dodaje do wiadomości HTML podany przez użytkownika kod.

PHPPython
addRawHtml(string $html)

Należy zaznaczyć, że spowoduje to dodanie podanej treści wyłącznie do wiadomości wysyłanej do nowych wersji komunikatora GG. Wiadomość dla wersji starszych pozostanie niezmieniona. Należy także pamiętać, że nowe wersje komunikatora pozwalają na użycie tylko niektórych, podstawowych znaczników HTML, takich jak <b>, <i>, <u>, <s>, <br>, <sub>, <sup>, a także <span>, który może zawierać wyłącznie atrybut style, w którym można ustawić: color, background-color, font-family, font-size.

Poniższy przykład utworzy dla starszych wersji komunikatora GG wiadomość o treści „Jestem botem”. Dla nowych wersji komunikatora utworzy natomiast wiadomość o treści „Jestem botem na Gadu-Gadu”:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  
$M = new MessageBuilder();
  
$M->addText('Jestem botem ');
  
$M->addRawHtml('<u>na Gadu-Gadu</u>');
  
$M->reply();

Kolejny przykład:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  
$M = new MessageBuilder();
  
$M->addText('Jestem botem na ');
  
$M->addRawHtml('<span style="background-color:#ffaa00; color:#ff0000; font-family:\'Georgia\'; font-size:16pt; ">GG</span>');
  
$M->reply();

1.1.6. Zastąpienie wiadomości HTML - metoda setRawHtml

działa na podobnej zasadzie, co powyższa metoda, ale nadpisuje część HTMLową wiadomości, a nie dodaje do istniejącej treści.

PHPPython
setRawHtml(string $html)

Przykład:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  
$M = new MessageBuilder();
  
$M->addText('Wiadomość dla starszych wersji komunikatora GG');
  
$M->setRawHtml('Wiadomość dla nowszych wersji komunikatora GG');
  
$M->reply();

1.1.7. Zastąpienie wiadomości tekstowej - metoda setAlternativeText

umożliwia nadpisanie części tekstowej przeznaczonej dla starszych komunikatorów GG.

PHPPython
setAlternativeText(string $text)

Poniższy przykład utworzy dla starszych komunikatorów GG wiadomość o treści „Nie jestem botem”. Dla nowych wersji komunikatora utworzy wiadomość o treści „Jestem botem”:

PHPPython
<?php
  
require_once('MessageBuilder.php'); 
  
$M = new MessageBuilder(); 
  
$M->addText('Jestem botem'); 
  
$M->setAlternativeText('Nie jestem botem'); 
  
$M->reply(); 

1.1.8. Wysłanie wiadomości - metoda reply

Jeśli zamierzamy wysłać wiadomość przy pomocy PULL, wystarczy skorzystać z metody reply. Przykład:

PHPPython
$M->reply();

Można również skorzystać z metody push dostępnej w klasie PushConnection opisanej poniżej. Przykład:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  require_once(
'PushConnection.php');
  
$M = new MessageBuilder();
  
$P = new PushConnection(123456'wojtek@gg.pl''hasło');
  
$M->addText('Twoja wiadomość to: '.file_get_contents("php://input"));
  
$M->setRecipients(array($_GET['from']));
  
$P->push($M);

1.1.9. Wyczyszczenie obiektu - metoda clear

Czyści wszystkie pola tego obiektu, aby można go było użyć ponownie. Użycie:

PHPPython
$M->clear();

Przykład:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  require_once(
'PushConnection.php');
  
$M = new MessageBuilder();
  
$P = new PushConnection(123456'wojtek@gg.pl''hasło');
  
$M->addText('Przesyłam Twoją wiadomość do numeru 321321');
  
$M->reply();
  
$M->clear();
  
$M->addText('Wiadomość od użytkownika: '.$_GET['from'].' o treści: '.file_get_contents("php://input"));
  
$M->setRecipients(array(321321));
  
$P->push($M);

Metoda może być przykładowo przydatna w przypadku, gdy piszemy bota będącego czatem i chcemy, żeby na wiadomość wysłaną przez użytkownika bot wysłał inną odpowiedź do tego użytkownika, a inną do pozostałych uczestników czatu. Wtedy można jedną wiadomość wysłać jako wiadomość PULL, a drugą jako wiadomość PUSH.

1.2. Opis klasy PushConnection

Klasa PushConnection umożliwia dokonanie autoryzacji oraz wysłanie na żądanie właściciela bota wiadomości do użytkownika bądź listy użytkowników bota, a także zmianę statusu/opisu bota.
UWAGA! Aby bot mógł wysłać wiadomość do użytkownika, to użytkownik musi nawiązać kontakt i przynajmniej jeden raz napisać do bota.

Poniżej znajduje się bardzo prosty przykład użycia klasy PushConnection oraz MessageBuilder do wysłania wiadomości do kilku użytkowników bota:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  require_once(
'PushConnection.php');
  
$M = new MessageBuilder();
  
$M->addText('Witajcie :)');
  
$M->setRecipients(array(123234345456));   // lista odbiorców
  
$P = new PushConnection(123456'wojtek@gg.pl''hasło');   // autoryzacja
  
$P->push($M);   // wysłanie wiadomości do odbiorców

Klasa PushConnection składa się z poniższych metod:

1.2.1. Konstruktor PushConnection

dostaje jako argumenty numer GG bota oraz login i hasło do BotAPI uzyskane po poprawnej rejestracji bota. Przykład:

PHPPython
<?php
PushConnection::$BOTAPI_LOGIN='wojtek@gg.pl';
PushConnection::$BOTAPI_PASSWORD='hasło';
$P = new PushConnection(123456);
lub
PHPPython
$P = new PushConnection(123456'wojtek@gg.pl''hasło');

1.2.2 Wysłanie wiadomości - metoda push

metoda wysyłająca wiadomość zdefiniowaną w obiekcie klasy MessageBuilder. Przykładowe użycie:

PHPPython
$P->push($M);   // $M jest obiektem klasy MessageBuilder

Metoda ta umożliwia wysłanie kilku wiadomości klasy MessageBuilder przy pomocy jednego żądania. Jako argument metody push należy w takim wypadku podać tablicę obiektów klasy MessageBuilder:

PHPPython
<?php
  
require_once('MessageBuilder.php');
  
require_once('PushConnection.php');
  
$M = array(new MessageBuilder(), new MessageBuilder());
  
$M[0]->addText("cześć :)")->setRecipients(array(1001,1002));
  
$M[1]->addText("witaj :)")->setRecipients(array(1003,1004));
  
$P = new PushConnection(123456'wojtek@gg.pl''hasło');
  
$P->push($M);

1.2.3. Zmiana statusu/opisu bota - metoda setStatus

umożliwia zmianę statusu oraz opisu bota.

PHPPython
setStatus(string $opis[, string $status])

Metoda, jako parametry przyjmuje:

  • tekstowy opis w kodowaniu UTF-8, który może mieć do 255 znaków (starsze wersje komunikatora pokażą jednak tylko pierwszych 75 znaków opisu),
  • opcjonalnie jeden z poniższych statusów (jeśli go nie podamy, zostanie zachowany aktualny status):
Status Znaczenie
STATUS_FFC Chętny do rozmowy
STATUS_BACK Dostępny
STATUS_AWAY Zaraz wracam
STATUS_DND Nie przeszkadzać
STATUS_INVISIBLE Niewidoczny

Przykłady:

PHPPython
$P->setStatus('opis tekstowy'PushConnection::STATUS_FFC);   // status "chętny do rozmowy" z opisem "opis tekstowy"
$P->setStatus('nowszy opis');                 // aktualny status z opisem "nowszy opis"

1.2.4. Pobranie obrazków wysyłanych do bota - metoda getImage

umożliwia pobranie obrazka przesłanego w wiadomości od użytkownika do bota.

PHPPython
getImage(string $identyfikator)
Botmaster pozwala na przesłanie do pięciu obrazków w jednej wiadomości do bota. Jeżeli w wiadomości przychodzącej do bota znajdzie się obrazek to Botmaster wywoła skrypt przypisany do bota za pomocą żądania POST z dodatkowym parametrem images, w którym znajdą się oddzielone przecinkiem identyfikatory obrazków. Identyfikator obrazka skłąda się z 16 znaków. Przykładowe żądanie z dwoma obrazkami:

POST http://www.twojadomena.pl/bot.php?from=1234567&to=7654321&images=34df156000000141,ea34c2220000249d
Przykładowe użycie:
PHPPython
<?php
require_once('MessageBuilder.php');
require_once(
'PushConnection.php');
PushConnection::$BOTAPI_LOGIN='wojtek@gg.pl';
PushConnection::$BOTAPI_PASSWORD='hasło';
$P = new PushConnection(123456);
$M = new MessageBuilder();
$identyfikator $_GET['images'];
$obrazek $P->getImage($identyfikator);
$M->addText("Odebrałem obrazek:\n");
$M->addImage($obrazekIMG_RAW);
$M->addText("\no identyfikatorze: ".$identyfikator);
$M->reply();

1.2.5. Sprawdzanie czy numer GG jest botem - metoda isBot

umożliwia sprawdzenie czy numer GG jest botem zarejestrowanym na platformie BotAPI GG.

PHPPython
isBot(int $gg_number)

Przykład:

PHPPython
$P->isBot(12345);

Zwrotem może być TRUE albo FALSE.

1.3. Możliwe zwroty HTTP dla żądań PUSH

W bibiotece BotAPI w wersji PHP zwroty będą widoczne po zmianie stałej CURL_VERBOSE na początku pliku PushConnection.php z false na true.

Komunikat w przypadku powodzenia:

Kod HTTP XML z opisem i statusem BotAPI
200 OK <?xml version="1.0"?><result><status>0</status></result>

Możliwe komunikaty błędów w przypadku niepowodzenia:

Kod HTTP XML z opisem i statusem BotAPI
400 Bad Request <?xml version="1.0"?><result><errorMsg>Nieprawidłowy numer bota.</errorMsg><status>1</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Bot niezarejestrowany lub nieaktywny na tej maszynie.</errorMsg><status>2</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Brak wiadomości do wysłania.</errorMsg><status>3</status></result>
401 Unauthorized <?xml version="1.0"?><result><errorMsg>Błędny lub nieważny token.</errorMsg><status>4</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Liczba odbiorców wiadomości nie może być większa od 1000</errorMsg><status>5</status>/result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Brak poprawnych numerów odbiorców na liście.</errorMsg><status>6</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Długość opisu nie może przekraczać 255 bajtów.</errorMsg><status>7</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Wartość statusu musi być prawidłową liczbą</errorMsg><status>8</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Niepoprawny zasób. Dostępne zasoby: setStatus, sendMessage</errorMsg><status>9</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Za mało parametrów żądania, musi zawierać przynajmniej to oraz msg</errorMsg><status>10</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Za mało parametrów żądania, musi zawierać: status oraz opcjonalnie desc</errorMsg><status>11</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Niepoprawne żądanie. Upewnij się, że parametry żądania są w kodowaniu procentowym (Content-Type: application/x-www-form-urlencoded)</errorMsg><status>12</status></result>
503 Service Unavailable <?xml version="1.0"?><result><errorMsg>Nie udało się wysłać wiadomości.</errorMsg><status>13</status></result>
503 Service Unavailable <?xml version="1.0"?><result><errorMsg>Nie udało się ustawić statusu.</errorMsg><status>14</status></result>
411 Length Required <?xml version="1.0"?><result><errorMsg>Nieprawidłowy nagłówek Content-Length.</errorMsg><status>15</status></result>
413 Request Entity Too Large <?xml version="1.0"?><result><errorMsg>Długość żądania przekracza dopuszczalny rozmiar.</errorMsg><status>16</status></result>
413 Request Entity Too Large <?xml version="1.0"?><result><errorMsg>Długość nagłówka przekracza dopuszczalny rozmiar.</errorMsg><status>17</status></result>
404 Not Found <?xml version="1.0"?><result><errorMsg>Nie znalazłem obrazka ani w wiadomości protokołowej, ani w pamięci podręcznej</errorMsg><status>18</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Długość wiadomości HTML jest niezgodna z informacją z nagłówka.</errorMsg><status>19</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Długość wiadomości tekstowej jest niezgodna z informacją z nagłówka.</errorMsg><status>20</status></result>
400 Bad Request <?xml version="1.0"?><result><errorMsg>Któreś z pól struktury (tekst, html, formatowanie lub obrazek) przekraczają dopuszczalną długość.</errorMsg><status>21</status></result>

2. Opis protokołu BotAPI 2

Protokół BotAPI 2 zmienił się w stosunku do poprzedniej wersji. Poniższy opis protokołu może się przydać osobom, które chciałyby stworzyć własną bibliotekę zgodną z BotAPI 2, inną niż ogólnie dostępna biblioteka PHP.

Uwaga! Jeśli chcesz szybko stworzyć własnego bota w języku PHP lub Python, skorzystaj z gotowej biblioteki opisanej we wcześniejszych punktach.

2.1. Autoryzacja

Operacje PUSH wymagają adresu serwera Botmastera wraz z portem, który obsługuje bota oraz aktywnego tokena. Przed każdą operacją wysłania wiadomości do użytkowników przez bota, konieczne jest pobranie aktywnego tokena. Autoryzacja nie jest wymagana do obsługi wiadomości typu PULL.

Aby otrzymać token wymagane są następujące dane:

  • login do BotAPI (otrzymany w trakcie rejestracji bota),
  • hasło do BotAPI (otrzymane w trakcie rejestracji bota),
  • numer GG bota.

Jako odpowiedź żądania autoryzacji uzyskamy XML z poniższymi danymi:

  • token (16 znaków z zakresu: 0-9, a-z, A-Z),
  • adres serwera obsługującego bota,
  • port, na którym serwer nasłuchuje.

Pobranie tokena

Token uzyskujemy wysyłając żądanie GET wraz z nagłówkiem pod adres:

https://botapi.gadu-gadu.pl/botmaster/getToken/123456

gdzie w miejscu 123456 podajemy numer GG bota, dla którego pragniemy uzyskać token. Wymagana jest standardowa autoryzacja HTTP.

Jako odpowiedź uzyskamy XML w postaci:

<botmaster
  <
token>3Z9bPc19axXf7B1R</token
  <
server>botapi-2-1.gadu-gadu.pl</server
  <
port>80</port
</
botmaster>

Przykład

Autoryzacja użytkownika o nazwie „login” i haśle „haslo” dla bota o numerze GG 123456 (w przykładzie zostało użyte polecenie curl dostępne w systemach uniksowych):

curl --"" --basic --user login:haslo https://botapi.gadu-gadu.pl/botmaster/getToken/123456

Wysłane:

GET /botmaster/getToken/123456 HTTP/1.1 
Authorization: Basic bG9naW46aGFzbG8= 
Host: botapi.gadu-gadu.pl
Accept: */* 

Otrzymane:

HTTP/1.1 200 OK 
Transfer-Encoding: chunked 
Content-Type: text/xml 
Date: Mon, 03 Jan 2011 10:30:17 GMT
Server: lighttpd

<?xml version="1.0" encoding="UTF-8"?> 
<botmaster>
<token>3Z9bPc19axXf7B1R</token>
<server>botapi-2-1.gadu-gadu.pl</server>
<port>80</port>
</botmaster> 

Nieudana autoryzacja zwróci:

HTTP/1.1 401 Unauthorized
Transfer-Encoding: chunked 
Content-type: text/html 
Date: Mon, 03 Jan 2011 10:31:36 GMT
Server: lighttpd

<?xml version="1.0" encoding="UTF-8"?>
<botmaster>
<errorMsg>Błąd autoryzacji</errorMsg>
</botmaster>

2.2. Wiadomości przychodzące

Gdy użytkownik napisze do bota, Botmaster wywołuje skrypt przypisany do bota za pomocą żądania POST. Np:

POST http://www.twojadomena.pl/bot.php?from=1234567&to=7654321

W URL przekazywane są parametry:

Parametr Opis Możliwe wartości
from Numer GG autora wiadomości [0-9]{1,9}
to Numer GG bota otrzymującego wiadomość [0-9]{1,9}

W POST Body przekazywana jest treść wiadomości kodowana w UTF-8 (jest to zmiana w stosunku do BotAPI 1.0, gdzie używano kodowania CP-1250).

Treść wiadomości można odczytać w PHP np. za pomocą zmiennej $HTTP_RAW_POST_DATA lub file_get_contents("php://input")

Generowanie odpowiedzi

Odpowiedź do użytkownika przekazywana jest jako wynik działania skryptu. W porównaniu z BotAPI 1.0 zrezygnowano z protokołu średnikowego. Obecnie osoba pisząca skrypt do obsługi bota ma dwie możliwości:

  • jeśli osoba pisząca wiadomość do bota ma dostać w odpowiedzi zwykły tekst bez formatowania, to wystarczy, że skrypt będzie zwracał czysty tekst w kodowaniu UTF-8. Zostanie on poprawnie dostarczony zarówno do nowych, jak i starszych komunikatorów GG korzystających z kodowania CP-1250 (np. GG 7.x). W tym przypadku nie jest konieczne korzystanie z wiadomości protokołowych BotAPI 2,
  • jeśli osoba pisząca wiadomość do bota ma dostać w odpowiedzi wiadomość z formatowaniem i/lub obrazkiem, należy skorzystać z funkcji udostępnianych przez bibliotekę BotAPI 2. W opisie znajduje się również wiele przykładów użycia biblioteki.

2.3. Pakiet z wiadomością protokołową

Dane w protokole BotAPI przesyłane są binarnie: na początku zawsze musi wystąpić struktura, która określi, jakie będą długości poszczególnych danych:

  • 4 bajty (unsigned int) na długość wiadomości zawierającej HTML (dla GG 8.x i nowszych; należy doliczyć końcowy znak \0),
  • 4 bajty (unsigned int) na długość wiadomości zawierającej wiadomość tekstową (dla starszych klientów; należy doliczyć końcowy znak \0),
  • 4 bajty (unsigned int) na długość danych z zawartością struktury z obrazkiem (może być równe 0, obrazek jest przesyłany opcjonalnie),
  • 4 bajty (unsigned int) na długość formatowania dla wiadomości tekstowej (może być równe 0, formatowanie tekstu jest opcjonalne).

Za nagłówkiem powinny kolejno wystąpić:

  • (wymagana) treść wiadomości HTML o długości określonej w powyższej strukturze (zakończona zerem),
  • (wymagana) treść wiadomości tekstowej o długości określonej w powyższej strukturze (również zakończona zerem),
  • (opcjonalnie) struktura z obrazkiem opisana niżej (nie zakończona zerem),
  • (opcjonalnie) formatowanie wiadomości tekstowej (nie zakończone zerem).

Tak przygotowany pakiet powinien być zwracany przez skrypt bota dla wiadomości PULL.

Jeśli wiadomość PULL ma zostać wysłana do wielu odbiorców, należy dodać w nagłówku HTTP pole 'To' z listą numerów GG odbiorców oddzielonych przecinkami. Można również dodać opcjonalne pole 'Send-to-offline' z wartością 0 lub false, jeśli nie chcemy, by wiadomość trafiła do osób w danej chwili niedostępnych.

2.4. Wysłanie wiadomości PUSH

W przypadku wiadomości PUSH pakiet powinien być wysyłany jako parametr 'msg' żądania POST HTTP, w parametrze 'to' powinna się znaleźć lista numerów GG odbiorców wiadomości rozdzielonych przecinkami. Wymagany jest również nagłówek 'Token' z tokenem uzyskanym podczas autoryzacji. Parametr 'Content-type' nagłówka HTTP oraz treść danych POST musi być w postaci application/x-www-form-urlencoded, a więc zakodowana kodowaniem procentowym. Podobnie jak przy wiadomościach PULL, można ustawić opcjonalny nagłówek 'Send-to-offline'. Tak przygotowane żądanie należy wysłać na adres botapi zwrócony przy okazji autoryzacji na zasób sendMessage.

UWAGA! Aby bot mógł wysłać wiadomość do użytkownika, to użytkownik musi nawiązać kontakt i przynajmniej jeden raz napisać do bota.

Istnieje również możliwość wysłania wielu różnych wiadomości do różnych grup odbiorców w jednym żądaniu PUSH. Można to uczynić wysyłając w żadaniu pary parametrów typu 'to1' - 'msg1', 'to2' - 'msg2' itd.

Przykładowe żądanie wysłania wiadomości "cześć :)" z bota o numerze GG 123456 przy użyciu narzędzia curl:

curl --"" https://botapi-2-7.gadu-gadu.pl/sendMessage/123456 -"Content-Type: application/x-www-form-urlencoded"
-"Token: 3Z9bPc19axXf7B1R" -"msg=cze%C5%9B%C4%87%20%3A)" -"to=1000,1001,1002,1003" 

Przykładowe żądanie wysłania wiadomości "cześć :)" do numerów 1001 i 1002 oraz wiadomości "witam :)" do numerów 1003 i 1004:

curl --"" https://botapi-2-7.gadu-gadu.pl/sendMessage/123456 -"Content-Type: application/x-www-form-urlencoded"
-"Token: 3Z9bPc19axXf7B1R" -"msg1=cze%C5%9B%C4%87%20%3A)" -"to1=1001,1002" -"msg2=witam20%3A)" -"to2=1001,1002" 

Możliwe kody błędów HTTP przy korzystaniu z wiadomości PUSH oraz ustawianiu statusu bota zostały opisane w punkcie 1.3.

2.5. Tagi wspierane w wiadomości HTML

  • <span> może zawierać wyłącznie atrybut style, w którym można ustawić: color, background-color, font-family, font-size
  • <b> oraz </b> - pogrubienie
  • <i> oraz </i> - pochylenie
  • <u> oraz </u> - podkreślenie
  • <s> oraz </s> - przekreślenie
  • <br> - przejście do nowej linii
  • <sub> - indeks dolny
  • <sup> - indeks górny
  • <img> - powinien zawierać atrybut name z identyfikatorem obrazka opisanym niżej; dodatkowo może zawierać atrybuty: style, width oraz height
  • atrybut name składa się z 16 znaków - pierwszych 8 znaków to suma kontrolna CRC32 zapisana szesnastkowo, kolejnych 8 znaków to wielkość obrazka w bajtach zapisana szesnastkowo

2.6. Struktura z obrazkiem

  • 8 bajtów - zapisana szesnastkowo suma kontrolna CRC32,
  • 8 bajtów - zapisana szesnastkowo wielkość obrazka w bajtach,
  • resztę danych stanowi sam obrazek (do 262144 bajtów, choć trzeba pamiętać o tym, że użytkownik może w komunikatorze ograniczyć tę wielkość i nie przyjąć obrazka) – w przypadku wiadomości wysyłanej przy pomocy PUSH ta część struktury może wystąpić opcjonalnie. Jeśli będziemy wysyłać wiele tych samych żądań PUSH paczkami po maksymalnie 1 tysiąc odbiorców, Botmaster za pierwszym razem zapisze obrazek i będzie mógł z niego skorzystać przy następnym żądaniu pozbawionym danych obrazka (ale z 16 bajtami z CRC32 i wielkością). Jeśli Botmaster nie znajdzie obrazka w pamięci, zwróci błąd HTTP „404 Not Found" wraz z poniższą treścią (w takim przypadku należy powtórzyć żądanie wysyłając je tym razem wraz z treścią obrazka).
<?xml version="1.0"?>
  <result>
    <errorMsg>Nie znalazłem obrazka ani w wiadomości protokołowej, ani w pamięci podręcznej</errorMsg>
    <status>18</status>
  </result>	

2.7. Obsługa obrazków

Obsługa obrazków w Botmasterze jest zapewniona poprzez trzy zasoby pozwalające na: zapisanie obrazka, sprawdzenie czy obrazek istnieje oraz pobranie obrazka.

Zapisanie obrazka odbywa się przy pomocy zasobu putImage. Jako odpowiedź otrzymamy XML z hashem czyli identyfikatorem obrazka. Przykładowe żądnie zapisujące obrazek default.jpg o wielkości 1624 bajty w Botmasterze:
curl --"" --request POST --data-binary "@default.jpg" https://botapi.gadu-gadu.pl/botmaster/putImage/123456 
-"Token: 3Z9bPc19axXf7B1R" -"Expect: " 

Wysłane:

POST /botmaster/putImage/123456 HTTP/1.1
Host: botapi.gadu-gadu.pl
Accept: */*
Token: 3Z9bPc19axXf7B1R
Content-Length: 1624
Content-Type: application/x-www-form-urlencoded

Otrzymane:

HTTP/1.1 200 OK
Date: Thu, 19 Jul 2012 13:25:04 GMT
Server: nginx/1.0.11
Content-Type: text/xml
Transfer-Encoding: chunked

<?xml version="1.0" encoding="UTF-8"?>
<result>
<status>0</status>
<hash>be19636700000658</hash>
</result>

Sprawdzenie czy obrazek istnieje już w Botmasterze odbywa się przy pomocy zasobu existsImage. Przykładowe żądnie sprawdzające czy istnieje obrazek o identyfikatorze be19636700000658 zapisany w poprzednim przykładzie:

curl --"" https://botapi.gadu-gadu.pl/botmaster/existsImage/123456 -"Token: 3Z9bPc19axXf7B1R" -"hash=be19636700000658"

Wysłane:

POST /botmaster/existsImage/123456 HTTP/1.1
Host: botapi.gadu-gadu.pl
Accept: */*
Token: 3Z9bPc19axXf7B1R
Content-Length: 21
Content-Type: application/x-www-form-urlencoded

hash=5ecc307800005cd0

Otrzymane:

HTTP/1.1 200 OK
Date: Thu, 19 Jul 2012 14:39:58 GMT
Server: nginx/1.0.11
Content-Type: text/xml
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8"?>
<result>
<status>0</status>
</result>
Jeżeli obrazek istnieje status będzie równy 0.

Botmaster pozwala na przesyłanie obrazków do bota co zostało opisane szerzej w punkcie 1.2.4. Obrazek można pobrać z Botmastera za pomocą zasobu getImage. Przykładowe żądanie pobierające obrazek o identyfikatorze be19636700000658 i zapisujące go do pliku default.jpg:

curl -default.jpg --"" https://botapi.gadu-gadu.pl/botmaster/getImage/123456 -"Token: 3Z9bPc19axXf7B1" 
-"hash=be19636700000658"

2.8. Formatowanie wiadomości tekstowej

Jest używane przez starsze wersje komunikatora GG (np.: 7.x). Liczby są zapisywane zgodnie ze standardem Little Endian (odwrócona kolejność bajtów).

Na samym początku musi wystąpić bajt 0x02 oznaczający, że za nim nastąpi formatowanie tekstu. Tuż po nim na dwóch bajtach przekazana jest długość (w bajtach) dalszej części z właściwym formatowaniem. Przykładowo, jeśli długość dalszej części będzie równa 10, to należy wysłać dwa bajty: 0x0a i 0x00. Następnie występują po sobie struktury oznaczające zmianę formatowania. Każda taka struktura składa się z:

  • pozycji w tekście (2 bajty),
  • atrybut formatowania (jeden bajt),
  • kolor czcionki (opcjonalnie),
  • struktura obrazka (opcjonalnie, opisana poniżej).

Atrybut formatowania może być sumą następujących wartości: 0x01 (pogrubienie), 0x02 (pochylenie), 0x04 (podkreślenie), 0x08 (kolorowy tekst), 0x80 (obrazek).

Struktura obrazka składa się z:

  • dwóch stałych bajtów: 0x09 i 0x01,
  • 4 bajtów z zapisanym rozmiarem obrazka (Little Endian),
  • 4 bajtów z zapisaną sumą kontrolną CRC32 obrazka (Little Endian).

Kolor czcionki to trzy następujące po sobie bajty oznaczające natężenie poszczególnych składowych RGB (w tej kolejności), np. 0xff, 0x00, 0x00 oznacza kolor czerwony.

2.9. Zmiana statusu/opisu bota

Aby zmienić status i/lub opis bota, należy wykonać żądanie na adres BotAPI zwrócony przy okazji autoryzacji na zasób setStatus. Przykładowe żądanie ustawiające status "Zaraz wracam" z opisem "Zażółć gęślą jaźń":

curl --"" https://botapi-2-7.gadu-gadu.pl/setStatus/123456  -"Token: 3Z9bPc19axXf7B1R" -"status=5" 
-"desc=Za%C5%BC%C3%B3%C5%82%C4%87%20g%C4%99%C5%9Bl%C4%85%20ja%C5%BA%C5%84"

123456 to przykładowy numer bota, token ma wartość zwróconą przy autoryzacji, status to wartość liczbowa zgodna z poniższą tabelką. Parametr desc powinien zawierać opis o długości do 255 znaków w kodowaniu UTF-8 i zakodowany w kodowaniu procentowym.

Status liczbowy Znaczenie
0 Obecny status (brak zmiany)
2 Dostępny
3 Zaraz wracam
4 Dostępny z opisem
5 Zaraz wracam z opisem
20 Niewidoczny
22 Niewidoczny z opisem
23 PoGGadaj ze mną
24 PoGGadaj ze mną z opisem
32 Reklamowy
33 Nie przeszkadzać
34 Nie przeszkadzać z opisem

2.10. Sprawdzenie czy numer GG jest botem

Aby sprawdzić czy numer GG jest botem zarejestrowanym na platformie BotAPI GG konieczne jest pobranie aktywnego tokena a następnie wykonanie następującego zapytania:

curl --"" -"Token: 3Z9bPc19axXf7B1R" https://botapi.gadu-gadu.pl/botmaster/isBot/123456 -"check_ggid=100"

123456 to numer naszego bota do którego posiadamy login i hasło BotAPI. Natomiast 100 to numer GG, który chcemy sprawdzić czy jest botem zarejestrowanym na platformie BotAPI GG.

Otrzymanie:

<?xml version="1.0" encoding="UTF-8"?> 
<result><status>0</status></result> 

oznacza, że sprawdzany numer GG nie jest botem zarejestrowanym na platformie BotAPI GG.

Otrzymanie:

<?xml version="1.0" encoding="UTF-8"?> 
<result><status>1</status></result> 

oznacza, że sprawdzany numer GG jest botem zarejestrowanym na platformie BotAPI GG.


Regulamin BotAPI GG | Regulamin Komunikatora | Forum
© 2016 Xevin Consulting Limited