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
-
Opis biblioteki BotAPI 2
-
Opis klasy MessageBuilder
- Konstruktor MessageBuilder
- Dodanie tekstu - metoda addText
- Dodanie obrazka - metoda addImage
- Ustawienie odbiorców wiadomości - metoda setRecipients
- Dodanie kodu HTML do wiadomości - metoda addRawHtml
- Zastąpienie wiadomości HTML - metoda setRawHtml
- Zastąpienie wiadomości tekstowej - metoda setAlternativeText
- Wysłanie wiadomości - metoda reply
- Wyczyszczenie obiektu - metoda clear
- Opis klasy PushConnection
- Możliwe zwroty HTTP dla żądań PUSH
-
Opis klasy MessageBuilder
- Opis protokołu BotAPI 2
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 także 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.
Metoda addText dba 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:
<?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
1.1.2. Dodanie tekstu - metoda addText
umożliwia dodanie tekstu
Parametry:
- text - tekst dodawany do wiadomości,
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.
1.1.3. Dodanie obrazków - metoda addImage
pozwala na dodanie obrazków do wiadomości
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:
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ą.
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:
1.1.5. Dodanie kodu HTML do wiadomości - metoda addRawHtml
dodaje do wiadomości HTML podany przez użytkownika kod.
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”:
<?php
require_once('MessageBuilder.php');
$M = new MessageBuilder();
$M->addText('Jestem botem ');
$M->addRawHtml('<u>na Gadu-Gadu</u>');
$M->reply();
Kolejny przykład:
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.
Przykład:
1.1.7. Zastąpienie wiadomości tekstowej - metoda setAlternativeText
umożliwia nadpisanie części tekstowej przeznaczonej dla starszych komunikatorów GG.
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”:
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:
Można również skorzystać z metody push dostępnej w klasie PushConnection opisanej poniżej. Przykład:
1.1.9. Wyczyszczenie obiektu - metoda clear
Czyści wszystkie pola tego obiektu, aby można go było użyć ponownie. Użycie:
Przykład:
<?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:
<?php
require_once('MessageBuilder.php');
require_once('PushConnection.php');
$M = new MessageBuilder();
$M->addText('Witajcie :)');
$M->setRecipients(array(123, 234, 345, 456)); // 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:
lub1.2.2 Wysłanie wiadomości - metoda push
metoda wysyłająca wiadomość zdefiniowaną w obiekcie klasy MessageBuilder. Przykładowe użycie:
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:
<?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.
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:
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.
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,ea34c2220000249dPrzykładowe użycie:
<?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($obrazek, IMG_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.
Przykład:
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 -v -A "" --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ą 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.
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.
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 -v -A "" https://botapi-2-7.gadu-gadu.pl/sendMessage/123456 -H "Content-Type: application/x-www-form-urlencoded"
-H "Token: 3Z9bPc19axXf7B1R" -d "msg=cze%C5%9B%C4%87%20%3A)" -d "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 -v -A "" https://botapi-2-7.gadu-gadu.pl/sendMessage/123456 -H "Content-Type: application/x-www-form-urlencoded"
-H "Token: 3Z9bPc19axXf7B1R" -d "msg1=cze%C5%9B%C4%87%20%3A)" -d "to1=1001,1002" -d "msg2=witam20%3A)" -d "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 -v -A "" --request POST --data-binary "@default.jpg" https://botapi.gadu-gadu.pl/botmaster/putImage/123456
-H "Token: 3Z9bPc19axXf7B1R" -H "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 -v -A "" https://botapi.gadu-gadu.pl/botmaster/existsImage/123456 -H "Token: 3Z9bPc19axXf7B1R" -d "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 -o default.jpg -v -A "" https://botapi.gadu-gadu.pl/botmaster/getImage/123456 -H "Token: 3Z9bPc19axXf7B1"
-d "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 -v -A "" https://botapi-2-7.gadu-gadu.pl/setStatus/123456 -H "Token: 3Z9bPc19axXf7B1R" -d "status=5"
-d "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 -v -A "" -H "Token: 3Z9bPc19axXf7B1R" https://botapi.gadu-gadu.pl/botmaster/isBot/123456 -d "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.