Skip to main content

A Simple SDK for Joker's Voice API.

Project description

JokerSDK

JokerSDK is a flexible and user-friendly Python library wrapping around Joker's Voice API.

Key Features

  • Creating outbound voice calls.
  • Playing audio/text into live calls.
  • Gathering DTMF with audio/text from live calls.
  • Transferring recipients from Leg A to Leg B.
  • Sending DTMF into a live call.

Requirements

  • Python >= 3.10

To do

  • Fix type hints.
  • Redo docs, add docs.
  • Integrate callback class.

Guide - How to install JokerSDK

JokerSDK via PyPi:

$ pip install JokerSDK

Or, if you wish to download it directly from this repository:

$ python setup.py install

JokerSDK - Usage

Create an outbound call

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "API_KEY", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

Object attributes

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "API_KEY", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

callSid = call.sid # Access the SID of the call.
retrieved = call.__retrieve__ # Boolean to check if the call has been retrieved or not.
staticStatus = call._sid # A static status indicating if the call has been terminated. This is inferred and does not reflect the actual state of the call.

Play audio into a call.

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "API_KEY", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

call.play_audio(
    audioUrl = "https://my.cdnserver.xyz/JokerSDK/audio.wav" # A web server which holds the audio file to play.
)

Play text into a call.

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "API_KEY", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

call.play_text(
    text = "This is an example phrase of in what will be presented into a live call/channel", # A phrase which JokerAPI will synthesise.
    voice = "ai3-en-US-Madison" # The voice name of in which JokerAPI will synthesise with.
)

Gathering DTMF whilst playing Audio

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "<API_KEY>", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

call.gather_dtmf_with_audio(
    audioUrl = "https://my.cdnserver.xyz/JokerSDK/audio.wav", # A web server which holds the audio file to play.
    maxDigits = 5 # The amount of digits which will be captured before calling back.
)

Gathering DTMF whilst playing Text

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "<API_KEY>", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

call.gather_dtmf_with_text(
    text = "This is an example phrase of in what will be presented into a live call/channel", # A phrase which JokerAPI will synthesise.
    voice = "ai3-en-US-Madison", # The voice name of in which JokerAPI will synthesise with.
    maxDigits = 5 # The amount of digits which will be captured before calling back.
)

Send DTMF tones

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "<API_KEY>", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

call.send_dtmf(
    input_ = "1234" # Digits to Send DTMF tones to Leg B(to) from.
)

Retrieve an session.

call = JokerAPI.client.retrieve(
    apiKey = "<API_KEY>", # Your API Key, this can be found on site.
    sid = "1234567890" # A valid identifier in which to retrieve.
)

Every object attribute & function from the retrieve class is interconnected with the create_outbound_call class.

Finally, hang up the call.

import JokerAPI

call = JokerAPI.client.create_outbound_call(
    apiKey = "<API_KEY>", # Your API Key, this can be found on site.
    to = "1234567890", # The number to call.
    from_ = "1987654321", # The number to call `to` from.
    callbackUrl = "https://my.callbackserver.xyz/JokerSDK/callbacks" # A web server to send all callbacks to.
)

Callback class demo

import JokerAPI
from flask import Flask, request


def callBacks():
    requestPayload = request.json

    if not all(requiredParameters in requestPayload for requiredParameters in ['status', 'callsid']):
        # At this point, the request is invalid/malformed.
        return "Invalid.Parameters" # You can return any value.

    call = JokerAPI.client.retrieve(apiKey = "API_KEY" sid = requestPayload['callsid'])

    match requestPayload['status']:
        case JokerAPI.callback.Enums.RINGING:
            print("The call is ringing!")

        case JokerAPI.callback.Enums.ANSWERED:
            print("The call has been answered, waiting for voicemail detection!") # Only if Voicemail detection is enabled, if not skip to detection
        
        case JokerAPI.callback.Enums.VOICEMAIL_DETECTED:
            print("The system has detected that this call is not legitimate, hanging up!")
            call.hangup()
        
        case JokerAPI.callback.Enums.HUMAN_DETECTED:
            print("The system has detected that this call is legit, we will play some text into the call!")
            call.play_text(text = "This is the text that will be presented into the call!")
        
        case JokerAPI.callback.Enums.NOTSURE_DETECTED:
            print("The system couldn't detect the integrity of this call, hanging up!")
            call.hangup()
        
        case JokerAPI.callback.Enums.DTMF_RECIEVED:
            digit = request.json['digit']
            print(f"The user[Leg(b)] has entered a DTMF digit!, Digit: {digit}")
            call.play_text(text = f"You have entered the DTMF digit {digit}")
        
        case JokerAPI.callback.Enums.DTMF_GATHERED:
            digits = request.json['digits']
            print(f"The system has gathered multiple DTMF digits!, Digit: {digits}")
            call.play_text(text = f"You have entered multiple DTMF digits {digits}")
        
        case JokerAPI.callback.Enums.HANGUP:
            print("The recipient has hung up the call.")

    return "JokerSDK/Demo"

# Create a web app server for webhooks.
server = JokerAPI.client.callback_server(
    Flask(__name__)
)

server.addCallbackEndpoint(
    callBacks
)

server.createCallbackServer()

Contributing

  • Feel free to contribute by opening issues or sending pull requests.

License

This project is licensed under the GPL-3.0 license - see the LICENSE file for details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

JokerSDK-0.0.43.tar.gz (7.0 kB view hashes)

Uploaded Source

Built Distribution

JokerSDK-0.0.43-py3-none-any.whl (9.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page