### Example Script: Appointment Booking Bot

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

A complete example script demonstrating how to use PySIP to create an appointment booking bot.

```APIDOC
## Example Script: Appointment Booking Bot

### Description
This script demonstrates a basic appointment booking bot that handles incoming calls to book appointments.

### Code
```python
import asyncio
from PySIP.sip_account import SipAccount
from scripts.appointment_booking_bot import appointment_booking_bot
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Initialize SIP account with credentials from .env file
account = SipAccount(
    os.environ["SIP_USERNAME"],
    os.environ["SIP_PASSWORD"],
    os.environ["SIP_SERVER"],
)

@account.on_incoming_call
async def handle_incoming_call(call: SipCall):
    await call.accept()
    await call.call_handler.say("We have received your call successfully")

async def main():
    # Register the SIP account
    await account.register()

    # Make a call to a test number (e.g., '111')
    call = account.make_call("111")
    call_task = asyncio.create_task(call.start())

    # Run the appointment booking bot
    await appointment_booking_bot(call.call_handler, customer_name="John")

    # Wait for the call to complete, then unregister
    await call_task
    await account.unregister()

if __name__ == "__main__":
    asyncio.run(main())
```
```

--------------------------------

### Install PySIP from PyPI

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Installs the PySIP library from the Python Package Index (PyPI) using pip. Ensure you use the correct package name 'PySIPio'.

```bash
pip install PySIPio
```

--------------------------------

### Appointment Booking Bot Example Script

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

A complete Python script demonstrating PySIP usage for an appointment booking bot. It includes account initialization, registration, making calls, handling incoming calls, and running the bot logic.

```python
import asyncio
from PySIP.sip_account import SipAccount
from scripts.appointment_booking_bot import appointment_booking_bot
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Initialize SIP account with credentials from .env file
account = SipAccount(
    os.environ["SIP_USERNAME"],
    os.environ["SIP_PASSWORD"],
    os.environ["SIP_SERVER"],
)

@account.on_incoming_call
async def handle_incoming_call(call: SipCall):
    await call.accept()
    await call.call_handler.say("We have received your call successfully")

async def main():
    # Register the SIP account
    await account.register()

    # Make a call to a test number (e.g., '111')
    call = account.make_call("111")
    call_task = asyncio.create_task(call.start())

    # Run the appointment booking bot
    await appointment_booking_bot(call.call_handler, customer_name="John")

    # Wait for the call to complete, then unregister
    await call_task
    await account.unregister()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Clone PySIP Repository and Install Dependencies

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Clones the PySIP GitHub repository and installs its dependencies using pip. This method requires Git and Python 3.8+.

```bash
git clone https://github.com/moha-abdi/PySIP.git
cd PySIP
pip install -r requirements.txt
```

--------------------------------

### Instantiate SIP Account

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Creates an instance of the SipAccount class. This requires the username, password, and server address for the SIP account.

```python
account = SipAccount(username, password, server)
```

--------------------------------

### Configure SIP Account Credentials

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Sets up SIP account credentials by creating a .env file with SIP_USERNAME, SIP_PASSWORD, and SIP_SERVER. This file is then loaded to access these environment variables.

```bash
SIP_USERNAME=your_sip_username
SIP_PASSWORD=your_sip_password
SIP_SERVER=your_sip_server
```

--------------------------------

### Initialize SipAccount in Python

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Initializes a SipAccount object in Python using credentials loaded from a .env file via the dotenv library. This is the first step to interacting with SIP services.

```python
from PySIP.sip_account import SipAccount
import os
from dotenv import load_dotenv

# Load SIP credentials from .env file
load_dotenv()

account = SipAccount(
    os.environ["SIP_USERNAME"],
    os.environ["SIP_PASSWORD"],
    os.environ["SIP_SERVER"],
)
```

--------------------------------

### SipAccount API

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Documentation for the SipAccount class, which is central to PySIP operations. It covers instantiation, registration, making calls, handling incoming calls, and unregistering.

```APIDOC
## SipAccount Class

### Description
The `SipAccount` class manages all account-related tasks, including registration, initiating calls, and unregistering from the SIP server.

### Instantiating a SIP Account
```python
account = SipAccount(username, password, server)
```

### Registering an Account
```python
await account.register()
```

### Making a Call
```python
call = account.make_call("destination_number")
```

### Handling Incoming Calls
Use the `on_incoming_call` decorator to define a handler for incoming calls.
```python
@account.on_incoming_call
async def handle_incoming_call(call: SipCall):
    await call.accept()  # or call.reject() or call.busy()
    await call.call_handler.say("Thank you for calling us!")
    await call.call_handler.hangup()
```

### Unregistering an Account
```python
await account.unregister()
```
```

--------------------------------

### Register SIP Account

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Registers the SipAccount with the SIP server. This initiates the process of activating the account on the server, enabling subsequent call functionalities.

```python
await account.register()
```

--------------------------------

### Handle Incoming Call Status

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Manages the state of an incoming call by accepting, rejecting, or marking it as busy.

```python
await call.accept()  # Accept the incoming call
await call.reject()  # Reject the incoming call
await call.busy()    # Mark the line as busy for the incoming call
```

--------------------------------

### Make SIP Call

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Initiates an outgoing call to a specified destination number. The method returns a Call object that can be used to manage the call lifecycle.

```python
call = account.make_call("destination_number")
```

--------------------------------

### Handle Incoming SIP Calls

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Defines a handler function for incoming calls using a decorator. This function processes incoming calls, allowing actions like accepting, rejecting, or engaging with the caller.

```python
@account.on_incoming_call
async def handle_incoming_call(call: SipCall):
    await call.accept()  # or call.reject() or call.busy()
    await call.call_handler.say("Thank you for calling us!")
    await call.call_handler.hangup()
```

--------------------------------

### Call Handling API

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Details on the CallHandler class, which facilitates managing the call flow, including playing messages, gathering input, transferring calls, and managing call states.

```APIDOC
## Call Handling

### Description
The `CallHandler` is responsible for managing the call flow, allowing interaction with the caller.

### Playing a Message
```python
await call_handler.say("Welcome to our service.")
```

### Gathering User Input
```python
dtmf_key = await call_handler.gather(length=1, timeout=5)
```

### Transferring a Call
```python
await call_handler.transfer_to("1234567890")
```

### Managing Incoming Call States
For incoming calls, you can accept, reject, or mark the line as busy:
```python
await call.accept()  # Accept the incoming call
await call.reject()  # Reject the incoming call
await call.busy()    # Mark the line as busy for the incoming call
```
```

--------------------------------

### Gather User Input

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Collects DTMF input (key presses) from the caller. It allows specifying the length of input and a timeout period.

```python
dtmf_key = await call_handler.gather(length=1, timeout=5)
```

--------------------------------

### Receive UDP Datagram

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Processes incoming UDP datagrams. Received data is placed into a queue for further asynchronous processing.

```python
self.data_q.put_nowait(data)
```

--------------------------------

### Play Message in Call

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Plays an audio message to the caller using the CallHandler. This is useful for interactive voice response (IVR) systems.

```python
await call_handler.say("Welcome to our service.")
```

--------------------------------

### Unregister SIP Account

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Gracefully closes the SIP session by unregistering the account from the server. This is essential for a clean shutdown of SIP services.

```python
await account.unregister()
```

--------------------------------

### UDP Transport API

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Information regarding the UdpHandler, which manages the sending and receiving of SIP messages over UDP.

```APIDOC
## UDP Transport

### Description
The `UdpHandler` manages the asynchronous sending and receiving of SIP messages over the network using UDP.

### Sending a Message
```python
self.transport.sendto(message)
```

### Receiving a Datagram
```python
self.data_q.put_nowait(data)
```
```

--------------------------------

### Send UDP Message

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Sends a UDP message, typically a SIP message, to a specified destination. This is handled internally by the UdpHandler.

```python
self.transport.sendto(message)
```

--------------------------------

### Transfer Call

Source: https://github.com/moha-abdi/pysip/blob/main/README.md

Forwards an ongoing call to a different phone number. This is a common feature for call centers or routing calls.

```python
await call_handler.transfer_to("1234567890")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.