VoiceToAI
Գլխավոր
Ինտեգրման ուղեցույց

VoiceToAI ինտեգրման ուղեցույց

Այս էջը նկարագրում է, թե ինչպես միացնել VoiceToAI-ը ձեր համակարգերին՝ աուդիո վերբեռնելու, տրանսկրիպտ ստանալու, AI գործակալներ օգտագործելու և սեփական chat ինտեգրում կառուցելու համար։

Գործող API հասցե

https://api.voicetoai.am

Աուդիո ինտեգրման endpoint-ները գործում են։
Chat API բանալիները և session-ները գործում են։
Chat պատասխանները գալիս են հոսքային ձևով։

Ընդհանուր նկարագիր

Ինչի համար է այս ուղեցույցը

Ուղեցույցը նախատեսված է այն թիմերի համար, որոնք ուզում են VoiceToAI-ը կապել իրենց կայքին, CRM-ին, աջակցության համակարգին, հեռախոսային հավելվածին կամ սերվերային աշխատանքային հոսքին։

Աուդիո վերբեռնում

Վերբեռնեք ձայնագրություններ API-ով և թողեք, որ հարթակը ստեղծի տրանսկրիպտ, ամփոփում և տրամադրության վերլուծություն։

Տրանսկրիպտների ստացում

Հարցրեք աշխատանքի կարգավիճակը, ստացեք պատրաստ տրանսկրիպտը, բանախոսների նշումները և հատվածները։

AI գործակալներ

Կառավարեք բիզնեսի գիտելիքը, ապրանքների կատալոգը և խոսակցությունները, որոնք գործակալը օգտագործում է պատասխանելիս։

Սեփական ինտեգրում

Միացրեք նույն AI գործակալը ձեր կայքին կամ սերվերային համակարգին Chat API-ով։

Նույնականացում

Ո՞ր մուտքի մեխանիզմը որտեղ է օգտագործվում

Աուդիո ինտեգրումը՝ Cognito JWT կամ secret բանալի

Վահանակի (per-user) հոսքը օգտագործում է Cognito JWT՝ /integrations/transcriptions/*endpoint-ներով։ Սերվեր-սերվեր ինտեգրման համար նույն sk_live_/sk_test_բանալիները աշխատում են /v1/integrations/transcriptions/* endpoint-ներով, և օգտագործման րոպեները հաշվարկվում են enterprise-ի ընդհանուր սահմանից (ոչ թե առանձին օգտատիրոջ)։

Գործում է

Cognito JWT

Օգտագործվում է վահանակի և աուդիո տեքստավորման ինտեգրման endpoint-ների համար։

Authorization: Bearer <cognito-id-token>
Գործում է

Chat API secret բանալի

Ստեղծվում է վահանակի API ինտեգրում էջում և պահվում է միայն ձեր սերվերային համակարգում։

Authorization: Bearer sk_live_...
Գործում է

Աուդիո վերբեռնում (server-to-server բանալի)

Նույն sk_live_/sk_test_ բանալին աուդիո վերբեռնման /v1/integrations/transcriptions/* endpoint-ների համար։ Րոպեները հաշվարկվում են enterprise-ի ընդհանուր pool-ից, ոչ թե առանձին օգտատիրոջ։

Authorization: Bearer sk_live_...
Գործում է

Կարճաժամկետ session token

Բրաուզերից chat օգտագործելու համար սերվերը ստեղծում է cst_ token, որը կապված է կոնկրետ խոսակցության և origin-ի հետ։

Authorization: Bearer cst_...
Գործում է միացված ալիքների համար

Մեսենջերների կապեր

Մեսենջերային ալիքները նույնականացվում են provider webhook/token հոսքով, ոչ թե public browser key-ով։

Provider webhook + encrypted channel token

Աուդիո վերբեռնում

Աուդիո վերբեռնման հոսք

  1. 1Նույնականացեք Cognito JWT-ով (վահանակ) կամ sk_live_/sk_test_ բանալիով՝ սերվեր-սերվեր ինտեգրման համար (/v1 նախածանցով endpoint-ներ)։
  2. 2Ստեղծեք presigned վերբեռնում՝ POST /integrations/transcriptions/uploads հարցումով։
  3. 3Վերբեռնեք աուդիո ֆայլը ստացված uploadUrl հասցեին՝ PUT մեթոդով։
  4. 4Սկսեք տրանսկրիպտի ստեղծումը՝ POST /integrations/transcriptions/{jobId}/start հարցումով։
  5. 5Հետևեք կարգավիճակին՝ GET /integrations/transcriptions/{jobId} կամ GET /integrations/transcriptions/by-external-id/{externalCorrelationId} հարցումներով։
  6. 6Պատրաստ լինելուց հետո օգտագործեք տրանսկրիպտը VoiceToAI-ում կամ արտահանեք այն։
POST/integrations/transcriptions/uploads
Գործում է

Ստեղծում է job id և presigned վերբեռնման հղում։ Սա դեռ չի սկսում տրանսկրիպտի ստեղծումը։

PUT<uploadUrl>
Գործում է

Վերբեռնում է աուդիո ֆայլը անմիջապես object storage՝ ճշգրիտ Content-Type-ով։

POST/integrations/transcriptions/{jobId}/start
Գործում է

Ստուգում է վերբեռնված ֆայլը, պահում է օգտագործման րոպեները, ստեղծում է job-ը և հերթ դնում մշակման համար։

Վերբեռնման ստեղծում

curl -X POST "https://api.voicetoai.am/integrations/transcriptions/uploads" \
  -H "Authorization: Bearer <cognito-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "meeting.m4a",
    "fileSize": 18432000,
    "mimeType": "audio/mp4",
    "durationSeconds": 900,
    "externalCorrelationId": "crm-call-1001",
    "language": ["hy-AM"],
    "speakerCount": 2,
    "useAiFormat": true,
    "integration": {
      "system": "crm",
      "externalRecordId": "call_1001"
    }
  }'

Վերբեռնման պատասխան

{
  "status": "ok",
  "jobId": "9a0df102-6b72-4eaa-8ae3-c8fda0cce888",
  "externalCorrelationId": "crm-call-1001",
  "uploadUrl": "https://s3-presigned-url...",
  "s3Key": "user-id/2026/05/meeting-9a0df102.m4a",
  "expiresAt": "2026-05-31T10:15:00.000Z",
  "jobStatus": "upload_pending",
  "transcriptStatus": "pending",
  "evaluationStatus": "pending"
}

Ֆայլի վերբեռնում presigned հղումով

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mp4" \
  --upload-file ./meeting.m4a

Տրանսկրիպտի ստեղծման մեկնարկ

curl -X POST "https://api.voicetoai.am/integrations/transcriptions/9a0df102-6b72-4eaa-8ae3-c8fda0cce888/start" \
  -H "Authorization: Bearer <cognito-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "s3Key": "user-id/2026/05/meeting-9a0df102.m4a",
    "fileName": "meeting.m4a",
    "fileSize": 18432000,
    "mimeType": "audio/mp4",
    "durationSeconds": 900,
    "externalCorrelationId": "crm-call-1001",
    "language": ["hy-AM"],
    "speakerCount": 2,
    "useAiFormat": true
  }'

Աջակցվող աուդիո և սահմանափակումներ

Ընդունվող MIME տիպեր՝ audio/mpeg, audio/wav, audio/x-wav, audio/mp4, audio/x-m4a, audio/aac, audio/ogg, audio/webm, audio/flac։
durationSeconds-ը պետք է լինի դրական և ոչ ավելի, քան 24 ժամ։
Ֆայլի առավելագույն չափը՝ մինչև 500 ՄԲ։
Job-ը սկսելուց առաջ օգտագործման րոպեները ստուգվում են ձեր հաշվի կամ enterprise սակագնի սահմաններում։

Տրանսկրիպտներ

Տրանսկրիպտի կարգավիճակ և արդյունք

Job status-ը գալիս է հիմնական transcription lifecycle-ից՝ queued, processing, completed կամ failed։ Integration response-ը նաև տալիս է transcriptStatus՝ pending, processing, completed կամ failed։

GET/integrations/transcriptions/{jobId}
Գործում է

Ստացեք տրանսկրիպտի կարգավիճակը և վերջնական տրանսկրիպտը՝ ըստ VoiceToAI job id-ի։

GET/integrations/transcriptions/by-external-id/{externalCorrelationId}
Գործում է

Ստացեք նույն պատասխանը՝ օգտագործելով ձեր correlation id-ն։

GET/integrations/transcriptions/{jobId}/evaluations
Գործում է

Ստացեք ամփոփման և տրամադրության գնահատման կարգավիճակն ու տվյալները, երբ դրանք հասանելի են։

POST/integrations/transcriptions/{jobId}/exports
Գործում է

Ստեղծեք txt, docx, srt կամ json արտահանում՝ transcriptStatus completed դառնալուց հետո։

Տրանսկրիպտի ստացում

curl "https://api.voicetoai.am/integrations/transcriptions/9a0df102-6b72-4eaa-8ae3-c8fda0cce888" \
  -H "Authorization: Bearer <cognito-id-token>"

Պատրաստ պատասխանի կառուցվածք

{
  "status": "ok",
  "jobId": "9a0df102-6b72-4eaa-8ae3-c8fda0cce888",
  "externalCorrelationId": "crm-call-1001",
  "jobStatus": "completed",
  "transcriptStatus": "completed",
  "evaluationStatus": "completed",
  "summaryStatus": "completed",
  "sentimentStatus": "completed",
  "transcript": {
    "text": "Speaker 1: Բարեւ, սկսենք հանդիպումը...",
    "speakers": ["Speaker 1", "Speaker 2"],
    "segments": [
      {
        "speaker": "Speaker 1",
        "text": "Բարեւ, սկսենք հանդիպումը...",
        "start": 0.2,
        "end": 4.8
      }
    ]
  },
  "createdAt": "2026-05-31T09:00:00.000Z",
  "completedAt": "2026-05-31T09:04:12.000Z"
}

Հաճախ հանդիպող սխալներ

// 401
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid bearer token"
  }
}

// 413
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds 500 MB limit"
  }
}

// 400
{
  "error": {
    "code": "UPLOAD_NOT_FOUND",
    "message": "Audio file was not uploaded or is not visible yet"
  }
}

AI գործակալներ

AI գործակալների ինտեգրում

VoiceToAI-ի AI գործակալը բիզնեսի անունից պատասխանող conversation-based օգնական է։ Այն օգտագործում է enterprise-scoped settings, knowledge sources, product catalog և conversation history։ Գործակալը նախատեսված է support, sales և ներքին workflow հարցերի համար, ոչ թե ընդհանուր chatbot լինելու։

Գիտելիքի աղբյուրներ

FAQ, policies, կայքի բովանդակություն կամ raw text կարող են ingest լինել embedding/RAG որոնման համար։

Ապրանքների կատալոգ

Ապրանքների SKU, անուն, նկարագրություն, գին, currency և stock դաշտերը հասանելի են agent tools-ին։

Խոսակցություններ

Յուրաքանչյուր channel պահում է conversation և message history, որպեսզի հաջորդ պատասխանները ունենան context։

Մեսենջերային ինտեգրումներ

Messaging ալիքներում webhook-ը ընդունում է customer message-ը, conversation-ը կապում է տվյալ business-ին, գործարկում է նույն agent orchestrator-ը և պատասխանը հետ է ուղարկում provider-ի token-ով։ Սա հարմար է customer support և business assistant use case-երի համար։

Chat API

Սեփական AI գործակալի ինտեգրում

Headless Chat API-ն նախատեսված է, որ բիզնեսը նույն AI գործակալը միացնի իր կայքին, app-ին կամ backend-ին։ Սա live API է՝ secret key + short-lived session token մոդելով։

  1. 1Հաճախորդի backend-ը պահում է sk_live_ secret բանալին։ Այն երբեք չպետք է հայտնվի browser-ի կոդում։
  2. 2Backend-ը secret բանալիով կանչում է POST /v1/chat/sessions։
  3. 3VoiceToAI-ը enterprise/account-ը որոշում է բանալու գրառումից, ոչ թե հարցման body-ից։
  4. 4Հարթակը ստեղծում կամ վերսկսում է web խոսակցությունը և վերադարձնում կարճաժամկետ cst_ session token։
  5. 5Browser-ը կամ backend-ը հաղորդագրությունները ուղարկում է հոսքային chat endpoint-ին։
  6. 6Հարթակը գործարկում է առկա AI գործակալը՝ տվյալ խոսակցության համատեքստով։
  7. 7Օգնականի պատասխանը հոսքով փոխանցվում է SSE-ով և պահվում որպես խոսակցության հաղորդագրություններ։
POST/v1/chat/keys
Գործում է (միայն վահանակ)

Cognito-ով նույնականացված վահանակի endpoint՝ Chat API բանալիներ ստեղծելու, դիտելու և չեղարկելու համար։

POST/v1/chat/sessions
Գործում է

Secret-բանալիով endpoint, որը վերադարձնում է conversationId, sessionToken և expiresAt։

POST/v1/chat/messages
Գործում է (հոսքային)

Հոսքային endpoint, որը վերադարձնում է text/event-stream։

Browser-ի session token-ի ստեղծում

curl -X POST "https://api.voicetoai.am/v1/chat/sessions" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endUserId": "customer-123",
    "origin": "https://example.com"
  }'

Session-ի պատասխան

{
  "conversationId": "conv_...",
  "sessionToken": "cst_...",
  "expiresAt": "2026-05-31T10:15:00.000Z"
}

Օրինակներ

Կոդի օրինակներ

cURL՝ աուդիոյի վերբեռնում

curl -X POST "https://api.voicetoai.am/integrations/transcriptions/uploads" \
  -H "Authorization: Bearer <cognito-id-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "meeting.m4a",
    "fileSize": 18432000,
    "mimeType": "audio/mp4",
    "durationSeconds": 900,
    "externalCorrelationId": "crm-call-1001",
    "language": ["hy-AM"],
    "speakerCount": 2,
    "useAiFormat": true,
    "integration": {
      "system": "crm",
      "externalRecordId": "call_1001"
    }
  }'

cURL՝ տրանսկրիպտի ստացում

curl "https://api.voicetoai.am/integrations/transcriptions/9a0df102-6b72-4eaa-8ae3-c8fda0cce888" \
  -H "Authorization: Bearer <cognito-id-token>"

JavaScript՝ հաղորդագրության ուղարկում AI գործակալին

const session = await fetch("https://api.voicetoai.am/v1/chat/sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    endUserId: "customer-123",
    origin: "https://example.com"
  })
}).then((res) => res.json());

const response = await fetch("https://5vy6pxqwplcde6yz4dsvw7te6i0fdddv.lambda-url.us-east-1.on.aws/v1/chat/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${session.sessionToken}`,
    "Content-Type": "application/json",
    Accept: "text/event-stream"
  },
  body: JSON.stringify({ message: "Ի՞նչ սակագներ ունեք։" })
});

JavaScript՝ հոսքային պատասխանների մշակում SSE-ով

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (reader) {
  const { value, done } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  // Մշակեք Server-Sent Events հոսքը.
  // event: delta
  // data: {"text":"..."}
  renderTypingChunk(chunk);
}

Անվտանգություն

Անվտանգության կանոններ

Երբեք մի բացահայտեք secret բանալիները

sk_live_ և sk_test_ բանալիները պահեք միայն server-side-ում։ Browser-ի համար mint արեք կարճաժամկետ cst_ session token։

Tenant-ը որոշեք credentials-ից

enterprise/account id-ը պետք է որոշվի API key-ից կամ session token-ից, ոչ թե body-ից։

Կարգավորեք թույլատրված origins-ը

Browser-direct integrations-ի համար allowedOrigins-ը սահմանեք dashboard-ում, որպեսզի session token-ը աշխատի միայն ձեր domain-ից։

Կիրառեք rate limiting

Public/chat surfaces-ը պետք է պաշտպանել rate limit-ով՝ key, origin, conversation կամ end-user մակարդակով։