Звонки через API: SDK на Python

Установка

Пакет выдаём по запросу. Нужен 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) даёт события.
• Любой отказ — dialogs.ApiError с status, code, reason, см. ошибки.

Песочница

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.