phound 0.1.1

Phound SDK

Installing

pip install phound

Usage

Create and fill in .env file within your project's directory with:

PERSONS=<uid1> <uid2> ...
TOKEN=<token>

where uid1 uid2 etc. represent persons to listen. If no one specified(or omitted), all persons within an account will be listened to.

Please refer to [e-mail] to get a token

Simple python chatbot could look like:

import os
import time

from phound import Phound
from phound.handlers import BaseChatHandler
from phound.chats.text_helpers import MessageTextFormat, bold


class ChatHandler(BaseChatHandler):
    def on_message(self, message):
        print(f"Got new message: {message}")
        self.show_typing()
        time.sleep(1)
        chat_history = self.get_history(depth=5)
        reply_items = [f"{bold('Initial message:')} {message.text}",
                       f"{bold('Response:')} {message.text[::-1]}",
                       f"Also got chat history with last <u>{len(chat_history)}<u> messages"]
        self.send_message(
            os.linesep.join(reply_items),
            text_format=MessageTextFormat.HTML,
            # make sure files exists
            attachments=["./service_data/dinosaur.jpg",
                         "./service_data/apple.jpg",
                         "./service_data/guitar.mp3"],
        )


if __name__ == "__main__":
    with Phound() as phound:
        phound.register_chat_handler(ChatHandler)
        phound.start_listen_events()

API Reference

Phound

Methods:

• register_chat_handler(self, handler, chat_types=("private",)) - Registers specified chat handler.
  • handler: BaseChatHandler - The chat handler to register.
  • chat_types: Tuple[str, ...] - The chat types to handle, valid values are private and group
• start_listen_events() - Starts listen events
  
  

BaseChatHandler

• persona_uid: str - The unique ID of the persona listening to the chat.
• chat_type: str - Either "private" or "group".
• chat_id: str - The ID of the chat.

Event handlers:

• on_message(self, message) - Called when a new message is received in the chat.
  • message: Message - The message object.

Methods:

Same as for Chat object, please refer to the documentation bellow.

BaseCallHandler

• persona_uid: str - The unique ID of the persona listening to the call.
• chat: Chat - The chat object associated with the call.

Event handlers:

• on_incoming_call(self, call) - Called when an incoming call is received.
  • call: Call - The call object.
• on_call_ready(self) - Called when a call is ready.
• on_playback_status(self, status) - Called when the playback status changes.
  • status: PlaybackStatus - Enum, one of PlaybackStatus.IN_PROGRESS or PlaybackStatus.COMPLETE.
• on_audio_chunk_recorded(self, audio_chunk) - Called when an audio chunk is recorded.
  • audio_chunk: AudioChunk - The audio chunk object.
• on_hangup(self) - Called when the call is hung up.
• on_attendee_join(self, attendee) - Called when an attendee joins the call.
  • attendee: CallAttendee - The CallAttendee object.
• on_attendee_drop(self, attendee) - Called when an attendee drops the call.
  • attendee: CallAttendee - The CallAttendee object.

Methods:

• answer(self) - Answers the call.
• reject(self) - Rejects the call.
• hangup(self) - Hangs up the call.
• play(self, file_path) - Plays the specified audio file in the call.
  • file_path: str - The path to the audio file.
• record(self, file_path) - Records the call and saves it to the specified file.
  • file_path: str - The path to the audio file.
• get_active_attendees(self) - Returns a list of active attendees (CallAttendee) in the call.
• get_all_attendees(self) - Returns a list of all attendees (CallAttendee) in the call.

Chat

• persona_uid: str - The unique ID of the persona listening to the chat.
• chat_id: str - The ID of the chat.

Methods:

• show_typing(self, timeout=60, chat_id="", persona_uid="") - Displays a typing indicator in the chat. The indicator is shown for the specified timeout or until the next message is sent.
  • timeout: int - The timeout in seconds.
  • chat_id: str - The ID of the chat to show the typing indicator in. If not specified, the typing indicator is shown in the handled chat.
  • persona_uid: str - The unique ID of the persona to show the typing indicator in chat with. If not specified, the typing indicator is shown in the handled chat.
• send_message(self, text, text_format=None, attachments=None, app_meta=None, chat_id="", persona_uid="") - Sends a message with the specified text to the chat.
  • text: str - The text content of the message. Please see also the "Text helpers" section bellow.
  • text_format: MessageTextFormat | None - The text format of the message. One of MessageTextFormat.HTML, MessageTextFormat.PLAIN or MessageTextFormat.GPTMARKDOWN. If not specified, format is guessed from the text.
  • attachments: List[str] | None - A list of attachment as path to be added to the message.
  • app_meta: Dict[str, Any] | None - A dictionary of additional metadata to be added to the message.
  • chat_id: str - The ID of the chat to send the message to. If not specified, the message is sent to the handled chat.
  • persona_uid: str - The unique ID of the persona to send the message to. If not specified, the message is sent to the handled chat.
• get_history(self, depth=10, start_message_id="0", chat_id="", persona_uid="") - Retrieves the chat history as a list of Message objects.
  • depth: int - The number of messages to retrieve.
  • start_message_id: str - The ID of the message to start from. Use "0"(default) to start from the last message.
  • chat_id: str - The ID of the chat to retrieve the history from. If not specified, the history is retrieved from the handled chat.
  • persona_uid: str - The unique ID of the persona to retrieve the history from chat with. If not specified, the history is retrieved from the handled chat.

Call

• id: str - The ID of the call.
• persona_uid: str - The unique ID of the persona who is listening to the call.
• from_persona_uid: str - The unique ID of the persona who is calling.
• from_name: str - The name of the persona who is calling.

CallAttendee

• id: str - The ID of the attendee.
• number: str - The phone number of the attendee.
• name: str - The name of the attendee.
• persona_uid: str - The unique persona ID of the attendee.

AudioChunk

• audio_file_path: str - The path to the audio file.
• asn_file_path: str - The path to the ASN file.
• duration: float - The duration of the audio file in seconds.
• last_chunk: bool - Indicates whether the audio chunk is the last in the recording.
• full_audio_file_path: str | None - The path to the full audio file, if available.
• full_duration: float | None - The duration of the full audio file in seconds, if available.

Message

• id: str - The ID of the message.
• text: str - The text content of the message.
• from_uid: str - The unique ID of the persona from which the message originated.
• from_name: str - The name of the persona from which the message originated.
• tagged: bool - Indicates whether the persona listening to the chat was tagged in the message.
• attachments: List[MessageAttachment] - A list of MessageAttachment objects.

MessageAttachment

• name: str - The name of the attachment.
• size: int - The size of the attachment.
• url: str - The URL of the attachment.

Text helpers

Text helpers are the set of functions that are used to help to format the text of the message.

• mention(persona_uid, label="")

  • persona_uid: str - The unique ID of the persona to mention.
  • label: str - The label of the persona to mention. If not specified, the label is the same as the persona_uid.

• bold(text)

  • text: str - The text to bold.

• italic(text)

  • text: str - The text to italicize.

• underline(text)

  • text: str - The text to underline.

Example

from phound.chats.text_helpers import bold, italic, underline, mention

class ChatHandler(BaseChatHandler):
    ...
    text = (f"It's possible to use pure html tags to make text <b>bold</b>, or do it with {bold('helper')}\n"
            f"same for <i>italic</i> and <u>underline</u> ({italic('italic')}, {underline('underline')})\n"
            f"To mention someone use {mention('<uid>', 'name')}")
    self.send_message(text)