[Sugester V2](https://pomoc.sugester2.pl/index.md) / [Telefonia VoIP](https://pomoc.sugester2.pl/telefonia-voip.md)

# [Integracja Voip z firmą Ringostat](https://pomoc.sugester2.pl/integracja-ringostat.md)

Ringostat to dostawca telefonii i call trackingu. Po podłączeniu rozmowy z Ringostata trafiają do historii połączeń, przypinają się do klientów po numerze telefonu, a przy każdej rozmowie jest link do nagrania i dane kampanii (źródło, medium, kampania, identyfikator Google Analytics). Konfiguracja to dwa panele: dane z Ringostata wpisujesz w ustawieniach VoIP, a adres webhooka z ustawień VoIP wklejasz w Ringostacie.

## **1. Klucz API i ID projektu w panelu Ringostata**

1. Zaloguj się do panelu Ringostata (`https://app.ringostat.com`) i wejdź do projektu.
2. Przejdź do **Ustawienia -> Integracja -> Ringostat API**.
3. Skopiuj **Auth-key** i **Project id**. Oba są na tej samej stronie.

![Ringostat API: Auth-key i Project id](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/85e68e04910d8f69036367fcb6af0cf69453ec45)

Jedno konto łączy się z jednym projektem Ringostata. Jeśli masz kilka projektów, każdy ma własny klucz i własne ID.

## **2. Klucz i ID projektu w ustawieniach VoIP**

1. Przejdź do **Ustawienia VoIP** (`/voip/settings`) i kliknij **Edycja**.
2. W sekcji **Ringostat** wpisz **Klucz API** (Auth-key) i **ID projektu Ringostat**.
3. Kliknij **Zapisz**. Po zapisie klucz widać jako gwiazdki.

## **3. Adres webhooka**

1. Na stronie **Ustawienia VoIP**, w sekcji **Dane do integracji -> Ringostat**, kliknij **Wygeneruj adres webhooka**.
2. Skopiuj adres przyciskiem **Kopiuj**. Będzie potrzebny w kroku 5.

![Ustawienia VoIP: sekcja Ringostat z adresem webhooka](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/f3d5990b18d67af7b5372df3cb8f3cad0ac6128f)

Adres zawiera token przypisany do konta. Traktuj go jak hasło: kto go zna, może wysyłać zdarzenia połączeń na Twoje konto. Token da się wyłączyć w **Tokenach API** konta.

## **4. Numer VoIP i SIP-y**

1. Przejdź do **Numery VoIP** (`/voip/voips`) i kliknij **Nowy**.
2. Wybierz dostawcę **ringostat** i wpisz numer projektu dokładnie tak, jak jest w panelu Ringostata, w formacie międzynarodowym (np. `+48225987314`). Po tym numerze system rozpoznaje, do którego numeru należy rozmowa.

![Numer VoIP z dostawcą Ringostat](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/0339a7d7d1011cf727d71d438e7d84983436bf6b)

3. Dla każdego pracownika, który ma dzwonić z karty klienta, dodaj **SIP** (`/voip/sips`) z numerem VoIP z punktu 2 i numerem wewnętrznym tego pracownika z Ringostata (**Pracownicy 2.0 -> Numer dodatkowy**, np. `101`). Po tym numerze rozmowy przypisują się do operatora.

## **5. Webhook w panelu Ringostata**

To najważniejszy i najbardziej zdradliwy krok. W panelu Ringostata przejdź do **Ustawienia -> Integracja -> Webhooks 2.0** i kliknij **Dodaj unikalne zdarzenie**.

![Webhooks 2.0: formularz zdarzenia](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/d98c8dbe5f8ed162fbfdf48c3b2666455cd7975d)

1. **Nazwa**: dowolna, np. `Intum - po połączeniu`.
2. **Zdarzenie**: **Po połączeniu** (wtedy w zdarzeniu jest już czas rozmowy i nagranie).
3. Zakładka **HTTP**, **Metoda HTTP**: `POST`.
4. **Kierunek**: wklej adres webhooka z kroku 3 **razem z `https://` na początku**. Pole pokazuje po lewej prefiks `https://`, ale go nie dokleja. Bez niego Ringostat odrzuci wysyłkę komunikatem „Refusing to request unsafe URL" i nic nie dojdzie.
5. **Nagłówki**: `Content-Type: application/json`. **Format wysyłki danych**: `json`.
6. Kliknij **Dodaj wszystkie parametry**, a potem zmień **nazwy kluczy** (lewa kolumna) według tabeli niżej. Prawa kolumna (zmienna Ringostata) zostaje bez zmian. Klucze spoza tabeli mogą zostać, są ignorowane.

![Webhooks 2.0: parametry żądania po zmianie nazw kluczy](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/c56ddcdaf77163ba8fabe354356b8bcda86bf007)

| Zmienna Ringostata (prawa kolumna) | Klucz do wpisania (lewa kolumna) |
|---|---|
| Numer dzwoniącego | `caller` |
| Numer docelowy | `callee` |
| Status połączenia | `status` |
| Typ połączenia | `type` |
| Data połączenia | `date` |
| Czas trwania rozmowy (domyślny klucz `duration`) | `call_duration` |
| Czas trwania rozmowy (domyślny klucz `billsec`) | `dialog` |
| Czas oczekiwania | `waiting` |
| ID połączenia (domyślny klucz `uniqueid`) | `call_id` |
| Nagranie rozmowy | `record_link` |
| Nagranie rozmowy (wav) | `recording_wav` |
| Numer wewnętrzny pracownika | `manager_id` |
| Numer wychodzący (tylko zdarzenie wychodzące) | `outbound_number` |
| Źródło, Kanał, Kampania, Słowo kluczowe, Ogłoszenie | `source`, `medium`, `campaign`, `term`, `content` |
| Google Analytics client ID | `gaid` |
| Strona docelowa, Ostatnio odwiedzona strona, Referrer, IP odwiedzającego | `landing`, `last_page`, `referrer`, `user_ip` |

7. Kliknij **Zapisz**.
8. Powtórz kroki 1-7 dla zdarzenia **Po połączeniu wychodzącym** (ten sam adres, te same klucze). Bez niego rozmowy wychodzące i wynik autocalla nie wrócą do systemu.

Jeśli rozmowa nie pojawia się w historii, w Webhooks 2.0 kliknij **Sprawdź działania z błędami**. Lista pokazuje każdą nieudaną wysyłkę razem z treścią i powodem. Uwaga: przycisk **Wyślij** ponawia wysyłkę ze starym adresem, więc po poprawieniu adresu trzeba wykonać nowe połączenie.

## **6. Przekierowanie połączeń w Ringostacie**

Żeby ktoś odebrał połączenie przychodzące, w **Ustawienia -> Wirtualna centrala telefoniczna -> Przekierowanie połączeń** schemat musi kierować rozmowę na zalogowane konto SIP (aplikacja Ringostat Smart Phone) albo na numer telefonu. Jeśli konto SIP jest offline, rozmowa idzie od razu na pocztę głosową i w systemie ma status `VOICEMAIL`.

![Schemat przekierowań z numerem telefonu](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/bf6af7e44948e4f99029ecf781ee05a123e145a9)

## **7. Co widać po stronie systemu**

Po zakończonej rozmowie w **Rozmowy** pojawia się wpis z numerem dzwoniącego, numerem projektu, czasem rozmowy, statusem, linkiem **Odsłuchaj nagranie** i wierszem **Dane kampanii**.

![Karta rozmowy z nagraniem i danymi kampanii](https://s3.eu-west-1.amazonaws.com/attachments.intum.net/public-files/31076/cc3fcbb21a0bb7cc3ded541ed2a0d58e3f161370)

Statusy: `ANSWERED` i `PROPER` to rozmowy odebrane, `BUSY` to zajęte, a `NO ANSWER`, `FAILED`, `VOICEMAIL`, `DECLINE` i pozostałe to nieodebrane. Czas trwania na liście to czas samej rozmowy, bez dzwonienia.

## **8. Dzwonienie z karty klienta**

Kliknięcie w numer na karcie klienta zleca Ringostatowi połączenie: centrala dzwoni najpierw do operatora (konto SIP z numerem wewnętrznym z kroku 4), a po odebraniu łączy z klientem. Warunki: konto SIP operatora musi być **online** w Ringostat Smart Phone, a na koncie Ringostata musi być saldo na połączenia wychodzące. W przeglądarce softphone z Ringostatem nie działa, bo Ringostat nie udostępnia bramki WebRTC.

Czego integracja nie obejmuje: podglądu stanu linii na żywo oraz analiz AI, które zostają w panelu Ringostata.