API арқылы қоңыраулар: Python SDK

Орнату

Пакетті сұрау бойынша береміз. Python 3.10 немесе жаңарағы керек.

Қолдау қызметіне WhatsApp арқылы жазу · +7 771 682 74 70 · support@tehprof.kz

pip install dialogs_sdk-0.2.0-py3-none-any.whl

Бот үшін дыбыс — кез келген файл: WAV-ты SDK өзі оқиды, MP3, OGG және M4A — компьютерде ffmpeg болса.

Алғашқы бот

Бот жаңа кіріс қоңырауды алады, сәлемдеседі, клиентті тыңдайды және оны желі адамдарына береді. Клиент сәлемдесудің үстінен сөйлесе, бот үнсіз қалады.

import asyncio

import dialogs

GREETING = dialogs.load("greeting.mp3")

async def main(api: dialogs.Dialogs):
    async for event in api.calls.watch():      # секундына бір рет: не өзгерді
        if event.new_ringing:
            call = await api.calls.get(event.call_id)
            await call.accept()
            async with call.voice() as voice:
                greeting = asyncio.create_task(voice.play(GREETING))
                phrase = await voice.speech.utterance()   # клиент сөйлеп, аяқтады (немесе None)
                if not greeting.done():
                    await voice.flush()                   # сөзді бөлді — бот үнсіз қалады
            await call.transfer()                         # клиентті — желі адамдарына

dialogs.run_program(main)

# сіздің желілеріңізде
DIALOGS_KEY=gw_xxx python bot.py

# құмсалғышта
python bot.py --sandbox

SDK-дағы негізгісі

• api.calls — list, get, place, operators, watch (сұрау арқылы оқиғалар), history (бет-бетімен тарих).
• call.accept(), reject(), hangup(), transfer(), route(operator_id), behaviour() — қоңырау қорытындысы.
• call.voice() — дауыс: play нақты уақытта сөйлейді, flush бірден үнсіз қалады, async for pcm in voice — клиенттің дыбысы.
• voice.speech — клиент жағында не болып жатқаны, дыбыс бойынша, ЖИ-сіз: utterance() — клиенттің сөз тіркесі, speaking, interrupting — клиент сөзді бөледі, knocks() — тықылдату.
• Клиенттің дыбысы бірқалыпты келеді: бір бөлігі жолда жоғалса, SDK бос орынды толтырады, сөз тіркестері үзілмейді.
• Вебхуктан: dialogs.verify(raw_body, headers, secret) қолтаңбаны тексереді, dialogs.call_events(body) оқиғаларды береді.
• Кез келген бас тарту — status, code, reason бар dialogs.ApiError, қараңыз: қателер.

Құмсалғыш

dialogs.testing.Sandbox — сіздің компьютеріңіздегі TehProf Dialogs, сол API-мен. Нақты желілер мен деректерге тиіспейді.

• «Клиент» қоңырау шалып, берілген дыбысты айтады.
• Боттың айтқанының бәрі клиенттің «құлағына» жиналады — оны тексеруге болады.
• Қолтаңбалы оқиғалар нақты желілердегідей сіздің мекенжайыңызға кетеді.

from dialogs.testing import Sandbox

async with Sandbox() as sandbox:
    await sandbox.ring(says=[(500, hello_pcm)], hangs_up_after_ms=8000)
    await run_my_bot(dialogs.Dialogs(sandbox.key, base_url=sandbox.url))
    assert sandbox.heard(1)          # клиент не естіді

Шығыс қоңыраулар үшін нөмір қалай жауап беретінін көрсетіңіз: sandbox.answers(number, says=…) — тұтқаны көтеріп, сөйлейді; picks_up=False — көтермейді; refuses="contact_refuses_automation" — бірден бас тарту.

Кім жауап берді: адам немесе автожауапбергіш

voice.speech.who_answered() алғашқы секундтардың дыбысы бойынша тұтқаны кім көтергенін айтады: person, machine немесе unknown, ал reason ішінде — қай белгі бойынша.

voice.speech.beep_end() автожауапбергіш сигналының аяқталуын күтеді: одан кейін бағдарлама хабарлама қалдырады.

call = await api.calls.place(line, number)
while (await call.refresh()).phase not in {"active", "ended"} and call.active:
    await asyncio.sleep(0.1)
async with call.voice() as voice:
    answer = await voice.speech.who_answered()
    if answer.machine and await voice.speech.beep_end():
        await voice.play(MESSAGE)          # автожауапбергіш сигналдан кейін жазады
    elif answer.person:
        await voice.play(HELLO)

Сөзсіз жауаптар және естілуді тексеру

• ask_yes_no(voice, QUESTION) — «иә» немесе «жоқ» кез келген тәсілмен: айту, жоғары немесе төмен ыңылдау, бір немесе екі рет тықылдату, ысқыру. Клиент нашар естілсе, сіздің «қаттырақ жауап беріңіз» жазбаңыз ойнайды.
• dialogs.gestures — жоғары немесе төмен ыңылдау (hum_answer), ысқыру (whistle), сөз тіркесі соңының интонациясы (intonation: rising, falling, level).
• dialogs.soundcheck.SoundCheck — бүкіл қоңырау бойы клиенттің естілуін бақылайды: quiet — тыныш, choppy — байланыс үзіледі, noisy — шулы, clipped — асқын жүктеме.
• dialogs.Scene — қоңырау кезінде клиент жағында не бар: гудоктар, күту музыкасы, дауыстық мәзір, құрылғы, дауыс немесе фонның ауысуы.
• call.voice(whisper=True) — voice.speech сыбырды да естиді.

Дайын сценарийлер

• confirm, confirm_all — растау қоңыраулары: «келесіз — бірдеңе айтыңыз, жоқ — үндемеңіз». Нәтиже: confirmed, declined, machine, no_answer, refused және басқалар.
• survey, ask_rating — тықылдатумен 1-ден 5-ке дейін бағалау.
• after_hours, take_voicemail — жұмыстан тыс уақытта бот қоңырауды алып, хабарламаны WAV-қа жазады.
• WaitingLine — музыкалы кезек: кезектегі орын, адамдарға беру, тықылдатумен немесе дауыспен «маған қайта шалыңыз».
• missed_callbacks, call_back — жауап күтпей кеткендерге қайта шалу.

Дайын мысалдар

Пакетте дайын боттар бар, әрқайсысы --sandbox арқылы іске қосылады:

• жауап беріп, клиентті адамдарға беретін бот;
• хабарлама жазатын жұмыстан тыс уақыт;
• еске салу және растау қоңыраулары;
• музыкалы кезек;
• жауап берілмегендерге қайта шалу;
• алдымен сіздің CRM-дегі клиент менеджеріне түсетін қоңырау.