Zapytanie API do połączenia 2 numerów (prosty Callback)
Aby przyspieszyć obsługę zgłoszeń od klientów, mogą Państwo skonfigurować automatyczne oddzwanianie do klienta, który przesłał wypełniony formularz rejestracji lub zamówienia na Państwa stronie.
Analogicznie można inicjować połączenie z karty klienta w Państwa systemie CRM.
Proszę zwrócić uwagę, że tej metody nie można używać na Front End. Ze względów bezpieczeństwa oraz ochrony danych osobowych korzystanie z tego zapytania na Front End nie jest dostępne.
Ważny warunek działania metody
Wartością parametru extension może być wyłącznie numer telefonu z projektu (numer musi być podłączony do projektu jako „wejściowy” w sekcji „Wirtualna centrala” → „Podłączenie numerów”).
Opis parametrów zapytania
Adres API: https://api.ringostat.net/callback/outward_call ;
Metoda — POST;
Auth-key — klucz dostępu do projektu w Ringostat;
Extension — numer telefonu, z którego wykonywane jest połączenie
(musi być podłączony jako numer przychodzący w sekcji „Wirtualna centrala” → „Podłączenie numerów”);Destination — numer telefonu lub login konta SIP, na który wykonywane jest połączenie;
Content-Type:
application/x-www-form-urlencoded
Przykład dla Node.js:
const https = require('https);
const config = {
host: 'api.ringostat.net',
path: '/callback/outward_call',
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `extension=380441112233&destination=380671112233`;
request.write(body);
request.end();
Zapytanie API do połączenia 2 numerów (rozszerzony Callback)
Rozszerzona metoda pozwala na wykonanie połączenia między dowolnymi dwoma stronami — nawet takimi, które nie istnieją w Ringostat (np. dowolny numer telefonu lub konto SIP menedżera oraz numer klienta). Źródła takiego połączenia będą widoczne w statystykach tak samo jak przy standardowym Callback z widgetu.
Metoda ta sprawdzi się przy inicjowaniu połączeń z CRM, obsłudze zgłoszeń z formularzy na stronie lub w serwisach ogłoszeniowych.
Opis parametrów zapytania
Adres API: https://api.ringostat.net/a/v2 ;
Metoda — POST;
Auth-key — klucz dostępu do projektu;
clientIP — rzeczywisty lub losowy adres IP;
caller — numer lub konto SIP, na które należy oddzwonić;
callee — numer lub konto SIP, które odbierze połączenie;
projectId — ID projektu Ringostat.
Headers zapytania
Nazwa parametru | Opis |
| application/json |
| "unique_auth_key_string" |
Body zapytania
Nazwa parametru | Opis |
| Wersja protokołu (2.0) |
| Dowolna liczba do powiązania zapytania z odpowiedzią |
| Metoda serwera Ringostat: Api\V2\Callback.external |
Parametry dla połączeń wychodzących
Nazwa parametru | Opis |
| Typ kierunku: default – numer telefonu, scheme – schemat przekierowania |
| Numer telefonu klienta |
| Numer telefonu lub konto SIP pracownika |
| Typ połączenia: out – jako wychodzące (typ danych string) |
| Określa pierwszy kierunek: 0 – najpierw caller, potem callee 1 – najpierw callee, potem caller |
| Adres IP użytkownika |
| Źródło |
| Kanał |
| Kampania |
| Słowo kluczowe |
| Treść |
| Client ID Google Analytics |
| User Agent klienta |
Parametry dla połączeń przychodzących
Nazwa parametru | Opis |
| Typ kierunku |
| Numer klienta |
| Numer lub SIP pracownika |
| Typ połączenia: in – jako przychodzące |
| Kolejność połączenia |
| IP użytkownika |
| Źródło |
| Kanał |
| Kampania |
| Słowo kluczowe |
| Treść |
| Client ID Google Analytics |
| User Agent |
Aby przekazać dane o sesji użytkownika, należy je zbierać samodzielnie i dodać do zapytania.
Na przykład:
parametry UTM można pobrać z pliku cookie rngst2 (jeśli zainstalowano skrypt podmiany),
ClientID Google Analytics z pliku cookie _ga.
Przykład dla Node.js:
const https = require('https');
const config = {
host: 'api.ringostat.net',
path: '/a/v2',
method: 'POST',
headers: {
'Auth-key': 'unique_auth_key_string'
}
};
const callback = response => {
let result = Buffer.alloc(0);
response.on('data', chunk => {
result = Buffer.concat([ result, chunk ]);
});
response.on('end', () => {
//handler response
});
};
const request = https.request(config, callback);
const body = `{
"jsonrpc": "2.0",
"id": 777,
"method": "Api\\V2\\Callback.external",
"params": {
"callee_type": "default",
"caller_type": "default",
"caller": "380671112233",
"callee": "380632223344",
"manager_dst": 1,
"direction": "out",
"projectId": "11111",
"clientIp": "10.10.10.10",
"utmSource": "ringostat",
"utmMedium": "referral",
"utmCampaign": "extended_callback",
"utmTerm": "test_api_request",
"utmContent": "content",
"clientId": "111111111.2222222222",
"clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
}
}`;
request.write(body);
request.end();
Możliwe błędy zapytania
400 Bad Request — brak jednego z parametrów / nieprawidłowy caller lub callee / brak konwersji do JSON
401 Unauthorized — brak lub nieprawidłowy Auth-Key
403 Forbidden — brak dostępu (nieprawidłowy Auth-Key)
Przykłady użycia
Przykład z kontem SIP (caller)
Sytuacja:
Caller — konto SIP,
Callee — numer telefonu
Połączenie do klienta zostanie wykonane z numeru ustawionego w domyślnych ustawieniach połączeń wychodzących.
Przykład z numerem klienta (caller)
Sytuacja:
Caller — numer klienta,
Callee — konto SIP
Połączenie zostanie wykonane zgodnie z regułami ustawień połączeń wychodzących.
Rekomendujemy korzystanie z tej konfiguracji dla poprawnego działania reguł i prezentacji numerów.
Przykład:
Klient zamówił połączenie na numer w formacie +380XXXXXXXXX przez formularz na stronie.
Klient zobaczy połączenie przychodzące z numeru przypisanego do kierunku +380.
Drugi klient zamówił połączenie na numer +48XXXXXXXXX.
Klient zobaczy połączenie przychodzące z numeru przypisanego do kierunku +48.
Przykład ze schematem przekierowania (callee)
Sytuacja:
Caller — numer klienta,
Callee — schemat przekierowania
Przykład:
Klient zamówił połączenie na swój numer w formacie +380XXXXXXXXX za pomocą formularza na stronie (z wykorzystaniem rozszerzonej metody API Callback).
Połączenie należy przekierować na schemat przekierowania projektu.
Przykład zapytania:
"callee_type": "scheme",
"caller_type": "default",
"callee": "XXXXX",*
"caller": "380ХХХХХХХХХ"**
* callee — ID schematu przekierowania, na który zostanie skierowane połączenie
** caller — numer klienta
Aby sprawdzić, jaki ID został przypisany do wybranego schematu przekierowania, prosimy przejść w menu nawigacyjnym do sekcji:
Wirtualna centrala → Przekierowanie polaczeń
Następnie przy wybranym schemacie należy kliknąć przycisk „Edytuj schemat”.
Dziennik połączeń (direction in)
Kto dzwonił — wartość parametru caller (numer telefonu lub login konta SIP, na który zostało wykonane połączenie);
Dokąd dzwoniono — wartość parametru callee (numer lub konto SIP, z którego zostało wykonane połączenie);
Z kim połączono — wartość parametru caller (numer telefonu lub login konta SIP, na który zostało wykonane połączenie).
Dziennik połączeń (direction out)
Ustawiono parametr direction o wartości out — w dzienniku połączeń wywołanie jest zapisywane jako wychodzące w następujący sposób:
Kto dzwonił — wartość parametru callee (numer lub konto SIP, z którego zostało wykonane połączenie);
Dokąd wykonano połączenie — wartość parametru caller (numer telefonu lub login konta SIP, na który zostało wykonane połączenie);
Z kim połączono — wartość parametru caller (numer telefonu lub login konta SIP, na który zostało wykonane połączenie).
Test zapytania
Mogą Państwo sprawdzić zapytanie na stronie:
https://ringostat.readme.io/reference/post_callback-outward-call
Zapytanie API (prosty Callback)
Zapytanie API (rozszerzony Callback)
Można tam również wskazać parametry (1), Auth-key (2) oraz wysłać zapytanie testowe (3):
