შესავალი

Activi Voice API საშუალებას გაძლევს შენი სისტემა (CRM, ბილინგი, ERP, ვებსაიტი) დააკავშირო სატელეფონო სისტემასთან და AI ასისტენტთან:

• შემოიტანო აბონენტების მონაცემები — სახელი, დავალიანება, გადახდის ვადა, სტატუსი ან ნებისმიერი სხვა ველი. როცა აბონენტი დარეკავს, AI ასისტენტი ამ მონაცემებს ხედავს და იყენებს საუბარში.
• გაიტანო ზარების ისტორია, AI საუბრების შეჯამებები, გამოტოვებული ზარები და ჩანაწერები.
• მართო შიდა ნომრები და წამოიწყო ზარები.
• მიიღო მოვლენები რეალურ დროში Webhook-ით.

ავტორიზაცია

API გასაღებს ქმნის კლიენტი პანელში: API → ახალი გასაღები. გასაღები ჩანს მხოლოდ ერთხელ და ინახება დაშიფრული (hash). ყოველ მოთხოვნას დაურთე header:

Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

ალტერნატივა: X-API-Key: av_.... თითოეული გასაღები ეკუთვნის ერთ კლიენტს და ხედავს მხოლოდ მის მონაცემებს.

კავშირის და გასაღების შემოწმება.

curl https://voip.activi.ge/api/v1/ping -H "Authorization: Bearer av_..."

{"ok": true, "company": "შპს ალფა", "your_ip": "185.10.20.30"}

შეცდომები და ლიმიტები

წარმატებულ პასუხს აქვს "ok": true. შეცდომისას — HTTP კოდი და {"ok": false, "error": "აღწერა"}.

ლიმიტი: 120 მოთხოვნა წუთში ერთი IP-დან (burst 60). მრავალჯერადი არასწორი გასაღები IP-ს დროებით ბლოკავს. დიდი მოცულობისთვის გამოიყენე bulk — ერთ მოთხოვნაში 5000-მდე აბონენტი.

აბონენტების შემოტანა / განახლება

ქმნის ან ანახლებს აბონენტებს ტელეფონის ნომრით (upsert). ერთ მოთხოვნაში 1–5000 ჩანაწერი. Body — სია, ან {"customers": [...]}.

curl -X POST https://voip.activi.ge/api/v1/customers \
  -H "Authorization: Bearer av_..." \
  -H "Content-Type: application/json" \
  -d '[
    {"phone": "599123456", "name": "გიორგი ბერიძე", "org": "შპს ალფა",
     "debt": 125.50, "currency": "GEL", "due_date": "2026-10-20",
     "status": "ვადაგადაცილებული", "contract": "N-4521"},
    {"phone": "577987654", "name": "ნინო კაპანაძე", "debt": 0, "status": "აქტიური"}
  ]'

{"ok": true, "created": 1, "updated": 1, "errors": []}

import requests

API = "https://voip.activi.ge/api/v1"
H = {"Authorization": "Bearer av_..."}

customers = [
    {"phone": "599123456", "name": "გიორგი ბერიძე", "debt": 125.50,
     "due_date": "2026-10-20", "status": "ვადაგადაცილებული"},
]
r = requests.post(f"{API}/customers", json=customers, headers=H, timeout=30)
r.raise_for_status()
print(r.json())   # {'ok': True, 'created': 1, 'updated': 0, 'errors': []}

<?php
$customers = [[
  "phone" => "599123456", "name" => "გიორგი ბერიძე",
  "debt" => 125.50, "due_date" => "2026-10-20", "status" => "ვადაგადაცილებული"
]];
$ch = curl_init("https://voip.activi.ge/api/v1/customers");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer av_...", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($customers, JSON_UNESCAPED_UNICODE),
]);
$res = json_decode(curl_exec($ch), true);
print_r($res);

const res = await fetch("https://voip.activi.ge/api/v1/customers", {
  method: "POST",
  headers: { "Authorization": "Bearer av_...", "Content-Type": "application/json" },
  body: JSON.stringify([
    { phone: "599123456", name: "გიორგი ბერიძე", debt: 125.5,
      due_date: "2026-10-20", status: "ვადაგადაცილებული" }
  ])
});
console.log(await res.json());

აბონენტების სია და ძებნა

curl "https://voip.activi.ge/api/v1/customers?phone=599123456" -H "Authorization: Bearer av_..."

{"ok": true, "count": 1, "customers": [{
  "phone": "599123456", "name": "გიორგი ბერიძე", "org": "შპს ალფა", "note": "",
  "data": {"debt": 125.5, "due_date": "2026-10-20", "status": "ვადაგადაცილებული"},
  "created": "2026-10-11 01:46", "updated": "2026-10-11 09:12"}]}

ერთი აბონენტი

curl -X DELETE https://voip.activi.ge/api/v1/customers/599123456 -H "Authorization: Bearer av_..."

{"ok": true, "deleted": "599123456"}

ზარების ისტორია

{"ok": true, "calls": [
  {"start": "2026-10-11 10:15:02", "from": "995599123456", "to": "s", "duration": 84, "status": "ANSWERED"}]}

status: ANSWERED, NO ANSWER, BUSY, FAILED. ბოლო 5000 ჩანაწერი.

AI ზარების ანგარიშები

ყოველი საუბარი AI ასისტენტთან — ავტომატურად ამოღებული ინფორმაციით.

{"ok": true, "ai_calls": [{
  "id": "019a...", "at": "2026-10-11 10:20", "caller": "595512180", "duration": 91,
  "name": "დიმიტრი", "client_company": "შპს ბეტა", "phone": "599127000",
  "topic": "გაყიდვები", "product": "Activi POS", "preferred_time": "ხვალ 15:00",
  "callback": true, "summary": "დიმიტრის აინტერესებს POS მაღაზიისთვის...",
  "transcript": "AI: გამარჯობა!...", "status": "new"}]}

გამოტოვებული ზარები

{"ok": true, "missed": [{"id": "a1b2c3", "did": "2424022", "from": "599123456", "at": "2026-10-11 10:31", "status": "new"}]}

ზარის წამოწყება (click-to-call)

ჯერ რეკავს შიდა ნომერს (თანამშრომლის ტელეფონს); როცა აიღებს — უკავშირდება აბონენტს. მხოლოდ საქართველოს ნომრები.

curl -X POST https://voip.activi.ge/api/v1/call -H "Authorization: Bearer av_..." -H "Content-Type: application/json" \
  -d '{"extension": "100", "to": "599123456"}'

{"ok": true, "status": "ringing", "extension": "100", "to": "599123456"}

ჩანაწერები

{"ok": true, "recordings": [{"file": "c1a2b3_20261011-101502_in_2424022_599123456.wav",
  "at": "20261011-101502", "direction": "in", "parties": ["2424022", "599123456"],
  "size": 482044, "url": "https://voip.activi.ge/api/v1/recordings/c1a2b3_20261011-101502_in_2424022_599123456.wav"}]}

ფაილის ჩამოსატვირთად იგივე Authorization header. ფორმატი: WAV, 8 kHz. შენახვის ვადა დამოკიდებულია პაკეტზე.

ანგარიში და პაკეტი

{"ok": true, "company": {"name": "შპს ალფა", "type": "company", "code": "404123456"},
 "balance": 85.40, "currency": "GEL", "ai_available": true,
 "package": {"name": "AI სტარტი", "price": 120, "status": "active", "period_end": "2026-11-10",
             "ai_minutes_included": 150, "ai_minutes_used": 42.5, "max_numbers": 1, "max_extensions": 10}}

ნომრები

{"ok": true, "numbers": [{"number": "2424022", "online": true, "mode": "ai"}]}

შიდა ნომრები

curl -X POST https://voip.activi.ge/api/v1/extensions -H "Authorization: Bearer av_..." -H "Content-Type: application/json" \
  -d '{"extension": "106", "name": "ნინო — გაყიდვები"}'

{"ok": true, "server": "voip.activi.ge", "port": 5060, "transport": "udp", "extensions": [
  {"extension": "106", "name": "ნინო — გაყიდვები", "password": "Xy7...", "online": false,
   "setup_url": "https://voip.activi.ge/p/..."}]}

setup_url — პირადი გვერდი SIP ტელეფონის (Zoiper, Linphone) დასაყენებლად. გაუგზავნე თანამშრომელს.

Webhook-ები

პანელში (API → Webhook) მიუთითე შენი HTTPS მისამართი — მოვლენისას გამოვგზავნით POST JSON-ს:

POST https://your-system.ge/activi-webhook
Content-Type: application/json
X-Activi-Signature: 5d41402abc4b2a76b9719d911017c592...

{"event": "ai_call", "company": "c1a2b3", "at": "2026-10-11T10:22:05",
 "data": {"id": "019a...", "caller": "595512180", "name": "დიმიტრი", "phone": "599127000",
          "topic": "გაყიდვები", "product": "Activi POS", "preferred_time": "ხვალ 15:00",
          "summary": "...", "duration": 91}}

ხელმოწერის შემოწმება

X-Activi-Signature = HMAC-SHA256(body, საიდუმლო), hex. საიდუმლო ჩანს პანელში Webhook-ის ქვეშ. ყოველთვის შეამოწმე — ასე დარწმუნდები, რომ მოთხოვნა ჩვენგანაა.

import hmac, hashlib
from flask import Flask, request, abort

SECRET = b"შენი_webhook_საიდუმლო"
app = Flask(__name__)

@app.post("/activi-webhook")
def hook():
    sig = hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(sig, request.headers.get("X-Activi-Signature", "")):
        abort(401)
    ev = request.get_json()
    if ev["event"] == "ai_call":
        print("ახალი ლიდი:", ev["data"]["name"], ev["data"]["phone"])
    return {"ok": True}

<?php
$secret = "შენი_webhook_საიდუმლო";
$body = file_get_contents("php://input");
$sig = hash_hmac("sha256", $body, $secret);
if (!hash_equals($sig, $_SERVER["HTTP_X_ACTIVI_SIGNATURE"] ?? "")) { http_response_code(401); exit; }
$ev = json_decode($body, true);
if ($ev["event"] === "missed_call") { /* დაურეკე უკან: $ev["data"]["from"] */ }
echo json_encode(["ok" => true]);

import crypto from "node:crypto";
import express from "express";

const SECRET = "შენი_webhook_საიდუმლო";
const app = express();
app.post("/activi-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const got = req.get("X-Activi-Signature") || "";
  if (got.length !== sig.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(got)))
    return res.sendStatus(401);
  const ev = JSON.parse(req.body);
  console.log(ev.event, ev.data);
  res.json({ ok: true });
});
app.listen(3000);

უპასუხე 2xx-ით 10 წამში. მოვლენა იგზავნება ერთხელ — თუ შენი სერვერი მიუწვდომელია, მონაცემები მაინც ხელმისაწვდომია /ai-calls და /missed-ით.

AI-სთან ინტეგრაცია

როცა აბონენტი რეკავს, AI ასისტენტი ავტომატურად ეძებს მას დამრეკავის ნომრით და იღებს /customers-ით შემოტანილ ყველა ველს. მაგალითად, თუ გაგზავნე:

{"phone": "599123456", "name": "გიორგი", "debt": 125.50, "due_date": "2026-10-20", "status": "ვადაგადაცილებული"}

და გიორგი დარეკავს, AI მიესალმება სახელით და, თუ ჰკითხავს — ეტყვის: „თქვენი დავალიანება შეადგენს 125 ლარსა და 50 თეთრს, გადახდის ვადა იყო 20 ოქტომბერი.“

• ველების სახელები თავისუფალია — AI ხვდება მნიშვნელობას. უკეთესი შედეგისთვის გამოიყენე გასაგები სახელები (debt, due_date, next_payment, tariff, balance).
• თანხები გაგზავნე რიცხვად, თარიღები — YYYY-MM-DD.
• 🔒 უსაფრთხოება: AI ეძებს მხოლოდ იმ ნომრით, საიდანაც რეკავენ — სხვის მონაცემებს ვერავინ გაიგებს, თუნდაც სხვა ნომერი დაასახელოს.
• AI საუბრის შედეგი (სახელი, თემა, შეჯამება) ბრუნდება ai_call webhook-ით და /ai-calls-ით.

Activi Voice API v1 · კითხვებისთვის დაგვიკავშირდით