Calls by API: Python SDK

Installing

We provide the package on request. Python 3.10 or newer is needed.

Message Support on WhatsApp · +7 771 682 74 70 · support@tehprof.kz

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

The bot’s sound can be any file: the SDK reads WAV by itself, MP3, OGG and M4A — when ffmpeg is on the computer.

A first bot

The bot takes a new incoming call, says a greeting, listens to the client and hands them to the line’s people. If the client speaks over the greeting, the bot goes quiet.

import asyncio

import dialogs

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

async def main(api: dialogs.Dialogs):
    async for event in api.calls.watch():      # once a second: what changed
        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()   # the client spoke and finished (or None)
                if not greeting.done():
                    await voice.flush()                   # interrupted: the bot goes quiet
            await call.transfer()                         # the client to the line's people

dialogs.run_program(main)

# on your lines
DIALOGS_KEY=gw_xxx python bot.py

# in the sandbox
python bot.py --sandbox

The SDK in short

• api.calls — list, get, place, operators, watch (events by polling), history (history page by page).
• call.accept(), reject(), hangup(), transfer(), route(operator_id), behaviour() — the call summary.
• call.voice() — voice: play speaks in real time, flush goes quiet at once, async for pcm in voice — the client’s sound.
• voice.speech — what happens at the client’s end, from the sound, no AI: utterance() — the client’s phrase, speaking, interrupting — the client interrupts, knocks() — knocks.
• The client’s sound comes steady: when a piece is lost on the way, the SDK fills the gap and phrases do not break.
• From a webhook: dialogs.verify(raw_body, headers, secret) checks the signature, dialogs.call_events(body) gives the events.
• Any refusal is dialogs.ApiError with status, code, reason, see errors.

Sandbox

dialogs.testing.Sandbox — TehProf Dialogs on your computer, with the same API. Real lines and data are not touched.

• A «client» calls and says the sound you give.
• Everything the bot said collects in the client’s «ear» — you can check it.
• Signed events go to your address, as from real lines.

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)          # what the client heard

For outgoing calls, set how a number answers: sandbox.answers(number, says=…) — picks up and speaks; picks_up=False — does not pick up; refuses="contact_refuses_automation" — refused at once.

Who answered: a person or an answering machine

voice.speech.who_answered() tells from the sound of the first seconds who picked up: person, machine or unknown, and in reason — by which sign.

voice.speech.beep_end() waits for the machine’s beep to end: after it the program leaves a message.

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)          # the machine records after its beep
    elif answer.person:
        await voice.play(HELLO)

Answers without words and hearing check

• ask_yes_no(voice, QUESTION) — «yes» or «no» any way: say it, hum up or down, knock once or twice, whistle. If the client is hard to hear, your «please answer louder» recording plays.
• dialogs.gestures — a hum up or down (hum_answer), a whistle (whistle), the tune at the end of a phrase (intonation: rising, falling, level).
• dialogs.soundcheck.SoundCheck — watches the whole call for whether the client can be heard: quiet, choppy — the connection breaks up, noisy, clipped — overloaded.
• dialogs.Scene — what is at the client’s end during the call: tones, hold music, a voice menu, the device, a change of voice or background.
• call.voice(whisper=True) — voice.speech hears a whisper too.

Ready scenarios

• confirm, confirm_all — confirmation calls: «coming — say anything, not — stay silent». Outcomes: confirmed, declined, machine, no_answer, refused and others.
• survey, ask_rating — a rating from 1 to 5 by knocks.
• after_hours, take_voicemail — after hours the bot takes the call and records a message as WAV.
• WaitingLine — a queue with music: the place in the queue, the hand-over to people, «call me back» by a knock or by voice.
• missed_callbacks, call_back — calling back those who did not wait for an answer.

Ready examples

The package has ready bots, each runs with --sandbox:

• a bot that answers and hands the client to people;
• after hours with a recorded message;
• reminder and confirmation calls;
• a queue with music;
• calling back those nobody answered;
• a call that rings the client’s manager from your CRM first.