Developer cookbook

Používejte vlastní čísla (VoIP, API)

Připojte Twilio nebo Telnyx — případně libovolný SIP trunk — importujte telefonní čísla, která již vlastníte, a nechte agenty ThunderPhone na nich přijímat a uskutečňovat hovory.

Ukázková čísla jsou vhodná pro prototypování, ale produkční provoz by měl používat čísla, která vlastníte prostřednictvím vlastního poskytovatele VoIP. Tento průvodce vás provede tříkrokovým postupem: test přihlašovacích údajů → vytvoření připojení → import čísel → ověření.

Podporovaní poskytovatelé#

1. Otestujte přihlašovací údaje#

Před vytvořením trvale uloženého připojení VoIP otestujte přihlašovací údaje poskytovatele a potvrďte, že fungují. Vrátí se verification_evidence_id, které předáte kroku vytvoření, aby přihlašovací údaje nebyly za testování zpoplatněny dvakrát.

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
  }
}

Pokud některá kontrola selže, status odpovědi bude fail a checks ukáže, který krok selhal. Opravte konfiguraci u poskytovatele (přiřazení trunku, seznam povolených IP adres, autorizaci odchozích hovorů) a zkuste to znovu.

2. Vytvořte připojení#

Předejte právě získané 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..."
  }'

Odpovědí je objekt VoipConnection se stavem status="connected". Přihlašovací údaje jsou uložené na straně serveru a následné požadavky GET je nikdy nevracejí jako prostý text — pro jejich změnu spusťte nový test a proveďte PATCH s novým ověřovacím podkladem.

3. Vypište a importujte čísla#

Zkontrolujte čísla dostupná pro vaše přihlašovací údaje, která ještě nejsou v organizaci ThunderPhone:

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

Poté importujte ta, která chcete:

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ždý import se ve vaší organizaci stane zdrojem telefonního čísla s source="voip" a status="provisioning".

4. Ověřte každé importované číslo#

Importací se číslo zaregistruje jako dostupné; skutečné směrování hovorů přes něj vyžaduje obousměrné ověření (kontrolu příchozího volání + ověřovací test odchozí autorizace).

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

Po úspěchu se voip_verification_status změní na verified a číslo přejde do stavu status="active". Při selhání odpověď uvádí, co se nezdařilo — opravte to (často chybí přiřazení trunku v dashboardu poskytovatele) a požadavek zopakujte.

5. Přiřaďte agenty a uskutečněte hovor#

Po ověření čísla přiřadíte agenty pro příchozí a odchozí hovory stejně jako u ukázkového čísla. Viz Zpracování příchozích hovorů a Uskutečňování odchozích hovorů.

Obměna přihlašovacích údajů#

Když se klíč poskytovatele obmění, znovu proveďte postup otestování a následné aktualizace:

# 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"
  }'

Připojení zůstane zachováno — čísla není nutné znovu importovat.

Další kroky#