Voice API (Call API)

Dokumentacja Voice API (Call API) systemu CallAPI / VPBX.

Call API

Główny endpoint do wykonywania połączeń głosowych z programowalną logiką.

{
    "from": "4822100100",
    "to": "TWÓJ NUMER w formacie E164, np: 48501000000",
    "webhook": "http://nie.dziala.w.aplikacji.demo",
    "webhook_method": "POST",
    "ring_timeout": 30,
    "objects": [
        {
            "type": "answer"
        },
        {
            "type": "wait",
            "params": {
                "time": 2
            }
        },
        {
            "type": "tts",
            "params": {
                "text": "Twój jednorazowy kod to: 1. 2. 3. 4.",
                "lang": "pl-PL/Maja"
            }
        },
        {
            "type": "tts",
            "params": {
                "text": "Powtarzam: Twój jednorazowy kod to: 1. 2. 3. 4.",
                "lang": "pl-PL/Maja"
            }
        }
    ]
}

Parametry zapytania

Odpowiedź - Pomyślne zakolejkowanie połączenia głosowego

Odpowiedź - odrzucenie połączenia głosowego

Obiekty Call API

answer - odebranie połączenia po stronie API

Połączenie powinno być odebrane aby uruchomić inne obiekty, które wymagają dwukierunkowej komunikacji głosowej. Obiekt answer nie wymaga innych dodatkowych parametrów.

{
    "type": "answer"
}

tts - Generowanie mowy

{
    "type": "tts",
    "params": {
        "text": "Witaj w systemie CallAPI",
        "lang": "pl-PL/Maja"
    }
}

tts_dtmf - Generowanie mowy, wybór jednocyfrowej opcji DTMF podczas mowy

{
    "type": "tts_dtmf",
    "params": {
        "text": "Wciśnij 1 aby potwierdzić, 2 aby odrzucić",
        "lang": "pl-PL/Maja",
        "digits": {
            "1": "potwierdzam",
            "2": "odrzucam"
        }
    }
}

playfile - Odtworzenie pliku dźwiękowego

{
    "type": "playfile",
    "params": {
        "url": "https://example.com/audio.mp3"
    }
}

playfile_dtmf - Odtworzenie pliku dźwiękowego i wybór jednocyfrowej opcji DTMF podczas odtwarzania pliku

{
    "type": "playfile_dtmf",
    "params": {
        "url": "https://example.com/audio.mp3",
        "digits": {
            "1": "opcja1",
            "2": "opcja2"
        }
    }
}

dtmf - Wybór jednocyfrowej opcji DTMF

Akcja dtmf pozwala na wprowadzenie opcji (cyfry) DTMF i wykonanie skoku do zadanego znacznika. W przypadku nie wprowadzenia żadnej cyfry, zostanie wykonana następna akcja.

{
    "type": "dtmf",
    "params": {
        "digits": {
            "1": "opcja1",
            "2": "opcja2",
            "3": "opcja3"
        }
    }
}

wait - przerwa

{
    "type": "wait",
    "params": {
        "time": 2
    }
}

label - znacznik

{
    "type": "label",
    "params": {
        "name": "moj_znacznik"
    }
}

jump - skok do zadanego znacznika

{
    "type": "jump",
    "params": {
        "label": "moj_znacznik"
    }
}

pstn - połączenie wychodzące

Akcja ta służy do zestawienia połączenia wychodzącego. Najczęściej wykorzystywana w przypadku call-proxy lub pbx.

{
    "type": "pstn",
    "params": {
        "number": "48500000000",
        "ring_timeout": 30,
        "cli": "48221234567"
    }
}

extension - połączenie na numer wewnętrzny

Akcja ta służy do zestawienia połączenia z numerem wewnętrznym centrali vpbx.pl. Opcja najczęściej wykorzystywana w przypadku pbx.

{
    "type": "extension",
    "params": {
        "number": "100",
        "ring_timeout": 30
    }
}

hangup - zakończenie połączenia

Rozłączenie połączenia. Ta akcja nie wymaga dodatkowych parametrów.

{
    "type": "hangup"
}

webhook - wywołanie adresu URL

Akcja webhook pozwala na wysłanie żądania HTTP na wskazany adres URL.

{
    "type": "webhook",
    "params": {
        "url": "https://example.com/webhook",
        "custom_data": {
            "alarm": "potwierdzony",
            "extradata": 2
        }
    }
}

Przykład - Potwierdzenie alarmu

Poniższy przykład pokazuje użycie obiektów do potwierdzenia odebrania alarmu:

{
    "from": "4822100100",
    "to": "48501000000",
    "webhook": "http://nie.dziala.w.aplikacji.demo",
    "webhook_method": "POST",
    "ring_timeout": 30,
    "objects": [
        {
            "type": "answer"
        },
        {
            "type": "wait",
            "params": {
                "time": 1
            }
        },
        {
            "type": "tts_dtmf",
            "params": {
                "text": "To jest Alarm. Wciśnij 1 aby potwierdzić",
                "lang": "pl-PL/Maja",
                "digits": {
                    "1": "potwierdzam"
                }
            }
        },
        {
            "type": "webhook",
            "params": {
                "url": "http://nie.dziala.w.aplikacji.demo",
                "custom_data": {
                    "alarm": "nie_potwierdzony"
                }
            }
        },
        {
            "type": "tts",
            "params": {
                "text": "Alarm nie został potwierdzony.",
                "lang": "pl-PL/Maja"
            }
        },
        {
            "type": "hangup"
        },
        {
            "type": "label",
            "params": {
                "name": "potwierdzam"
            }
        },
        {
            "type": "webhook",
            "params": {
                "url": "http://nie.dziala.w.aplikacji.demo",
                "custom_data": {
                    "alarm": "potwierdzony",
                    "extradata": 2
                }
            }
        },
        {
            "type": "tts",
            "params": {
                "text": "Dziękujemy za potwierdzenie odebrania alarmu.",
                "lang": "pl-PL/Maja"
            }
        }
    ]
}

Głosy dostępne w akcjach TTS