Kuanza haraka (API)

Mwongozo huu unakuonyesha miito minne ya REST inayohitajika kujibu simu yako ya kwanza kwa ejenti wa AI.

Hatua ya 1: Pata ufunguo wa API

1. Ingia

   Fungua app.thunderphone.com.

2. Nenda kwenye Funguo

   Nenda kwenye Shirika → Funguo katika dashibodi.

3. Unda ufunguo

   Bofya Unda ufunguo, upe jina, kisha unakili thamani ya sk_live_.... Ufunguo kamili unaonyeshwa mara moja pekee — uhifadhi mara moja katika kidhibiti chako cha siri.

Katika mwongozo huu wote, badilisha sk_live_YOUR_API_KEY kwa thamani uliyonakili hivi punde. Ufunguo hutambua shirika lako kiotomatiki, kwa hiyo huhitaji kamwe kuweka kitambulisho cha shirika katika URL.

Hatua ya 2: Unda ejenti

Ejenti hufafanua jinsi AI inavyoshughulikia mazungumzo — prompt, sauti, kiwango cha bidhaa, zana na ustahiki wa wijeti.

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "Customer Support",
    "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    "voice":  "john",
    "product": "spark"
  }'

import os, requests

agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={
        "name":   "Customer Support",
        "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
        "voice":  "john",
        "product": "spark",
    },
).json()
print("Agent id:", agent["id"])

const agent = await fetch("https://api.thunderphone.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name:    "Customer Support",
    prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    voice:   "john",
    product: "spark",
  }),
}).then((r) => r.json());
console.log("Agent id:", agent.id);

Hatua ya 3: Tenga nambari ya simu

Simu hii huomba nambari kutoka kwenye dimbwi la majaribio la ThunderPhone na kukabidhi ejenti wako mpya kama kidhibiti cha simu zinazoingia. (Ili kuleta nambari yako kutoka kwa mtoa huduma wa VoIP, angalia miunganisho ya VoIP badala yake.)

# First provision
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

number = requests.post(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"area_code": "415"},
).json()
requests.patch(
    f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])

Nambari yako mpya huanza katika status="provisioning" na hubadilika kuwa active ndani ya sekunde chache; utakapofunga kivinjari chako, nambari itakuwa tayari kupokea simu.

Hatua ya 4 (si lazima): Sanidi webhook

Kwa matukio ya wakati halisi (uelekezaji wa simu unaobadilika, uchakataji baada ya simu), ongeza endpoint ya webhook. Jiandikishe kwa matukio unayohitaji pekee.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

Jibu lina secret ya matumizi ya mara moja — nakili kwenye kidhibiti chako cha siri. Tumia siri hiyo kuthibitisha header ya X-ThunderPhone-Signature kwenye maombi yanayoingia (angalia muhtasari wa Webhooks).

Hatua ya 5: Jaribu ejenti wako

Piga simu kwenye nambari uliyotenga hivi punde. Ejenti hupokea simu, hujitambulisha, na hufuata prompt yako.

Kagua simu baada ya kuisha:

curl https://api.thunderphone.com/v1/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Chunguza simu mahususi ili kupata nakala ya mazungumzo na URL ya rekodi:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Hatua zinazofuata