Python PHP

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.

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 Python

<?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();

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import cgi
from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        msg = cgi.escape(self.request.body) # ta zmienna zawiera wiadomość wysłaną przez użytkownika do bota
        if msg == 'cześć': M.addText('Cześć :) Twój numer GG to %s\n' % (int(self.request.get('from'))))
        elif msg == 'co słychać?': M.addText('wszystko w porządku')
        elif msg == 'co robisz?': M.addText('nudzę się...')
        else: M.addText('nie rozumiem, co masz na myśli')
        self.response.out.write(M.reply(self))

application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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

1.1.1. Konstruktor MessageBuilder

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

PHP Python

$M = new MessageBuilder();

M = MessageBuilder()

1.1.2. Dodanie tekstu - metoda addText

umożliwia dodanie tekstu

PHP Python

addText(string $text)

addText(string text)

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

PHP Python

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

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:

PHP Python

<?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();

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        PushConnection.BOTAPI_LOGIN = 'wojtek@gg.pl'
        PushConnection.BOTAPI_PASSWORD = 'hasło'
        P = PushConnection(123456)
        M = MessageBuilder()
        M.addText('Obrazek JPG:')
        M.addImage('obrazek.jpg')
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

PHP Python

$M->addImage($imgData, IMG_RAW);   // zakładamy, że $imgData zawiera dane binarne z obrazkiem

M.addImage(imgData, IMG_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ą.

PHP Python

setRecipients(int $gg_number)

setRecipients(int gg_number)

PHP Python

setRecipients(array(int $gg_number))

setRecipients(list[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:

PHP Python

$M->setRecipients(12345);

M.setRecipients(12345)

PHP Python

$M->setRecipients(array(12345, 23456, 34567, 45678));

M.setRecipients([12345, 23456, 34567, 45678])

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

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

PHP Python

addRawHtml(string $html)

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 , , , <s>, , , , a także , 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 Python

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

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        M.addText('Jestem botem ')
        M.addRawHtml('<u>na Gadu-Gadu</u>')
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

Kolejny przykład:

PHP Python

<?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();

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        M.addText('Jestem botem na ')
        M.addRawHtml('<span style="background-color:#ffaa00; color:#ff0000; font-family:\'Georgia\'; font-size:16pt; ">GG</span>')
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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.

PHP Python

setRawHtml(string $html)

setRawHtml(string html)

Przykład:

PHP Python

<?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();

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        M.addText('Wiadomość dla starszych wersji komunikatora GG')
        M.setRawHtml('Wiadomość dla nowszych wersji komunikatora GG')
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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

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

PHP Python

setAlternativeText(string $text)

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”:

PHP Python

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

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        M.addText('Jestem botem')
        M.setAlternativeText('Nie jestem botem')
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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:

PHP Python

$M->reply();

M.reply(self)

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

PHP Python

<?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);

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import cgi
from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        P = PushConnection(123456, 'wojtek@gg.pl', 'hasło')
        M.addText('Twoja wiadomość to: %s' % (cgi.escape(self.request.body)))
        M.setRecipients([int(self.request.get('from'))])
        P.push(M)
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

1.1.9. Wyczyszczenie obiektu - metoda clear

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

PHP Python

$M->clear();

M.clear()

Przykład:

PHP Python

<?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);

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import cgi
from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        P = PushConnection(123456, 'wojtek@gg.pl', 'hasło')
        M.addText('Przesyłam Twoją wiadomość do numeru 321321')
        self.response.out.write(M.reply(self))
        M.clear()
        M.addText('Wiadomość od użytkownika: %s o treści: %s' % (int(self.request.get('from')), cgi.escape(self.request.body)))
        M.setRecipients([321321])
        P.push(M)
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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 Python

<?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

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = MessageBuilder()
        M.addText('Witajcie :)')
        M.setRecipients([123,234,345,456])   # lista odbiorców
        P = PushConnection(123456, 'wojtek@gg.pl', 'hasło')   # autoryzacja
        P.push(M)   # wysłanie wiadomości do odbiorców
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

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:

PHP Python

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

PushConnection.BOTAPI_LOGIN = 'wojtek@gg.pl'
PushConnection.BOTAPI_PASSWORD = 'hasło'
P = PushConnection(123456)

lub

PHP Python

$P = new PushConnection(123456, 'wojtek@gg.pl', 'hasło');

P = 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:

PHP Python

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

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:

PHP Python

<?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);

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import cgi
from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        M = [MessageBuilder(),MessageBuilder()]
        M[0].addText('Cześć :)').setRecipients([1001, 1002])
        M[1].addText('Witaj :)').setRecipients([1003, 1004])
        P = PushConnection(123456, 'wojtek@gg.pl', 'hasło')
        P.push(M)

application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

1.2.3. Zmiana statusu/opisu bota - metoda setStatus

umożliwia zmianę statusu oraz opisu bota.

PHP Python

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

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:

PHP Python

$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"

P.setStatus('opis tekstowy', 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.

PHP Python

getImage(string $identyfikator)

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:

PHP Python

<?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();

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from google.appengine.ext import webapp
from google.appengine.ext.webapp.util import run_wsgi_app
from MessageBuilder import *
from PushConnection import *

class MainHandler(webapp.RequestHandler):
    def post(self):
        PushConnection.BOTAPI_LOGIN = 'wojtek@gg.pl'
        PushConnection.BOTAPI_PASSWORD = 'hasło'
        P = PushConnection(123456)
        M = MessageBuilder()
        identyfikator = self.request.get('images')
        obrazek = P.getImage(identyfikator)
        M.addText("Odebrałem obrazek:\n")
        M.addImage(obrazek, IMG_RAW)
        M.addText("\no identyfikatorze: %s" % str(identyfikator))
        self.response.out.write(M.reply(self))
        
application = webapp.WSGIApplication([('/', MainHandler)],debug=True)

def main():
    run_wsgi_app(application)

if __name__ == "__main__":
    main()

1.2.5. Sprawdzanie czy numer GG jest botem - metoda isBot

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

PHP Python

isBot(int $gg_number)

isBot(int gg_number)

Przykład:

PHP Python

$P->isBot(12345);

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 -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

 może zawierać wyłącznie atrybut style, w którym można ustawić: color, background-color, font-family, font-size
 oraz  - pogrubienie
 oraz  - pochylenie
 oraz  - podkreślenie
<s> oraz </s> - przekreślenie
  - przejście do nowej linii
 - indeks dolny
 - 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.