ET
ToodeIntegratsioonidHinnadArendajaleAPIKontakt
Logi sisse

API viide

API v1 kõik otspunktid. Näited curli, JavaScripti (fetch) ja Pythoniga (requests); valitud keel jäetakse kogu lehel meelde.

Baas-URLhttps://hubvocal.com/v1
AutentimineAuthorization: Bearer vt_live_…
Päringupiirang120 päringut/min võtme kohta · 429 + Retry-After
Õigusedread · write · calls
Igal võtmel on read, write ja/või calls. read hõlmab GET-päringuid, write muudatusi ja calls väljuvaid kõnesid. Päring, mis jääb võtme õigustest välja, saab vastuse 403.
Vea sisu{"detail": "..."}
OpenAPIGET /v1/openapi.json

Autentimise, lehele lisamise ja veakoodide kohta lugege jaotisest Arendajale.

Agendid

Vestlused toimuvad tekstirežiimis, seega testitakse juhiseid ja tööriistade kasutust, mitte häält ega viivitust. Simulatsioone käivitatakse juhtpaneelist; nende jaoks /v1 otspunkti veel pole.

Agentide loend

GET /v1/agents

Tagastab kõik teie organisatsiooni agendid samas järjekorras nagu juhtpaneelil.

Päring

curl 
curl "https://hubvocal.com/v1/agents" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "front-desk",
    "name": "Front desk",
    "lang": "en",
    "engine": "live",
    "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
    "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
    "voice": {
      "voice": "marin",
      "speed": 1
    },
    "tools": {
      "builtins": [
        "end_call",
        "take_message"
      ],
      "webhooks": [
        "tl_8f3a2c"
      ]
    },
    "turn": {
      "first_speaker": "agent",
      "idle_check_s": 30
    },
    "recording": {
      "enabled": false,
      "announce": true
    },
    "post_call": {
      "summary": true,
      "fields": [
        {
          "name": "appointment_date",
          "type": "date",
          "description": "Requested appointment date, if any"
        },
        {
          "name": "callback",
          "type": "boolean",
          "description": "Does the caller want a callback?"
        }
      ]
    },
    "knowledge": {
      "doc_ids": [
        "kb_7d21e4"
      ],
      "mode": "tool"
    },
    "published_version": 3,
    "draft_changed": false
  }
]

Agendi loomine

POST /v1/agents

Loob agendi. Iga välja kontrollitakse serveris; piirangut ületavad väärtused lühendatakse. Kui edastate juba olemasoleva id, ebaõnnestub päring veaga 409. Muutmiseks kasutage PUT-i.

NimiAsukohtTüüpKirjeldus
id body string Valikuline. Väiketähed, numbrid ja sidekriipsud, kuni 48 märki. Kui puudub, luuakse nime põhjal.
name
kohustuslik		 body string Kuvatav nimi, kuni 60 märki.
lang
kohustuslik		 body string Vestluskeele kood, nt tr, en, de. Täielik loend on GET /v1/voices vastuses.
engine
kohustuslik		 body "live" | "gemini" | "realtime" | "classic" live: GPT-Live 1, gemini: Gemini Live, realtime: OpenAI Realtime, classic: STT → LLM → TTS.
instructions body string Süsteemijuhised, kuni 8000 märki.
greeting body string Mida agent esimesena ütleb, kuni 400 märki.
voice body object voice (nimi loendist /v1/voices), speed (ainult classic ja realtime; live ja gemini puhul fikseeritud 1.0), tone (vabatekstiline kõnestiil, kuni 600 märki).
tools body object builtins (end_call, take_message) ja webhooks (tööriistade id-d); kokku kuni 16 tööriista. Tühi või puuduv väärtus tähendab, et tööriistu pole. mcp: [{server_id, tools}] lisab tööriistu teie MCP-serveritest; need arvestatakse sama piirangu sisse.
turn body object Kõnevoorude seaded: sensitivity (low, balanced, high; ainult classic mootor), first_speaker (agent või caller), silence_wait_s (1–5), idle_check_s (0 või 10–120), agent_timeout_s (0 või 10–60). Tühjad väljad kasutavad vaikeväärtusi.
recording body object recording: {enabled (vaikimisi false), announce (vaikimisi true), announce_text?}. Kui salvestamine on sisse lülitatud, teavitab agent sellest enne tervitust.
post_call body object post_call.summary: koosta kõne lõppedes kokkuvõte (vaikimisi true). post_call.fields: kuni 24 välja, mis täidetakse pärast kõnet ({name, type, description, enum?, required?}).
knowledge body object doc_ids (kuni 50 teadmusbaasi dokumenti) ja mode ("tool"). Agent saab siis tööriista search_knowledge.
calendar body object integration_id ja calendar_id juhtpaneelist, duration_min (15–240), buffer_min (0–60), timezone, working_hours, min_notice_h (0–72), max_days_ahead (1–90). Lülitab sisse broneerimistööriistad.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/agents" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "marin",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  }
}'

Vastus · 201

JSON 
{
  "id": "front-desk",
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "marin",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  },
  "published_version": null,
  "draft_changed": true
}

Vead

  • 409 Selle id-ga agent on juba olemas.

Agendi pärimine

GET /v1/agents/{id}

Tagastab ühe agendi. published_version on avaldatud versiooni number (null, kui agenti pole kunagi avaldatud) ja draft_changed näitab, kas mustand erineb sellest.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.

Päring

curl 
curl "https://hubvocal.com/v1/agents/front-desk" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "id": "front-desk",
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "marin",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  },
  "published_version": 3,
  "draft_changed": false
}

Vead

  • 404 Selle id-ga agenti pole.

Agendi muutmine

PUT /v1/agents/{id}

Asendab agendi saadetud objektiga. Saatke kogu objekt: välja jäetud väljad saavad vaikeväärtused. Tees olev id on ülimuslik sisus oleva id ees.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.
name
kohustuslik		 body string Kuvatav nimi, kuni 60 märki.
lang
kohustuslik		 body string Vestluskeele kood, nt tr, en, de. Täielik loend on GET /v1/voices vastuses.
engine
kohustuslik		 body "live" | "gemini" | "realtime" | "classic" live: GPT-Live 1, gemini: Gemini Live, realtime: OpenAI Realtime, classic: STT → LLM → TTS.
instructions body string Süsteemijuhised, kuni 8000 märki.
greeting body string Mida agent esimesena ütleb, kuni 400 märki.
voice body object voice (nimi loendist /v1/voices), speed (ainult classic ja realtime; live ja gemini puhul fikseeritud 1.0), tone (vabatekstiline kõnestiil, kuni 600 märki).
tools body object builtins (end_call, take_message) ja webhooks (tööriistade id-d); kokku kuni 16 tööriista. Tühi või puuduv väärtus tähendab, et tööriistu pole. mcp: [{server_id, tools}] lisab tööriistu teie MCP-serveritest; need arvestatakse sama piirangu sisse.
turn body object Kõnevoorude seaded: sensitivity (low, balanced, high; ainult classic mootor), first_speaker (agent või caller), silence_wait_s (1–5), idle_check_s (0 või 10–120), agent_timeout_s (0 või 10–60). Tühjad väljad kasutavad vaikeväärtusi.
recording body object recording: {enabled (vaikimisi false), announce (vaikimisi true), announce_text?}. Kui salvestamine on sisse lülitatud, teavitab agent sellest enne tervitust.
post_call body object post_call.summary: koosta kõne lõppedes kokkuvõte (vaikimisi true). post_call.fields: kuni 24 välja, mis täidetakse pärast kõnet ({name, type, description, enum?, required?}).
knowledge body object doc_ids (kuni 50 teadmusbaasi dokumenti) ja mode ("tool"). Agent saab siis tööriista search_knowledge.
calendar body object integration_id ja calendar_id juhtpaneelist, duration_min (15–240), buffer_min (0–60), timezone, working_hours, min_notice_h (0–72), max_days_ahead (1–90). Lülitab sisse broneerimistööriistad.

Päring

curl 
curl -X PUT "https://hubvocal.com/v1/agents/front-desk" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "cedar",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  }
}'

Vastus · 200

JSON 
{
  "id": "front-desk",
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "cedar",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  },
  "published_version": 3,
  "draft_changed": true
}

Vead

  • 404 Selle id-ga agenti pole. Looge see esmalt POST-iga.

Agendi kustutamine

DELETE /v1/agents/{id}

Kustutab agendi. Organisatsioonil on alati vähemalt üks agent, seega viimase kustutamine ebaõnnestub.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/agents/front-desk" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "front-desk"
}

Vead

  • 400 See on organisatsiooni viimane agent.
  • 404 Selle id-ga agenti pole.

Versioonide loend

GET /v1/agents/{id}/versions

Agendi avaldatud versioonid, uusimad eespool. is_live tähistab versiooni, mida kõned praegu kasutavad.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.

Päring

curl 
curl "https://hubvocal.com/v1/agents/front-desk/versions" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "version": 3,
    "note": "Shorter greeting",
    "published_at": 1793829000,
    "published_by": "ayse@example.com",
    "is_live": true
  },
  {
    "version": 2,
    "note": "Added price list",
    "published_at": 1793740000,
    "published_by": "ayse@example.com",
    "is_live": false
  }
]

Vead

  • 404 Selle id-ga agenti pole.

Versiooni pärimine

GET /v1/agents/{id}/versions/{n}

Kogu agent sellisena, nagu see selles versioonis oli.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.
n
kohustuslik		 path integer Versiooni number.

Päring

curl 
curl "https://hubvocal.com/v1/agents/front-desk/versions/2" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "id": "front-desk",
  "name": "Front desk",
  "lang": "en",
  "engine": "live",
  "instructions": "You are the front desk assistant for a dental clinic. Help callers book appointments and answer general questions briefly. Never make things up; offer a callback from the team instead.",
  "greeting": "Hello, thanks for calling the clinic. How can I help you today?",
  "voice": {
    "voice": "marin",
    "speed": 1
  },
  "tools": {
    "builtins": [
      "end_call",
      "take_message"
    ],
    "webhooks": [
      "tl_8f3a2c"
    ]
  },
  "turn": {
    "first_speaker": "agent",
    "idle_check_s": 30
  },
  "recording": {
    "enabled": false,
    "announce": true
  },
  "post_call": {
    "summary": true,
    "fields": [
      {
        "name": "appointment_date",
        "type": "date",
        "description": "Requested appointment date, if any"
      },
      {
        "name": "callback",
        "type": "boolean",
        "description": "Does the caller want a callback?"
      }
    ]
  },
  "knowledge": {
    "doc_ids": [
      "kb_7d21e4"
    ],
    "mode": "tool"
  },
  "version": 2
}

Vead

  • 404 Sellist agenti või versiooni pole.

Mustandi avaldamine

POST /v1/agents/{id}/publish

Salvestab praeguse mustandi uue versioonina ja kõned hakkavad seda kasutama. Juba käimasolevad kõned jäävad oma versiooni juurde.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.
note body string Lühike märkus muudatuste kohta.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/agents/front-desk/publish" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Shorter greeting"
}'

Vastus · 200

JSON 
{
  "version": 4
}

Vead

  • 404 Selle id-ga agenti pole.

Tagasipööramine

POST /v1/agents/{id}/rollback

Kopeerib varasema versiooni mustandisse ja avaldab selle uue versioonina.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Agendi id, nt front-desk.
version
kohustuslik		 body integer Versioon, mis taastatakse.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/agents/front-desk/rollback" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "version": 2
}'

Vastus · 200

JSON 
{
  "version": 5
}

Vead

  • 404 Sellist agenti või versiooni pole.

Teadmusbaas

Dokumentide loend

GET /v1/knowledge

Teie organisatsiooni dokumendid koos töötlemise oleku, suuruse, lõikude arvu ja neid kasutavate agentidega.

Päring

curl 
curl "https://hubvocal.com/v1/knowledge" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "kb_7d21e4",
    "title": "Price list 2026",
    "kind": "file",
    "filename": "price-list-2026.pdf",
    "url": null,
    "size_bytes": 248113,
    "chunks": 42,
    "status": "ready",
    "error": null,
    "created_at": 1793740000,
    "used_by": [
      "front-desk"
    ]
  }
]

Dokumendi lisamine

POST /v1/knowledge

Laadige fail üles multipart/form-data vormingus (väli file), saatke tekst JSON-ina {title, text} või üks veebileht JSON-ina {url}. Tagastab 201 olekuga processing; pärige dokumenti, kuni selle olek on ready või failed.

NimiAsukohtTüüpKirjeldus
file body file multipart/form-data: pdf, docx, txt, md või html, kuni 10 MB.
title body string Pealkiri, koos väljaga text.
text body string Sisu lihttekstina.
url body string Faili või teksti asemel üks https-leht, mis laaditakse alla.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/knowledge" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Opening hours",
  "text": "We are open 09:00–18:00 on weekdays and 10:00–14:00 on Saturdays. Closed on Sundays."
}'

Vastus · 201

JSON 
{
  "id": "kb_9f03b1",
  "title": "Opening hours",
  "kind": "text",
  "filename": null,
  "url": null,
  "size_bytes": 96,
  "chunks": 0,
  "status": "processing",
  "error": null,
  "created_at": 1793740000,
  "used_by": []
}

Vead

  • 400 Failitüüpi ei toetata, fail on üle 10 MB, URL pole https või osutab privaataadressile või on organisatsiooni piirang (200 dokumenti, 200 MB) täis.

Dokumendi pärimine

GET /v1/knowledge/{id}

Dokument koos esimese 2000 märgi eelvaatega.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Dokumendi id.

Päring

curl 
curl "https://hubvocal.com/v1/knowledge/kb_7d21e4" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "id": "kb_7d21e4",
  "title": "Price list 2026",
  "kind": "file",
  "filename": "price-list-2026.pdf",
  "url": null,
  "size_bytes": 248113,
  "chunks": 42,
  "status": "ready",
  "error": null,
  "created_at": 1793740000,
  "used_by": [
    "front-desk"
  ],
  "preview": "Price list 2026. Check-up 1,500 TRY, scale and polish 2,000 TRY…"
}

Vead

  • 404 Selle id-ga dokumenti pole.

Dokumendi kustutamine

DELETE /v1/knowledge/{id}

Kustutab dokumendi ja eemaldab selle kõigilt agentidelt, kes seda kasutasid.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Dokumendi id.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/knowledge/kb_7d21e4" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "kb_7d21e4"
}

Vead

  • 404 Selle id-ga dokumenti pole.

Otsing

POST /v1/knowledge/search

Teeb sama otsingu, mida kasutab agent, ja tagastab kõige paremini sobivad lõigud koos skooriga. Kasulik dokumentide kontrollimiseks enne kasutuselevõttu.

NimiAsukohtTüüpKirjeldus
query
kohustuslik		 body string Otsitav tekst.
doc_ids body string[] Otsi ainult nendest dokumentidest.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/knowledge/search" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "how much is a scale and polish"
}'

Vastus · 200

JSON 
[
  {
    "doc_id": "kb_7d21e4",
    "title": "Price list 2026",
    "chunk_index": 3,
    "text": "Scale and polish: 2,000 TRY, about 30 minutes.",
    "score": 0.82
  }
]

Tööriistad

Sisseehitatud tööriistad

Neid tööriistu ei pea eraldi defineerima. Lülitage need sisse agendi väljal tools.builtins. search_knowledge lisatakse, kui knowledge on määratud. Broneerimistööriistad lisatakse, kui calendar on määratud.

NimiMida see teeb
end_callAgent jätab hüvasti ja lõpetab kõne 0,75 s pärast seda, kui on rääkimise lõpetanud. Kui helistaja vahepeal räägib, kõne lõpetamine tühistatakse. Kõne kirjes on ended_by: "agent".
take_messageVõtab vastu name, phone, message ja callback_requested ning kirjutab need kõne kirje välja outcomes[]. Kinnitust ei küsi.
search_knowledgeLisatakse automaatselt, kui agendil on väljal knowledge dokumendid. Otsib neist ja salvestab allikad kõne kirjesse.
check_availabilityTüüp read. Tagastab vabad ajad vahemikus date_from kuni date_to agendi tööaja piires. Lisatakse, kui calendar on määratud.
book_appointmentTüüp write, läbib kinnitusetapi. Broneerib aja start nimele name ja numbrile phone, soovi korral märkusega note. Broneering lisatakse välja outcomes[].
cancel_appointmentTüüp write, läbib kinnitusetapi. Tühistab broneeringu selle booking_ref järgi.

Kalendriintegratsioonid (Google Calendar) ühendatakse ainult juhtpaneelis; nende jaoks /v1 otspunkti pole. Kasutage agendi väljal calendar juhtpaneelist saadud integratsiooni ja kalendri id-sid.

Tööriistade loend

GET /v1/tools

Teie organisatsiooni webhook-tööriistad. Saladust ei tagastata kunagi; has_secret näitab, kas see on määratud.

Päring

curl 
curl "https://hubvocal.com/v1/tools" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "tl_8f3a2c",
    "name": "check_order",
    "description": "Looks up the shipping status of an order by its number.",
    "kind": "read",
    "url": "https://crm.example.com/hooks/order",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "Order number"
        }
      },
      "required": [
        "order_id"
      ]
    },
    "timeout_s": 8,
    "enabled": true,
    "has_secret": true,
    "created_at": 1793830000,
    "updated_at": 1793830000
  }
]

Tööriista pärimine

GET /v1/tools/{id}

Üks webhook-tööriist. Saladust ei tagastata kunagi.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Tööriista id.

Päring

curl 
curl "https://hubvocal.com/v1/tools/tl_8f3a2c" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "id": "tl_8f3a2c",
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 8,
  "enabled": true,
  "has_secret": true,
  "created_at": 1793830000,
  "updated_at": 1793830000
}

Vead

  • 404 Selle id-ga tööriista pole.

Tööriista loomine

POST /v1/tools

Määrab organisatsioonile webhook-tööriista. Kasutamiseks lisage selle id agendi välja tools.webhooks. URL peab olema https ega tohi osutada kohalikule ega privaatsele aadressile.

NimiAsukohtTüüpKirjeldus
name
kohustuslik		 body string Väiketähed, numbrid ja alakriipsud, algab tähega (3–41 märki). Organisatsioonis unikaalne; end_call ja take_message on reserveeritud.
description
kohustuslik		 body string Ütleb mudelile, millal ja kuidas tööriista kasutada.
kind
kohustuslik		 body "read" | "write" read käivitub kohe; write palub helistajal kõigepealt kinnitada.
url
kohustuslik		 body string Teie otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
parameters body object JSON Schema objekt: kuni 20 välja tüübiga string, number, integer või boolean (enum on lubatud).
timeout_s body integer 2 kuni 15 sekundit.
enabled body boolean Keelatud tööriistu mudelile ei pakuta.
secret body string Kasutatakse päringute allkirjastamiseks. Ainult kirjutamiseks; muutmisel jätab tühi väärtus praeguse saladuse alles ja "-" eemaldab selle.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/tools" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 8,
  "enabled": true,
  "secret": "whsec_2b7f…"
}'

Vastus · 201

JSON 
{
  "id": "tl_8f3a2c",
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 8,
  "enabled": true,
  "has_secret": true,
  "created_at": 1793830000,
  "updated_at": 1793830000
}

Vead

  • 400 Mõni väli rikub reegleid: nime vorming, https-URL, privaatne aadress, üle 20 parameetri või aegumine lubatud vahemikust väljas.
  • 409 Selle nimega tööriist on juba olemas või nimi on reserveeritud.

Tööriista muutmine

PUT /v1/tools/{id}

Asendab tööriista saadetud objektiga. Praeguse secret-i säilitamiseks jätke väli tühjaks või saatmata; eemaldamiseks saatke "-".

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Tööriista id.
name
kohustuslik		 body string Väiketähed, numbrid ja alakriipsud, algab tähega (3–41 märki). Organisatsioonis unikaalne; end_call ja take_message on reserveeritud.
description
kohustuslik		 body string Ütleb mudelile, millal ja kuidas tööriista kasutada.
kind
kohustuslik		 body "read" | "write" read käivitub kohe; write palub helistajal kõigepealt kinnitada.
url
kohustuslik		 body string Teie otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
parameters body object JSON Schema objekt: kuni 20 välja tüübiga string, number, integer või boolean (enum on lubatud).
timeout_s body integer 2 kuni 15 sekundit.
enabled body boolean Keelatud tööriistu mudelile ei pakuta.
secret body string Kasutatakse päringute allkirjastamiseks. Ainult kirjutamiseks; muutmisel jätab tühi väärtus praeguse saladuse alles ja "-" eemaldab selle.

Päring

curl 
curl -X PUT "https://hubvocal.com/v1/tools/tl_8f3a2c" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 10,
  "enabled": true,
  "secret": ""
}'

Vastus · 200

JSON 
{
  "id": "tl_8f3a2c",
  "name": "check_order",
  "description": "Looks up the shipping status of an order by its number.",
  "kind": "read",
  "url": "https://crm.example.com/hooks/order",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "Order number"
      }
    },
    "required": [
      "order_id"
    ]
  },
  "timeout_s": 10,
  "enabled": true,
  "has_secret": true,
  "created_at": 1793830000,
  "updated_at": 1793833600
}

Vead

  • 400 Mõni väli rikub reegleid: nime vorming, https-URL, privaatne aadress, üle 20 parameetri või aegumine lubatud vahemikust väljas.
  • 404 Selle id-ga tööriista pole.

Tööriista kustutamine

DELETE /v1/tools/{id}

Kustutab tööriista ja eemaldab selle kõigilt agentidelt, kes seda kasutasid.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Tööriista id.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/tools/tl_8f3a2c" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "tl_8f3a2c"
}

Vead

  • 404 Selle id-ga tööriista pole.

Tööriista testimine

POST /v1/tools/{id}/test

Saadab tööriista URL-ile päris päringu teie antud argumentidega ning tagastab oleku, kulunud aja ja kuni 4 KB vastuse sisust.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Tööriista id.
arguments body object Näidisargumendid, mis vastavad väljale parameters.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/tools/tl_8f3a2c/test" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "arguments": {
    "order_id": "A-10234"
  }
}'

Vastus · 200

JSON 
{
  "ok": true,
  "status": 200,
  "ms": 412,
  "body": "{\"order_id\":\"A-10234\",\"status\":\"shipped\",\"eta\":\"2026-11-07\"}"
}

Vead

  • 404 Selle id-ga tööriista pole.

MCP-serverid

MCP-serverite loend

GET /v1/mcp-servers

Teie organisatsiooni MCP-serverid koos oleku ja sünkroonitud tööriistadega. auth_set näitab, kas saladus on salvestatud; saladust ennast ei tagastata kunagi.

Päring

curl 
curl "https://hubvocal.com/v1/mcp-servers" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "mcp_2b8e41",
    "name": "crm",
    "url": "https://mcp.example.com/mcp",
    "transport": "streamable_http",
    "auth": "bearer",
    "auth_set": true,
    "enabled": true,
    "status": "ok",
    "error": null,
    "tools_synced_at": 1793831000,
    "tools": [
      {
        "name": "find_customer",
        "description": "Find a customer by phone number.",
        "input_schema": {
          "type": "object",
          "properties": {
            "phone": {
              "type": "string"
            }
          },
          "required": [
            "phone"
          ]
        },
        "enabled": true,
        "access": "read"
      },
      {
        "name": "create_ticket",
        "description": "Open a support ticket.",
        "input_schema": {
          "type": "object",
          "properties": {
            "subject": {
              "type": "string"
            },
            "body": {
              "type": "string"
            }
          },
          "required": [
            "subject"
          ]
        },
        "enabled": false,
        "access": "write"
      }
    ]
  }
]

MCP-serveri lisamine

POST /v1/mcp-servers

Salvestab serveri ja laadib selle tööriistade loendi. Uued tööriistad on välja lülitatud. Organisatsiooni kohta kuni 10 serverit.

NimiAsukohtTüüpKirjeldus
name
kohustuslik		 body string Lühinimi; kasutatakse tööriistade nimedes eesliitena (<name>.<tool>).
url
kohustuslik		 body string Serveri MCP-otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
transport body string streamable_http (vaikimisi) või sse.
auth body string none, bearer või header.
secret body string Token või päise väärtus. Salvestatakse krüpteeritult ja seda ei tagastata kunagi; "-" eemaldab selle.
header_name body string Päise nimi, kui auth on header.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/mcp-servers" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "crm",
  "url": "https://mcp.example.com/mcp",
  "auth": "bearer",
  "secret": "sk_live_…"
}'

Vastus · 201

JSON 
{
  "id": "mcp_2b8e41",
  "name": "crm",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "auth": "bearer",
  "auth_set": true,
  "enabled": true,
  "status": "ok",
  "error": null,
  "tools_synced_at": 1793831000,
  "tools": [
    {
      "name": "find_customer",
      "description": "Find a customer by phone number.",
      "input_schema": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "phone"
        ]
      },
      "enabled": false,
      "access": "write"
    },
    {
      "name": "create_ticket",
      "description": "Open a support ticket.",
      "input_schema": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "subject"
        ]
      },
      "enabled": false,
      "access": "write"
    }
  ]
}

Vead

  • 400 URL ei ole https või viitab privaatsele aadressile või ei õnnestunud serveri tööriistade loendit laadida.
  • 409 Organisatsioonil on juba 10 MCP-serverit.

MCP-serveri muutmine

PUT /v1/mcp-servers/{id}

Muudab nime, URL-i, autentimist või seda, kas server on sisse lülitatud, ning seda, millised tööriistad on sees ja kas need on read või write. Saladuse eemaldamiseks saatke secret: "-".

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string MCP-serveri id.
name body string Lühinimi; kasutatakse tööriistade nimedes eesliitena (<name>.<tool>).
url body string Serveri MCP-otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
enabled body boolean Väljalülitatud serverit agentidele ei pakuta.
auth body string none, bearer või header.
secret body string Token või päise väärtus. Salvestatakse krüpteeritult ja seda ei tagastata kunagi; "-" eemaldab selle.
tools body object[] [{name, enabled, access}] iga tööriista kohta; access on read või write.

Päring

curl 
curl -X PUT "https://hubvocal.com/v1/mcp-servers/mcp_2b8e41" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tools": [
    {
      "name": "find_customer",
      "enabled": true,
      "access": "read"
    },
    {
      "name": "create_ticket",
      "enabled": true,
      "access": "write"
    }
  ]
}'

Vastus · 200

JSON 
{
  "id": "mcp_2b8e41",
  "name": "crm",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "auth": "bearer",
  "auth_set": true,
  "enabled": true,
  "status": "ok",
  "error": null,
  "tools_synced_at": 1793831000,
  "tools": [
    {
      "name": "find_customer",
      "description": "Find a customer by phone number.",
      "input_schema": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "phone"
        ]
      },
      "enabled": true,
      "access": "read"
    },
    {
      "name": "create_ticket",
      "description": "Open a support ticket.",
      "input_schema": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "subject"
        ]
      },
      "enabled": true,
      "access": "write"
    }
  ]
}

Vead

  • 400 URL ei ole https või viitab privaatsele aadressile või ei õnnestunud serveri tööriistade loendit laadida.
  • 404 Selle id-ga MCP-serverit pole.

MCP-serveri kustutamine

DELETE /v1/mcp-servers/{id}

Kustutab serveri ja eemaldab selle tööriistad kõigilt agentidelt.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string MCP-serveri id.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/mcp-servers/mcp_2b8e41" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "mcp_2b8e41"
}

Vead

  • 404 Selle id-ga MCP-serverit pole.

Tööriistade sünkroonimine

POST /v1/mcp-servers/{id}/sync

Laadib tööriistade loendi uuesti. Uued tööriistad on välja lülitatud ja nende juurdepääs on write.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string MCP-serveri id.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/mcp-servers/mcp_2b8e41/sync" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "id": "mcp_2b8e41",
  "name": "crm",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "auth": "bearer",
  "auth_set": true,
  "enabled": true,
  "status": "ok",
  "error": null,
  "tools_synced_at": 1793831000,
  "tools": [
    {
      "name": "find_customer",
      "description": "Find a customer by phone number.",
      "input_schema": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "phone"
        ]
      },
      "enabled": true,
      "access": "read"
    },
    {
      "name": "create_ticket",
      "description": "Open a support ticket.",
      "input_schema": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "subject"
        ]
      },
      "enabled": false,
      "access": "write"
    }
  ]
}

Vead

  • 400 URL ei ole https või viitab privaatsele aadressile või ei õnnestunud serveri tööriistade loendit laadida.
  • 404 Selle id-ga MCP-serverit pole.

Tööriista testimine

POST /v1/mcp-servers/{id}/test

Kutsub serveris välja ühe tööriista teie antud argumentidega ning tagastab kulunud aja, kuni 4 KB sisu ja selle, kas tööriist teatas veast.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string MCP-serveri id.
tool
kohustuslik		 body string Väljakutsutava tööriista nimi.
arguments body object Tööriista argumendid, mis vastavad selle input_schema-le.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/mcp-servers/mcp_2b8e41/test" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tool": "find_customer",
  "arguments": {
    "phone": "+905321234567"
  }
}'

Vastus · 200

JSON 
{
  "ok": true,
  "ms": 236,
  "content": "{\"customer_id\":\"C-1042\",\"name\":\"Ayşe Yılmaz\",\"open_tickets\":0}",
  "is_error": false
}

Vead

  • 404 Selle id-ga MCP-serverit pole.

Webhookid

Webhookide loend

GET /v1/webhooks

Teie organisatsiooni webhookid koos viimase edastuse tulemusega. Saladust siin kunagi ei tagastata; secret_set näitab, kas see on määratud.

Päring

curl 
curl "https://hubvocal.com/v1/webhooks" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "wh_3c9d1e",
    "url": "https://crm.example.com/hooks/voice",
    "events": [
      "call.ended"
    ],
    "enabled": true,
    "secret_set": true,
    "created_at": 1793830000,
    "last_delivery": {
      "status": "ok",
      "at": 1793832440.2,
      "http_status": 200
    }
  }
]

Webhooki loomine

POST /v1/webhooks

Tellib URL-ile sündmused. Praegu on ainus sündmus call.ended. Kuni 5 webhooki organisatsiooni kohta. Kui secret puudub, luuakse see ja tagastatakse ainult selles vastuses.

NimiAsukohtTüüpKirjeldus
url
kohustuslik		 body string Teie otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
events
kohustuslik		 body string[] Sündmused, mida vastu võtta. Praegu ["call.ended"].
enabled body boolean Keelatud webhookid ei saa midagi.
secret body string Allkirjastamise saladus. Kui puudub, luuakse automaatselt; tagastatakse ainult üks kord.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/webhooks" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.example.com/hooks/voice",
  "events": [
    "call.ended"
  ]
}'

Vastus · 201

JSON 
{
  "id": "wh_3c9d1e",
  "url": "https://crm.example.com/hooks/voice",
  "events": [
    "call.ended"
  ],
  "enabled": true,
  "secret_set": true,
  "created_at": 1793830000,
  "last_delivery": null,
  "secret": "whsec_9QmZ…"
}

Vead

  • 400 URL ei ole https, osutab privaatsele aadressile või mõni sündmus on tundmatu.
  • 409 Organisatsioonil on juba 5 webhooki.

Webhooki muutmine

PUT /v1/webhooks/{id}

Muudab URL-i, sündmusi või seda, kas webhook on lubatud. Saatke secret: "-", et luua uus saladus; see tagastatakse vastuses.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Webhooki id.
url body string Teie otspunkt. Ainult https; kohalikud ja privaatsed aadressid lükatakse tagasi.
events body string[] Sündmused, mida vastu võtta. Praegu ["call.ended"].
enabled body boolean Keelatud webhookid ei saa midagi.
secret body string "-" loob uue saladuse. Jätke väli ära, et praegune alles jätta.

Päring

curl 
curl -X PUT "https://hubvocal.com/v1/webhooks/wh_3c9d1e" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": false
}'

Vastus · 200

JSON 
{
  "id": "wh_3c9d1e",
  "url": "https://crm.example.com/hooks/voice",
  "events": [
    "call.ended"
  ],
  "enabled": false,
  "secret_set": true,
  "created_at": 1793830000,
  "last_delivery": {
    "status": "ok",
    "at": 1793832440.2,
    "http_status": 200
  }
}

Vead

  • 400 URL ei ole https, osutab privaatsele aadressile või mõni sündmus on tundmatu.
  • 404 Selle id-ga webhooki pole.

Webhooki kustutamine

DELETE /v1/webhooks/{id}

Kustutab webhooki. Ootel edastused tühistatakse.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Webhooki id.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/webhooks/wh_3c9d1e" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "wh_3c9d1e"
}

Vead

  • 404 Selle id-ga webhooki pole.

Webhooki testimine

POST /v1/webhooks/{id}/test

Saadab URL-ile näidissündmuse call.ended ning tagastab oleku, ajakulu ja vastuse sisu.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Webhooki id.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/webhooks/wh_3c9d1e/test" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "ok": true,
  "http_status": 200,
  "ms": 184,
  "body": "{\"received\":true}"
}

Vead

  • 404 Selle id-ga webhooki pole.

Edastuste loend

GET /v1/webhooks/{id}/deliveries

Webhooki viimased 50 edastust, uusimad eespool: olek (pending, ok, failed), katsete arv, HTTP-olek, viga ja järgmise katse aeg.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Webhooki id.

Päring

curl 
curl "https://hubvocal.com/v1/webhooks/wh_3c9d1e/deliveries" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "id": "dl_51b7a9",
    "event": "call.ended",
    "call_id": "demo-8585522d",
    "status": "ok",
    "attempts": 1,
    "http_status": 200,
    "error": null,
    "created_at": 1793832440.2,
    "next_attempt_at": null
  },
  {
    "id": "dl_51a3c4",
    "event": "call.ended",
    "call_id": "tel-6b1f04d2",
    "status": "pending",
    "attempts": 2,
    "http_status": 503,
    "error": "HTTP 503",
    "created_at": 1793832101.7,
    "next_attempt_at": 1793833901.7
  }
]

Vead

  • 404 Selle id-ga webhooki pole.

Edastuse kordamine

POST /v1/webhooks/deliveries/{id}/retry

Paneb ebaõnnestunud edastuse uuesti järjekorda.

NimiAsukohtTüüpKirjeldus
id
kohustuslik		 path string Edastuse id edastuste loendist.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/webhooks/deliveries/dl_51a3c4/retry" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "ok": true
}

Vead

  • 404 Selle id-ga edastust pole või see pole ebaõnnestunud.

Hääled ja mootorid

Mootorite, häälte ja piirangute loend

GET /v1/voices

Kõik, mida agendi vormi jaoks vaja: mootorite nimed, iga mootori lubatud hääled, kiirusvahemikud, keeled, tooni eelseadistused, iga mootori taga olev mudel ja väljade pikkuspiirangud. Allolev näide on lühendatud.

Päring

curl 
curl "https://hubvocal.com/v1/voices" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "engines": {
    "live": "GPT-Live 1 (OpenAI full-duplex ses modeli)",
    "gemini": "Gemini Live (Google ses-sese model)",
    "realtime": "Realtime (OpenAI ses-sese model)",
    "classic": "Klasik (Deepgram + OpenAI LLM + OpenAI TTS)"
  },
  "voices": {
    "live": [
      "marin",
      "cedar",
      "gleam",
      "meridian"
    ],
    "gemini": [
      "Kore",
      "Aoede",
      "Charon",
      "Puck"
    ],
    "realtime": [
      "marin",
      "cedar",
      "alloy"
    ],
    "classic": [
      "alloy",
      "coral",
      "sage"
    ]
  },
  "speed": {
    "live": {
      "min": 1,
      "max": 1
    },
    "gemini": {
      "min": 1,
      "max": 1
    },
    "realtime": {
      "min": 0.25,
      "max": 1.5
    },
    "classic": {
      "min": 0.25,
      "max": 4
    }
  },
  "langs": {
    "tr": "Türkçe",
    "en": "English"
  },
  "presets": [
    {
      "id": "calm",
      "label": "Sakin ve güven veren",
      "text": "Sakin, yumuşak ve güven veren bir tonla konuş."
    }
  ],
  "models": {
    "live": {
      "model": "gpt-live-1",
      "backend": "gpt-5.6-luna"
    },
    "gemini": {
      "model": "gemini-3.8-live",
      "ready": true
    },
    "realtime": {
      "model": "gpt-realtime-2.1-mini"
    },
    "classic": {
      "stt": "nova-3",
      "llm": "gpt-4.1-mini",
      "tts": "gpt-4o-mini-tts"
    }
  },
  "limits": {
    "tone": 600,
    "instructions": 8000,
    "greeting": 400
  }
}

Kõned

Säilitusaeg määratakse organisatsiooni kaupa juhtpaneelis: recordings_days (vaikimisi 30), transcripts_days (vaikimisi 365) ja pii_redaction. Igapäevane töö kustutab aegunud salvestised ja ärakirjad; kõne rida ja selle kulu jäävad alles.

Veebividin: avalikud võtmed (pk_…) luuakse juhtpaneelis iga agendi jaoks eraldi. Vidina skript kutsub välja POST /api/public/web-calls; vt juhendit lehel „Arendajale“.

Veebikõne alustamine

POST /v1/web-calls

Avab brauserikõne jaoks ruumi ja tagastab lühiajalise ligipääsutokeni. Andke server_url ja token brauseris teegile livekit-client; agent liitub ruumiga ise. Kutsuge seda oma serverist, et API-võti ei jõuaks kunagi brauserisse. agent_id asemel võite saata terve agent objekti, et proovida mustandit ilma salvestamata.

NimiAsukohtTüüpKirjeldus
agent_id body string Salvestatud agendi id. Kohustuslik, kui agent pole saadetud.
agent body object Terve agendi objekt (samad väljad mis POST /v1/agents), mida kasutatakse ainult selle kõne jaoks.
version body string | integer Kasutatav versioon: "live" (vaikimisi), "draft" või versiooni number.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/web-calls" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "front-desk"
}'

Vastus · 200

JSON 
{
  "server_url": "wss://hubvocal.com",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "room": "demo-3f9a1c2e",
  "max_seconds": 300
}

Vead

  • 400 Ei saadetud agent_id ega agent välja.
  • 402 Organisatsioon on jõudnud kuu kululimiidini.
  • 403 Organisatsioon on peatatud.
  • 404 Selle id-ga agenti pole.

Väljuva telefonikõne tegemine

POST /v1/calls

Helistab telefoninumbrile mõnelt teie organisatsiooni numbrilt ja ühendab agendi, kui kõnele vastatakse. Teenusepakkuja (DIDWW, Twilio või teie oma SIP-trunk) valitakse from numbri järgi.

NimiAsukohtTüüpKirjeldus
from
kohustuslik		 body string Üks teie organisatsiooni numbritest, E.164 vormingus (+90…).
to
kohustuslik		 body string Number, millele helistada, E.164 vormingus.
agent_id body string Kasutatav agent. Kui puudub, vastab from numbrile määratud agent.
version body string | integer Kasutatav versioon: "live" (vaikimisi), "draft" või versiooni number.

Päring

curl 
curl -X POST "https://hubvocal.com/v1/calls" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "+908501234567",
  "to": "+905321234567",
  "agent_id": "front-desk"
}'

Vastus · 200

JSON 
{
  "room": "tel-out-9c41e0b7",
  "provider": "didww",
  "sip_call_id": "SCL_7mVt2kQb9xRa"
}

Vead

  • 400 Number pole rahvusvahelises vormingus või from ei ole teie number.
  • 402 Organisatsioon on jõudnud kuu kululimiidini.
  • 502 Telefoniteenuse pakkuja lükkas kõne tagasi.

Kõnede loend

GET /v1/calls

Kõned uusimast vanimani, nii veebi- kui ka telefonikõned. quality on brauseripoolsete mõõtmiste kokkuvõte ja telefonikõnede puhul null. ended_by on caller, agent, max_call_seconds, caller_unresponsive, agent_unresponsive, no_answer või unknown. channel on web, phone_in või phone_out. Igal real on ka outcome ja summary_text (kokkuvõtte esimesed 160 märki). ended_by on supervisor, kui kõne lõpetas meeskonnajuht reaalajakonsoolist.

NimiAsukohtTüüpKirjeldus
limit query integer Vaikimisi 50, maksimaalselt 500.
agent query string Ainult selle agendi kõned (agendi nimi).
outcome query string Ainult selle tulemusega kõned.

Päring

curl 
curl "https://hubvocal.com/v1/calls?limit=20" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
[
  {
    "room": "demo-8585522d",
    "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
    "org_name": "Example Clinic",
    "channel": "web",
    "profile": "Front desk",
    "engine": "live",
    "lang": "en",
    "voice": "marin",
    "started_at": 1793832409.1,
    "ended_at": 1793832434.2,
    "duration_s": 25.1,
    "total_usd": 0.021215,
    "ended_by": "caller",
    "outcome": "message_taken",
    "summary_text": "The caller asked for an appointment on Thursday afternoon; a message was taken for a callback.",
    "extracted": {
      "appointment_date": "2026-11-12",
      "callback": true
    },
    "first_audio_s": 2.43,
    "turns": 4,
    "source_gaps": {
      "count": 0,
      "total_ms": 0,
      "max_ms": 0
    },
    "quality": {
      "verdict": "Clean: no loss, no gaps.",
      "protocol": "UDP",
      "loss_pct": 0,
      "conceal_pct": 0,
      "jitter_ms": 4,
      "rtt_ms": 38
    }
  }
]

Kõne pärimine

GET /v1/calls/{room}

Kõne täielik kirje: kulude jaotus teenusepakkujate kaupa, ärakiri, tervituse ajastus, agendipoolsed lüngad ja brauseri kvaliteedi ajatelg 2-sekundiliste akendena. Kuluväljad sõltuvad mootorist (live, llm, stt, tts, realtime…); igaühes on usd. source_gaps.events sisaldab paare [sekund, ms]. summary sisaldab välju text, outcome (resolved, message_taken, transferred, unresolved, no_conversation, spam), sentiment, topics ja action_items. supervisors näitab, kes reaalajakonsoolist kõnega liitusid ja millistes režiimides. recording sisaldab välju available, duration_s ja size_bytes. extracted sisaldab agendi post_call.fields väärtusi (null, kui väärtust ei mainitud).

NimiAsukohtTüüpKirjeldus
room
kohustuslik		 path string Ruumi nimi kõnede loendist või POST /v1/web-calls vastusest.

Päring

curl 
curl "https://hubvocal.com/v1/calls/demo-8585522d" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "call": {
    "room": "demo-8585522d",
    "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
    "org_name": "Example Clinic",
    "channel": "web",
    "profile": "Front desk",
    "engine": "live",
    "lang": "en",
    "voice": "marin",
    "started_at": 1793832409.1,
    "ended_at": 1793832434.2,
    "duration_s": 25.1,
    "total_usd": 0.021215,
    "ended_by": "caller",
    "outcome": "message_taken",
    "summary_text": "The caller asked for an appointment on Thursday afternoon; a message was taken for a callback.",
    "extracted": {
      "appointment_date": "2026-11-12",
      "callback": true
    },
    "first_audio_s": 2.43,
    "turns": 4,
    "source_gaps": {
      "count": 2,
      "total_ms": 230,
      "max_ms": 141,
      "agent_audio_s": 31.2,
      "events": [
        [
          16.4,
          141
        ],
        [
          40.1,
          89
        ]
      ]
    },
    "quality": {
      "verdict": "Clean: no loss, no gaps.",
      "protocol": "UDP",
      "loss_pct": 0,
      "conceal_pct": 0,
      "jitter_ms": 4,
      "rtt_ms": 38
    },
    "cost": {
      "live": {
        "billed_s": 25.1,
        "reported": true,
        "voice_usd": 0.020917,
        "backend": {
          "in": 1840,
          "cached": 1024,
          "out": 96
        },
        "backend_usd": 0.000298
      },
      "llm": {
        "input_tokens": 1840,
        "cached_tokens": 1024,
        "output_tokens": 96,
        "usd": 0.000298
      },
      "tts": {
        "input_tokens": 0,
        "audio_tokens": 0,
        "audio_s": 25.1,
        "usd": 0.020917
      },
      "stt": {
        "audio_s": 0,
        "usd": 0
      }
    },
    "tools": [
      {
        "t": 14.2,
        "name": "check_order",
        "kind": "read",
        "ok": true,
        "ms": 412,
        "status": 200
      }
    ],
    "outcomes": [],
    "summary": {
      "text": "The caller asked for an appointment on Thursday afternoon; a message was taken for a callback.",
      "language": "en",
      "outcome": "message_taken",
      "sentiment": "neutral",
      "topics": [
        "appointment"
      ],
      "action_items": [
        "Call the caller back on Thursday morning"
      ]
    },
    "recording": {
      "available": true,
      "duration_s": 25.1,
      "size_bytes": 201344
    },
    "supervisors": [
      {
        "user": "ayse@example.com",
        "joined_at": 1793832420.4,
        "left_at": 1793832431,
        "modes": [
          "listen",
          "whisper"
        ]
      }
    ],
    "greeting": {
      "connect_s": 0.15,
      "session_started_s": 0.05,
      "reply_requested_s": 0.05,
      "first_audio_s": 2.4,
      "reply_done_s": 7.1
    },
    "transcript": [
      {
        "role": "assistant",
        "text": "Hello, thanks for calling the clinic. How can I help you today?",
        "t": 2.4,
        "interrupted": false
      },
      {
        "role": "user",
        "text": "I would like an appointment on Thursday afternoon.",
        "t": 9.8
      }
    ]
  },
  "quality": {
    "summary": {
      "verdict": "Clean: no loss, no gaps.",
      "protocol": "UDP",
      "rtt_ms": 38,
      "protocols_seen": [
        "UDP"
      ],
      "loss_pct": 0,
      "conceal_pct": 0,
      "jitter_ms": 4,
      "buffer_ms": 62
    },
    "timeline": [
      {
        "t": 2,
        "loss": 0,
        "conceal": 0,
        "jitter": 3,
        "buffer": 60,
        "proto": "UDP"
      },
      {
        "t": 4,
        "loss": 0,
        "conceal": 0,
        "jitter": 4,
        "buffer": 62,
        "proto": "UDP"
      }
    ]
  }
}

Vead

  • 404 Kõnet ei leitud.

Salvestise allalaadimine

GET /v1/calls/{room}/recording

Kõne heli OGG/Opus-vormingus. Toetab Range-päringuid. 404, kui kõnet ei salvestatud või salvestise säilitusaeg on möödas.

NimiAsukohtTüüpKirjeldus
room
kohustuslik		 path string Ruumi nimi kõnede loendist või POST /v1/web-calls vastusest.

Päring

curl 
curl "https://hubvocal.com/v1/calls/demo-8585522d/recording" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -o call.ogg

Vastus · 200

audio/ogg 
HTTP/1.1 200 OK
Content-Type: audio/ogg
Accept-Ranges: bytes
Content-Length: 201344

<OGG/Opus>

Vead

  • 404 Kõnet ei salvestatud või salvestise säilitusaeg on möödas.

Kõne kustutamine

DELETE /v1/calls/{room}

Kustutab kohe kõne salvestise, ärakirja ja kokkuvõtte, näiteks KVKK või GDPR alusel esitatud taotluse korral. Kõne rida ja selle kulu jäävad alles.

NimiAsukohtTüüpKirjeldus
room
kohustuslik		 path string Ruumi nimi kõnede loendist või POST /v1/web-calls vastusest.

Päring

curl 
curl -X DELETE "https://hubvocal.com/v1/calls/demo-8585522d" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "deleted": "demo-8585522d"
}

Vead

  • 404 Kõnet ei leitud.

Kõnede eksport (CSV)

GET /v1/calls/export

Valitud ajavahemiku kõned CSV-vormingus, üks rida kõne kohta; struktureeritud väljad on lisaveergudena.

NimiAsukohtTüüpKirjeldus
format
kohustuslik		 query string Ainult csv.
from query date YYYY-MM-DD, kaasa arvatud.
to query date YYYY-MM-DD, kaasa arvatud.
agent_id query string Ainult selle agendi kõned.

Päring

curl 
curl "https://hubvocal.com/v1/calls/export?format=csv&from=2026-11-01&to=2026-11-05" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -o calls.csv

Vastus · 200

text/csv 
room,started_at,agent,channel,duration_s,total_usd,outcome,appointment_date,callback
demo-8585522d,2026-11-05T09:46:49Z,front-desk,web,25.1,0.021215,message_taken,2026-11-12,true

Telefoninumbrid

Telefoninumbrite loend

GET /v1/numbers

Teie organisatsiooni telefoninumbrid ja agent, kes igale neist vastab (profile_id), ning iga telefoniteenuse pakkuja valmisolek. Numbrid lisab platvormi meeskond; agendid määrate teie.

Päring

curl 
curl "https://hubvocal.com/v1/numbers" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "numbers": [
    {
      "number": "+908501234567",
      "provider": "didww",
      "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
      "org_name": "Example Clinic",
      "profile_id": "front-desk",
      "label": "Main line"
    }
  ],
  "sip": {
    "enabled": true,
    "room_prefix": "tel-",
    "providers": {
      "didww": {
        "inbound_ips": "46.19.209.14,46.19.210.14",
        "inbound_auth": false,
        "outbound_host": "trunk.example.com",
        "outbound_auth": true,
        "outbound_ready": true,
        "inbound_ready": true
      }
    }
  }
}

Agendi määramine numbrile

PUT /v1/numbers/{number}

Valib agendi, kes vastab sellele numbrile saabuvatele kõnedele. Määrangu eemaldamiseks saatke agent_id: null. Kodeerige numbri + tees kujul %2B (sobib ka eesliide 00).

NimiAsukohtTüüpKirjeldus
number
kohustuslik		 path string Number E.164 vormingus, URL-kodeeritud.
agent_id body string | null Agent, kes vastab sissetulevatele kõnedele.
label body string Märkus teie meeskonnale, kuni 60 märki.

Päring

curl 
curl -X PUT "https://hubvocal.com/v1/numbers/%2B908501234567" \
  -H "Authorization: Bearer $VT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "front-desk",
  "label": "Main line"
}'

Vastus · 200

JSON 
{
  "ok": true
}

Vead

  • 400 Sellist agenti pole.
  • 404 Number ei kuulu teie organisatsioonile.

Kasutus

Kasutus

GET /v1/usage

Teie organisatsiooni kõned, minutid ja teenusepakkujate kulu teenusepakkujate ja päevade kaupa (Europe/Istanbul). Vaikimisi jooksev kuu. kind on llm, tts, stt või voice (kõnest kõnesse mootorid).

NimiAsukohtTüüpKirjeldus
from query date YYYY-MM-DD, kaasa arvatud.
to query date YYYY-MM-DD, kaasa arvatud.

Päring

curl 
curl "https://hubvocal.com/v1/usage?from=2026-11-01&to=2026-11-05" \
  -H "Authorization: Bearer $VT_API_KEY"

Vastus · 200

JSON 
{
  "from": "2026-11-01",
  "to": "2026-11-05",
  "totals": {
    "calls": 42,
    "minutes": 81.2,
    "usd": 3.94
  },
  "by_provider": [
    {
      "provider": "openai",
      "model": "gpt-live-1",
      "kind": "voice",
      "calls": 30,
      "input_tokens": 0,
      "cached_tokens": 0,
      "output_tokens": 0,
      "audio_s": 2900.1,
      "usd": 2.41
    }
  ],
  "by_day": [
    {
      "date": "2026-11-05",
      "usd": 1.2,
      "minutes": 20.5,
      "calls": 9
    }
  ],
  "by_org": [
    {
      "org_id": "6f1c2a40-3b7e-4d0c-9a51-2f8e7c1d9b03",
      "org_name": "Example Clinic",
      "usd": 3.94,
      "minutes": 81.2,
      "calls": 42
    }
  ]
}

Spetsifikatsioon

OpenAPI spetsifikatsioon

GET /v1/openapi.json Võtit pole vaja

Selle API OpenAPI 3.1 dokument. Võtit pole vaja. Importige see Postmani, Insomniasse või klientide generaatorisse.

Päring

curl 
curl "https://hubvocal.com/v1/openapi.json"

Vastus · 200

JSON 
{
  "openapi": "3.1.0",
  "info": {
    "title": "HubVocal API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://hubvocal.com/v1"
    }
  ],
  "paths": {}
}