Użyj własnych numerów (VoIP, API)

Połącz Twilio, Telnyx, SignalWire, Vonage, Plivo lub dowolny inny trunk SIP przez SIP, zaimportuj numery telefonów, które już posiadasz, i pozwól agentom głosowym ThunderPhone odbierać oraz wykonywać na nich połączenia.

Zatwierdzone numery ThunderPhone mogą wykonywać połączenia wychodzące i obsługiwać kampanie. Jeśli wolisz używać własnych numerów za pośrednictwem własnego dostawcy VoIP, ten przewodnik przeprowadzi Cię przez proces połączenia: przetestuj poświadczenia → utwórz połączenie → zaimportuj numery → zweryfikuj.

Obsługiwani dostawcy#

1. Przetestuj poświadczenia#

Zanim utworzysz trwałe połączenie VoIP, sprawdź poświadczenia dostawcy, aby potwierdzić, że działają. Zwracany jest identyfikator verification_evidence_id, który przekazujesz do kroku tworzenia, aby za testowanie poświadczeń nie naliczono opłaty dwukrotnie.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Jeśli któraś kontrola się nie powiedzie, status odpowiedzi będzie mieć wartość fail, a checks wskaże, który etap zakończył się błędem. Popraw konfigurację po stronie dostawcy (przypisanie trunku, lista dozwolonych adresów IP, autoryzacja połączeń wychodzących) i spróbuj ponownie.

2. Utwórz połączenie#

Przekaż właśnie otrzymany verification_evidence_id:

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

Odpowiedź to obiekt VoipConnection ze stanem status="connected". Poświadczenia i inne tajne wartości połączenia są przechowywane po stronie serwera i nigdy nie są zwracane w postaci zwykłego tekstu przez kolejne żądania GET — aby je zmienić, uruchom ponownie test i wykonaj PATCH z nowym potwierdzeniem.

Subkonta Twilio#

Połączenie Twilio jest powiązane z jednym kontem Twilio, którego Account SID i Auth Token zawiera. Twilio przechowuje numery telefonów i trunki SIP w obrębie każdego subkonta, więc połączenie utworzone przy użyciu konta nadrzędnego widzi tylko własne numery konta nadrzędnego, a istniejącego połączenia nie można później przełączyć na inne subkonto.

Aby uzyskać dostęp do numerów przechowywanych na subkontach, utwórz jedno połączenie na każde subkonto. Panel zrobi to za Ciebie: gdy połączysz konto nadrzędne z aktywnymi subkontami, okno konfiguracji wyświetli ich listę, zaznaczysz wybrane konta, a ThunderPhone utworzy połączenie (oraz trunk SIP) na każdym z nich. Ten sam proces jest dostępny przez API:

# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'

Odpowiedź zawiera po jednym wierszu dla każdego subkonta ze stanem status created, skipped (już połączono) lub failed, a także błędem error, na który możesz zareagować. Wiersze są niezależne, więc błąd w jednym subkoncie nigdy nie blokuje pozostałych, a discovery_id pozostaje ważny przez 30 minut, dzięki czemu wiersz zakończony błędem można po prostu ponowić. Tokeny subkont są odczytywane z Twilio podczas wykrywania i zapisywane w nowym połączeniu; nigdy nie są zwracane przez API. Każde nowe połączenie następnie importuje i weryfikuje numery dokładnie tak samo jak połączenie utworzone ręcznie. Dodaj "enable_transfers": true, aby włączyć także transfery połączeń dla pnia SIP każdego nowego połączenia; błąd w tym przypadku jest zgłaszany w test_result.transfer_enable_error tego połączenia i nie powoduje błędu wiersza.

3. Wyświetl i importuj numery#

Sprawdź numery widoczne dla Twoich danych uwierzytelniających, które nie są jeszcze w organizacji ThunderPhone:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Następnie zaimportuj wybrane numery:

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

Każdy import staje się zasobem numeru telefonu w Twojej organizacji z number_type="voip" i status="provisioning".

4. Zweryfikuj każdy zaimportowany numer#

Importowanie rejestruje numer jako dostępny; faktyczne kierowanie przez niego połączeń wymaga weryfikacji. W przypadku połączeń z dostawcami (Twilio, Telnyx) ponownie sprawdza ona poświadczenia dostawcy i osiągalność SIP. W przypadku połączenia ręcznego SIP najpierw podejmowana jest próba samopołączenia zwrotnego: ThunderPhone wykonuje krótkie połączenie testowe z numeru, przez Twój trunk SIP, z powrotem na ten sam numer. Jeśli nie zweryfikuje to ścieżki przychodzącej, system przechodzi do krótkiego połączenia testowego z numeru, przez Twój trunk SIP, na numer ThunderPhone. Testy te sprawdzają nazwę użytkownika, hasło, transport, routing wychodzący i dostarczanie połączeń przychodzących trunku. Twój operator nalicza opłaty za te połączenia tak jak za każde inne.

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Po pomyślnej weryfikacji voip_verification_status zmienia się na verified, a numer otrzymuje status="active". Numer na własnym koncie Telnyx nadal odbiera połączenia przychodzące, gdy jego połączenie testowe się nie powiedzie lub połączenia wychodzące nie są jeszcze skonfigurowane: otrzymuje status="active" z voip_verification_status ustawionym na unverified, a odpowiedź wyjaśnia przyczynę. W przypadku niepowodzenia odpowiedź określa, co nie zadziałało — dla ręcznego trunku jest to odpowiedź SIP operatora, na przykład "odrzucono poświadczenia ThunderPhone (SIP 401)" lub "nie można było skierować połączenia (SIP 404)" — popraw to (poświadczenia, dozwolone źródłowe adresy IP, brakujące przypisanie trunku w panelu dostawcy) i wywołaj ponownie.

W przypadku ręcznego połączenia SIP z listą dozwolonych adresów test połączenia przychodzącego również zakończy się niepowodzeniem, jeśli te Dozwolone źródłowe adresy IP blokowałyby rzeczywiste połączenie przychodzące.

5. Przypisz agentów i odbierz połączenie#

Po zweryfikowaniu numeru przypisujesz agentów obsługujących połączenia przychodzące / wychodzące tak samo jak w przypadku numeru ThunderPhone. Zobacz Obsługa połączeń przychodzących oraz Wykonywanie połączeń wychodzących.

Rotacja poświadczeń#

Gdy klucz dostawcy zostanie zmieniony, ponownie wykonaj proces testowania, a następnie aktualizacji:

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

Połączenie pozostaje na miejscu — nie trzeba ponownie importować numerów.

Kolejne kroki#