Zapytania API i dokumentacja API w Oki-Toki

Czym jest API?

API to sposób, dzięki któremu jeden program może „dogadać się” z innym. Można poprosić Oki-Toki o przekazanie lub pobranie potrzebnych danych. Na przykład automatycznie wysyłać informacje o klientach do Twojego CRM albo wczytywać dane z powrotem do Oki-Toki.

Jaki jest pożytek z API dla call center?

• Automatyzacja: API przejmuje rutynowe zadania. Na przykład nowy kontakt trafia do Twojego CRM, a dane są automatycznie aktualizowane;
• Integracja: dzięki API łatwo połączysz Oki-Toki z innymi systemami — CRM, analityką, chatbotami itp. Wszystkie narzędzia działają razem jak jeden organizm, co upraszcza i przyspiesza procesy biznesowe.
• Dane w czasie rzeczywistym: system od razu wysyła lub odbiera informacje, gdy tylko się pojawiają. To wygodne do analizy i monitoringu;
• Łatwa rozbudowa: można dodawać nowe funkcje i narzędzia bez skomplikowanych zmian. To szczególnie wygodne, gdy Twój projekt rośnie;
• Zmniejszenie liczby błędów: mniej pracy ręcznej — mniejsze ryzyko pomyłek. Wszystko dzieje się automatycznie, szybko i precyzyjnie.

Rodzaje zapytań API w Oki-Toki

W Oki-Toki stosowany jest standardowy sposób komunikacji z serwisami internetowymi – REST API. System pobiera informacje na żądanie i zwraca odpowiedź w odpowiednim formacie, najczęściej JSON. W Oki-Toki dostępne są następujące metody zapytań:

• GET – służy do pobierania informacji, na przykład kontaktów z CRM lub statystyk połączeń;
• POST – wysyła nowe dane do systemu, na przykład do masowego dodawania lub usuwania zadań dialera, włączania/wyłączania dialera.

Do przetestowania zapytania, sprawdzenia poprawności danych lub znalezienia błędu sprawdzi się Postman.

Dokumentacja i konfiguracja API w Oki-Toki

Dokumentacja API Oki-Toki to Twoja instrukcja obsługi, w której opisano metody zapytań, przykłady użycia i strukturę danych. Dla wygody dokumentacja techniczna API jest podzielona na sekcje według głównych funkcji i narzędzi Oki-Toki.

Dostęp do API 

Dostep do API odbywa sie za pomoca tokenow – to klucze, ktore daja systemowi zrozumiec, kto sie z nim laczy. Dzieki nim latwo pracowac z API i bezpiecznie przekazywac dane.

W Oki-Toki uzytkownik moze utworzyc wlasny token, jesli posiada uprawnienie „Zarzadzanie uzytkownikami” w swojej roli. Takie uprawnienie jest w standardowych rolach „Admin” i „Superviser” , ale mozna je tez dodac do dowolnej roli utworzonej przez Ciebie. 

„Zarzadzanie zasobami zewnetrznymi, integracjami i zdarzeniami (Webhook)” – to kolejne uprawnienie niezbedne do pracy z API. Bez niego nie uda sie utworzyc integracji ani dodac Webhooka.

Wiecej o rolach mozna dowiedziec sie w osobnym artykule na blogu.

Jak uzyskac klucz API?

Aby utworzyc dowolne zadanie API, potrzebujesz tokena. Zeby go wygenerowac, przejdz do sekcji Lista uzytkownikow. W ustawieniach profilu wybierz pozycje „Bezpieczenstwo”. Tutaj mozna utworzyc, wyswietlic lub usunac token.

Kody bledow zapytan API

Bledy zdarzaja sie kazdemu – nawet profesjonalisci napotykaja trudnosci przy przekazywaniu danych lub wykonywaniu zadan. Najwazniejsze to wiedziec, jak to naprawic. Przygotowalismy liste najczestszych bledow podczas wykonywania zapytania api:

• 401 (Unauthorized) – w zapytaniu podano nieistniejacy obiekt albo Twoj token jest nieprawidlowy;
• 403 (Forbidden) – oznacza to, ze serwer zrozumial zapytanie, ale odmawia dostepu. Byc moze nie masz uprawnien ani zezwoleń do wykonania tego zapytania;
• 404 (Not Found) – w adresie URL sa bledy, sprawdz poprawnosc wprowadzonych danych;
• 405 Method Not Allowed – nieprawidlowy typ zapytania. Na przyklad probowales uzyc metody POST zamiast GET;
• 422 (Unprocessable Entity) – zapytanie zostalo przyjete, ale nie zostalo przetworzone z powodu bledu semantycznego w „ciele” danych;
• 429 Too Many Requests – przekroczenie limitu zapytan;
• 500 (Internal Server Error)– problemy z dzialaniem serwera lub z przetwarzaniem Twojego zapytania.

Kazdemu bledowi zapytan API towarzyszy kod i komunikat, ktore pomoga okreslic przyczyne problemu i ja naprawic.

Przyklady wykorzystania API w Oki-Toki

API Oki-Toki — narzedzie do rozwiazywania wielu zadan w call center. Oto kilka przykladow, gdzie jego wykorzystanie pomoze zaoszczedzic czas i uproscic procesy:

1. Dodawanie klientow do dialer do post-obrobki przychodzacych polaczen/ zimnej bazy – po pomyslnym polaczeniu z agentem dane automatycznie sa przekazywane do dalszego obdzwaniania. To oszczedza czas i zmniejsza ryzyko bledow, eliminujac reczna obsluge;
2. Usuwanie zadan z dialer – zadania, ktore zostaly obrobione i sa juz nieaktualne, poniewaz klienci dali odmowe, zostana usuniete z listy obdzwaniania;
3. Przekazywanie danych o polaczeniach do CRM – wszystkie potrzebne dane o polaczeniach, niezbedne do dalszej pracy z klientem, zostana przekazane do CRM;
4. Aktualizacja kontaktu w CRM – Na przyklad zmiana statusu zadan lub dodanie nowych parametrow do analizy.

Jak utworzyc zapytanie API?

Aby utworzyc zapytanie do pracy z danymi w Oki-Toki, najpierw zapoznaj sie z dokumentacja API. Tutaj zebrano informacje o tym, jakie dane mozna przekazywac lub otrzymywac. Wybierz potrzebne zapytanie i sprawdz, jaka dodatkowa informacja moze byc potrzebna, na przyklad ID dialer.

Aby znalezc te dane, wejdz do odpowiedniego dialer. ID bedzie wskazane w linku w pasku adresu przegladarki — to liczba po nazwie narzedzia.

Przyklad zapytania API w Postman: dodawanie do Czarnej listy

Link zapytania utworzymy w programie Postman, ktory trzeba bedzie zainstalowac na swoim urzadzeniu.

W dokumentacji znajdujemy sekcje „Lists”, wybieramy zapytanie „Adding a value to a list” . Zapytanie dodaje dane do Twoich list. Nie musi to byc koniecznie „Czarna lista” — mozesz chciec uzupelnic „Liste klientow VIP” albo dowolna inna, dopasowana do Twoich procesow biznesowych.

Przejdzmy do tworzenia linku API:

• sprawdzamy w dokumentacji typ zapytania – w naszym przypadku to post i kopiujemy link URL https://home.oki-toki.net/api/v1/lists/add. Przechodzimy do Postman, ustawiamy typ i wklejamy link.

• kolejny krok – Twój token. Jak wygenerować token opisaliśmy wyżej w artykule;
• w zapytaniu trzeba podać parametr ID listy. W tym celu przejdź do sekcji Listy, znajdź potrzebną, skopiuj numer z paska adresu i przenieś go do Postman. 
• Parametr „values” należy uzupełnić danymi, które trafią do listy, na przykład numerem telefonu; 

Po dodaniu wszystkich parametrów generuje się nam link w takiej postaci: 

https://home.oki-toki.net/api/v1/lists/add?api_token=(TWÓJ TOKEN)list_id=101&values=(NUMER TELEFONU)

Generujemy zapytanie, jeśli wszystko jest poprawnie, otrzymujemy odpowiedź – 200 OK. Teraz potrzebny numer został dodany do czarnej listy.

Aby skonfigurować różne warunki uruchamiania zapytań, używaj zdarzeń. Pozwalają one przekazywać nie tylko dane o połączeniach i klientach, ale także informacje o naruszeniach, statusach użytkowników i uruchomieniu analizy mowy. To pozwala monitorować kluczowe wskaźniki pracy agentów, ich aktywność, rejestrować odchylenia od scriptów lub naruszenia dyscyplinarne, aby utrzymać wysoki poziom jakości obsługi.

Jak skonfigurować integrację API?

Jeśli trzeba połączyć Oki-Toki z zewnętrznym zasobem, pomoże integracja API. Na przykład przekazywanie danych o klientach lub dodawanie numeru do dialera można zautomatyzować przez API. Ustawienia składają się z dwóch etapów:

Etap 1. Tworzenie webhook

Na początek trzeba utworzyć webhook w sekcji Zewnętrzne zasoby:

• Podaj nazwę;
• W polu URL wklej link, w zależności od zadania. Na przykład, aby dodać zadanie do dialer, należy znaleźć w dokumentacji technicznej API zapytanie „Adding a task (number) to a call” skopiować link i wkleić go w polu URL;
• Wybierz metodę przesyłania danych z listy: GET, POST, JSON;
• W polu „Ogólne parametry zapytań” wpisz swój klucz dostępu w formacie: api_token= TWÓJ TOKEN.

W przykładzie pokazano, jak utworzyć webhook do automatyzacji zadań wewnątrz Oki-Toki. Jeśli w polu URL zostanie podany link do zewnętrznego systemu, Oki-Toki będzie integrować się z nim. 

Jak zintegrować chat-bota z Telegram przeczytasz na naszym blogu.

Etap 2. Tworzenie zdarzenia

Przejdź do sekcji Zdarzenia i integracje i utwórz nowe powiązanie.

• Podaj nazwę i typ zdarzenia (działania użytkowników, połączenia, naruszenia);
• Integracja zewnętrzna – wybierz z listy lub dodaj nowe źródło zewnętrzne;
• Warunki uruchomienia – ustaw trigger aktywacji. Lista warunków zależy od typu zdarzenia;

• Parametry działania – w tym polu należy wprowadzić dane do doprecyzowania zapytania. Dostępne parametry, których można użyć w zapytaniu, są wskazane w dokumentacji;
• Zmienne są wyświetlone na liście. Po kliknięciu wybranej zostanie ona skopiowana do uzupełnienia parametrów działania. 

Raportowanie i koszty zapytań API

Monitorować, jak są wykonywane zapytania, można za pomocą Dziennika wywołań API. Raport jest generowany według daty, uzytkownikow, czasu trwania wykonania i typu zapytania – wybierz API. Gotowy raport zawiera informacje o dacie, godzinie, czasie trwania i nazwie uzytkownika, ktory utworzyl zapytanie, a takze URL i parametry zapytania.

Dostepny jest eksport w formatach HTML, Google Sheets i Microsoft Excel.

W Dzienniku zdarzen znajdziesz informacje o tym, jakie zdarzenia zostaly przetworzone i z jakim wynikiem. Raport zawiera nazwe, typ zdarzenia, integracje, date utworzenia i przetworzenia, aktualny status (powodzenie, niepowodzenie lub oczekiwanie), a takze dane wykorzystane podczas tworzenia zdarzenia i integracji za pomoca API.

Zapytania API to platna funkcja; informacje o cenach znajdziesz w sekcji Zarzadzanie uslugami. Swoje codzienne obciazenia najlatwiej sledzic w Dzienniku salda.

Dzieki tej instrukcji i dokumentacji Oki-Toki bedziesz mogl skonfigurowac przekazywanie danych oraz zapytania API. Integracje i webhooki Oki-Toki rozwiaza wiekszosc praktycznych zadan szybko, skutecznie i bez zbędnego wysilku. To zoptymalizuje wiele procesow biznesowych Twojej firmy i pozwoli skupic sie na tym, co najwazniejsze — wysokiej jakosci obsludze klientow.