Skip to content

# Notifications

class terminusgps.aws.notifications.AsyncNotificationManager(origin_pool_arn: str | None = None, configuration_set: str | None = None, max_sms_price: str = '0.20', max_voice_price: str = '0.20', region_name: str = 'us-east-1', debug_enabled: bool = False, logger_level: int = 10, logger_days: int = 10)

  Asyncronously delivers notifications using AWS End User Messaging.

  Public Data Attributes:

  `region_name` | An AWS region name.
  `configuration_set` | The configuration set to use for messaging.
  `origin_pool` | The origination pool to use for messaging.
  `max_sms_price` | The max allowed price per sms message.
  `max_voice_price` | The max allowed price per voice message.
  `debug` | Whether or not debug mode is enabled.

  Public Methods:

  `__init__`([origin_pool_arn, ...]) | Sets attributes on the notification manager.
  `__aenter__`() | Creates asyncronous clients.
  `__aexit__`(exc_type, exc_val, exc_tb) | Destroys asyncronous clients.
  `send_sms`(phone, message[, ttl, dry_run, ...]) | Texts `message` to `phone` via sms.
  `send_voice`(phone, message[, ttl, voice_id, ...]) | Calls `phone` and reads `message` aloud.
  `batch_send_sms`(phones, message, **kwargs) | Sends `message` to all phone numbers in `phones` via sms.
  `batch_send_voice`(phones, message, **kwargs) | Calls each number in `phones` and reads `message` aloud.

  async batch_send_sms(phones: Sequence[str], message: str, **kwargs) → list[dict[str, str]]

    Sends `message` to all phone numbers in `phones` via sms.

    Parameters:

      - phones (`Sequence`) – A sequence of phone numbers.

      - message (`str`) – A message body.

      - kwargs – Additional keyword arguments passed to `send_sms()`.

    Raises:

      AssertionError – If `_pinpoint_client` wasn’t set.

    Returns:

      A list of sms message responses.

    Return type:

      `dict`

    See also

    `send_sms()` for details on available keyword arguments.

  async batch_send_voice(phones: Sequence[str], message: str, **kwargs) → list[dict[str, str]]

    Calls each number in `phones` and reads `message` aloud.

    Parameters:

      - phone (`Sequence`) – A sequence of phone numbers.

      - message (`str`) – A message body.

      - kwargs – Additional keyword arguments passed to `send_voice()`.

    Raises:

      AssertionError – If `_pinpoint_client` wasn’t set.

    Returns:

      A voice message response.

    Return type:

      `dict`

    See also

    `send_voice()` for details on available keyword arguments.

  async send_sms(phone: str, message: str, ttl: int = 300, dry_run: bool = False, feedback: bool = False) → dict[str, str]

    Texts `message` to `phone` via sms.

    Parameters:

      - phone (`str`) – A destination phone number.

      - message (`str`) – A message body.

      - ttl (`int`) – Time to live in ms. Default is `300`.

      - dry_run (`bool`) – Whether or not to execute the message as a dry run. Default is `False`.

      - feedback (`bool`) – Whether or not to include message feedback in the response. Default is `False`.

    Raises:

      AssertionError – If `_pinpoint_client` wasn’t set.

    Returns:

      An sms message response.

    Return type:

      `dict`

  async send_voice(phone: str, message: str, ttl: int = 300, voice_id: str = 'Joanna', dry_run: bool = False, feedback: bool = False) → dict[str, str]

    Calls `phone` and reads `message` aloud.

    Parameters:

      - phone (`str`) – A destination phone number.

      - message (`str`) – A message body.

      - ttl (`int`) – Time to live in ms. Default is `300`.

      - voice_id (`str`) – A voice id to use for speech synthesis. Default is `"Joanna"`.

      - dry_run (`bool`) – Whether or not to execute the message as a dry run. Default is `False`.

      - feedback (`bool`) – Whether or not to include message feedback in the response. Default is `False`.

    Raises:

      AssertionError – If `_pinpoint_client` wasn’t set.

    Returns:

      A voice message response.

    Return type:

      `dict`

  property configuration_set: str

    The configuration set to use for messaging.

    Type:

      `str`

  property debug: bool

    Whether or not debug mode is enabled.

    Type:

      `bool`

    Value:

      `False`

  property max_sms_price: str

    The max allowed price per sms message.

    Type:

      `str`

    Value:

      `"0.20"`

  property max_voice_price: str

    The max allowed price per voice message.

    Type:

      `str`

    Value:

      `"0.20"`

  property origin_pool: str

    The origination pool to use for messaging.

    Type:

      `str`

  property region_name: str

    An AWS region name.

    Type:

      `str`

## Usage

With an `AsyncNotificationManager`, you can asyncronously dispatch sms messages or voice calls.

Within an asyncronous event loop, i.e. `main()`, open an asyncronous context manager with `async with`.

Within the context manager, `await` the `send_sms()` or `send_voice()` methods to dispatch your message.

    import asyncio
    from terminusgps.aws.notifications import AsyncNotificationManager

    async def main() -> None:
        async with AsyncNotificationManager() as manager:
            # This is the message we will dispatch in this example
            message: str = "We know where ours are... do you?"

            # Send the message via sms to a single phone number
            await manager.send_sms("+15555555555", message)

            # Send the message via voice to a single phone number
            await manager.send_voice("+15555555555", message)

            # Send the message via sms to multiple phone numbers
            await manager.batch_send_sms(["+17135555555", "+15555555555"], message)

            # Send the message via sms to a single phone number with feedback
            await manager.send_sms("+15555555555", message, feedback=True)

            # Send the message via sms to a single phone number as a dry run
            await manager.send_sms("+15555555555", message, dry_run=True)
        return

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