tls.messaging


Nametls.messaging JSON
Version 0.6.2 PyPI version JSON
download
home_page
SummarySDK for the Telstra Messaging API
upload_time2021-01-20 02:04:42
maintainer
docs_urlNone
authorDavid Andersson
requires_python>=3.8,<4.0
licenseApache-2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Telstra Messaging

The SDK for the Telstra messaging API.

> :warning: **This SDK is experimental, everything is subject to change**

## Installing

```bash
pip install tls.messaging
```

## Getting Started

Set the `TLS_CLIENT_KEY` and `TLS_CLIENT_SECRET` environment variables. These
are the `Client key` and `Client secret` you can find here:
<https://dev.telstra.com/user/me/apps>.

To send your first SMS:

```python
from tls.messaging import sms

sms.send(to="+61412345678", body="Hi")
```

To set the required environment variables if your application is in `app.py`:

```bash
TLS_CLIENT_KEY="<client key>" TLS_CLIENT_SECRET="<client secret>" python app.py
```

## Authentication

On top of the authentication through the `TLS_CLIENT_KEY` and
`TLS_CLIENT_SECRET` environment variables, authentication through code is also
supported. For example:

```python
from tls.messaging.utils.config import CONFIG

CONFIG.tls_client_key = '<client key>'
CONFIG.tls_client_secret = '<client secret>'
```

This should be done before any interactions requiring authentication, such as
sending a SMS.

## Free Trial

Telstra offers a free trial for the messaging API to help you evaluate whether
it meets your needs. There are some restrictions that apply compared to the
full API, including a maximum number of SMS that can be sent and requiring the
registration of a limited number of destinations before SMS can be sent to that
destination. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#tag/Free-Trial>.

### Registering Destinations

> :information_source: **Only required for the free trial**

Register destinations for the free trial. For more information, please see
here:
<https://dev.telstra.com/content/messaging-api#operation/freeTrialBnumRegister>.

The function `tls.messaging.bnum.register` can be used to register
destinations. It takes the following arguments:

- `phone_numbers`: A list of destinations, expected to be phone numbers of the
  form `+614XXXXXXXX` or `04XXXXXXXX`.

It returns the list of phone numbers that have been registered.

For example:

```python
from tls.messaging import bnum

phone_numbers = bnum.register(phone_numbers=["+61412345678"])
print(phone_numbers)
```

### Retrieve Destinations

> :information_source: **Only required for the free trial**

Retrieve destinations for the free trial. For more information, please see
here:
<https://dev.telstra.com/content/messaging-api#operation/freeTrialBnumList>.

The function `tls.messaging.bnum.get` can be used to retrieve registered
destinations. It takes no arguments. It returns the list of phone numbers that
have been registered.

For example:

```python
from tls.messaging import bnum

phone_numbers = bnum.get()
print(phone_numbers)
```

## Subscription

A subscription gives you a dedicated mobile number tied to an application. For
more information, please see here:
<https://dev.telstra.com/content/messaging-api#tag/Provisioning>.

### Create Subscription

Create a new subscription. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/createSubscription>.

The function `tls.messaging.subscription.create` can be used to create a
subscription. It takes the following arguments:

- `active_days` (optional): The number of days the subscription will be active,
  defaults to 30.
- `notify_url` (optional): A notification URL that will be POSTed to whenever a
  new message (i.e. a reply to a message sent) arrives at this destination
  address.

It returns an object with the following properties:

- `destination_address`: The phone number that a message can be sent to.
- `active_days`: The number of days left on the subscription.

For example:

```python
from tls.messaging import subscription

created_subscription = subscription.create()
print(created_subscription)
```

### Get Subscription

Retrieve the current subscription. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/getSubscription>.

The function `tls.messaging.subscription.get` can be used to get the current
subscription. It takes no arguments. It returns an object with the following
properties:

- `destination_address`: The phone number that a message can be sent to.
- `active_days`: The number of days left on the subscription.

For example:

```python
from tls.messaging import subscription

retrieved_subscription = subscription.get()
print(retrieved_subscription)
```

### Delete Subscription

Delete the current subscription. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/deleteSubscription>.

The function `tls.messaging.subscription.delete` can be used to delete the current
subscription. It takes no arguments.

```python
from tls.messaging import subscription

subscription.delete()
```

## SMS

For more information, please see here:
<https://dev.telstra.com/content/messaging-api#tag/Messaging>.

### Send SMS

Send a SMS to a mobile number. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/sendSms>.

The function `tls.messaging.sms.send` can be used to send SMS. It takes the
following arguments:

- `to`: The destination address, expected to be a phone number of the form
  `+614XXXXXXXX` or `04XXXXXXXX`.
- `body`: The SMS to send.
- `from_` (optional): An alphanumeric value which will appear as the sender.
  Note that phone numbers are not supported amd the maximum length is 11
  characters. Certain well know senders will be blocked.
- `validity` (optional): How long the platform should attempt to deliver the
  message for (in minutes).
- `scheduled_delivery` (optional): How long the platform should wait before
  attempting to send the message (in minutes).
- `notify_url` (optional): Contains a URL that will be called once your message
  has been processed.
- `priority` (optional): Message will be placed ahead of all messages with a
  normal priority.
- `reply_request` (optional): If set to true, the reply message functionality
  will be implemented.
- `receipt_off` (optional): Whether Delivery Receipt will be sent back or not.
- `user_msg_ref` (optional): Optional field used by some clients for custom
  reporting.

It returns an object with the following properties:

- `to`: The destination mobile number.
- `delivery_status`: Whether the delivery has been completed.
- `message_id`: Unique identifier for the message.
- `message_status_url`: URL to retrieve the current delivery status.

For example:

```python
from tls.messaging import sms

sms.send(to="+61412345678", body="Hi")
```

### Get SMS Status

Find out whether a SMS has been sent. For more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/getSmsStatus>.

The function `tls.messaging.sms.get_status` can be used to retrieve
the status of a SMS. It takes the following arguments:

- `message_id`:Unique identifier for the message.

It returns an object with the following properties:

- `to`: Where the message is delivered to.
- `delivery_status`: Whether the delivery has been completed.
- `received_timestamp`: When the message was received.
- `sent_timestamp`: When the message was sent.

For example:

```python
from tls.messaging import sms

sent_sms = sms.send(to="+61412345678", body="Hi")
status = sms.get_status(sent_sms.message_id)
print(status)
```

### Retrieve Replies

Retrieve SMS sent to the mobile number associated with the subscription. For
more information, please see here:
<https://dev.telstra.com/content/messaging-api#operation/retrieveSmsReplies>.

The function `tls.messaging.sms.get_next_unread_reply` can be used to retrieve
the next unread reply for your phone number subscription. It takes no
arguments. It returns `None` if there are no more replies or an object with the
following properties:

- `destination_address`: Where the message is delivered to.
- `sender_address`: Who the message is from.
- `status`: Whether the delivery has been completed.
- `message`: The body of the message.
- `message_id`: Unique identifier for the message.
- `sent_timestamp`: When the message was sent.

For example:

```python
from tls.messaging import sms

reply = sms.get_next_unread_reply()
print(reply)
```


            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "tls.messaging",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8,<4.0",
    "maintainer_email": "",
    "keywords": "",
    "author": "David Andersson",
    "author_email": "david-andersson@users.noreply.github.com",
    "download_url": "https://files.pythonhosted.org/packages/54/f1/7aeb0a6389b702a9b452b57b31ae9c5ea5c1d249c01d8615658a7dbcfc7a/tls.messaging-0.6.2.tar.gz",
    "platform": "",
    "description": "# Telstra Messaging\n\nThe SDK for the Telstra messaging API.\n\n> :warning: **This SDK is experimental, everything is subject to change**\n\n## Installing\n\n```bash\npip install tls.messaging\n```\n\n## Getting Started\n\nSet the `TLS_CLIENT_KEY` and `TLS_CLIENT_SECRET` environment variables. These\nare the `Client key` and `Client secret` you can find here:\n<https://dev.telstra.com/user/me/apps>.\n\nTo send your first SMS:\n\n```python\nfrom tls.messaging import sms\n\nsms.send(to=\"+61412345678\", body=\"Hi\")\n```\n\nTo set the required environment variables if your application is in `app.py`:\n\n```bash\nTLS_CLIENT_KEY=\"<client key>\" TLS_CLIENT_SECRET=\"<client secret>\" python app.py\n```\n\n## Authentication\n\nOn top of the authentication through the `TLS_CLIENT_KEY` and\n`TLS_CLIENT_SECRET` environment variables, authentication through code is also\nsupported. For example:\n\n```python\nfrom tls.messaging.utils.config import CONFIG\n\nCONFIG.tls_client_key = '<client key>'\nCONFIG.tls_client_secret = '<client secret>'\n```\n\nThis should be done before any interactions requiring authentication, such as\nsending a SMS.\n\n## Free Trial\n\nTelstra offers a free trial for the messaging API to help you evaluate whether\nit meets your needs. There are some restrictions that apply compared to the\nfull API, including a maximum number of SMS that can be sent and requiring the\nregistration of a limited number of destinations before SMS can be sent to that\ndestination. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#tag/Free-Trial>.\n\n### Registering Destinations\n\n> :information_source: **Only required for the free trial**\n\nRegister destinations for the free trial. For more information, please see\nhere:\n<https://dev.telstra.com/content/messaging-api#operation/freeTrialBnumRegister>.\n\nThe function `tls.messaging.bnum.register` can be used to register\ndestinations. It takes the following arguments:\n\n- `phone_numbers`: A list of destinations, expected to be phone numbers of the\n  form `+614XXXXXXXX` or `04XXXXXXXX`.\n\nIt returns the list of phone numbers that have been registered.\n\nFor example:\n\n```python\nfrom tls.messaging import bnum\n\nphone_numbers = bnum.register(phone_numbers=[\"+61412345678\"])\nprint(phone_numbers)\n```\n\n### Retrieve Destinations\n\n> :information_source: **Only required for the free trial**\n\nRetrieve destinations for the free trial. For more information, please see\nhere:\n<https://dev.telstra.com/content/messaging-api#operation/freeTrialBnumList>.\n\nThe function `tls.messaging.bnum.get` can be used to retrieve registered\ndestinations. It takes no arguments. It returns the list of phone numbers that\nhave been registered.\n\nFor example:\n\n```python\nfrom tls.messaging import bnum\n\nphone_numbers = bnum.get()\nprint(phone_numbers)\n```\n\n## Subscription\n\nA subscription gives you a dedicated mobile number tied to an application. For\nmore information, please see here:\n<https://dev.telstra.com/content/messaging-api#tag/Provisioning>.\n\n### Create Subscription\n\nCreate a new subscription. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/createSubscription>.\n\nThe function `tls.messaging.subscription.create` can be used to create a\nsubscription. It takes the following arguments:\n\n- `active_days` (optional): The number of days the subscription will be active,\n  defaults to 30.\n- `notify_url` (optional): A notification URL that will be POSTed to whenever a\n  new message (i.e. a reply to a message sent) arrives at this destination\n  address.\n\nIt returns an object with the following properties:\n\n- `destination_address`: The phone number that a message can be sent to.\n- `active_days`: The number of days left on the subscription.\n\nFor example:\n\n```python\nfrom tls.messaging import subscription\n\ncreated_subscription = subscription.create()\nprint(created_subscription)\n```\n\n### Get Subscription\n\nRetrieve the current subscription. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/getSubscription>.\n\nThe function `tls.messaging.subscription.get` can be used to get the current\nsubscription. It takes no arguments. It returns an object with the following\nproperties:\n\n- `destination_address`: The phone number that a message can be sent to.\n- `active_days`: The number of days left on the subscription.\n\nFor example:\n\n```python\nfrom tls.messaging import subscription\n\nretrieved_subscription = subscription.get()\nprint(retrieved_subscription)\n```\n\n### Delete Subscription\n\nDelete the current subscription. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/deleteSubscription>.\n\nThe function `tls.messaging.subscription.delete` can be used to delete the current\nsubscription. It takes no arguments.\n\n```python\nfrom tls.messaging import subscription\n\nsubscription.delete()\n```\n\n## SMS\n\nFor more information, please see here:\n<https://dev.telstra.com/content/messaging-api#tag/Messaging>.\n\n### Send SMS\n\nSend a SMS to a mobile number. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/sendSms>.\n\nThe function `tls.messaging.sms.send` can be used to send SMS. It takes the\nfollowing arguments:\n\n- `to`: The destination address, expected to be a phone number of the form\n  `+614XXXXXXXX` or `04XXXXXXXX`.\n- `body`: The SMS to send.\n- `from_` (optional): An alphanumeric value which will appear as the sender.\n  Note that phone numbers are not supported amd the maximum length is 11\n  characters. Certain well know senders will be blocked.\n- `validity` (optional): How long the platform should attempt to deliver the\n  message for (in minutes).\n- `scheduled_delivery` (optional): How long the platform should wait before\n  attempting to send the message (in minutes).\n- `notify_url` (optional): Contains a URL that will be called once your message\n  has been processed.\n- `priority` (optional): Message will be placed ahead of all messages with a\n  normal priority.\n- `reply_request` (optional): If set to true, the reply message functionality\n  will be implemented.\n- `receipt_off` (optional): Whether Delivery Receipt will be sent back or not.\n- `user_msg_ref` (optional): Optional field used by some clients for custom\n  reporting.\n\nIt returns an object with the following properties:\n\n- `to`: The destination mobile number.\n- `delivery_status`: Whether the delivery has been completed.\n- `message_id`: Unique identifier for the message.\n- `message_status_url`: URL to retrieve the current delivery status.\n\nFor example:\n\n```python\nfrom tls.messaging import sms\n\nsms.send(to=\"+61412345678\", body=\"Hi\")\n```\n\n### Get SMS Status\n\nFind out whether a SMS has been sent. For more information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/getSmsStatus>.\n\nThe function `tls.messaging.sms.get_status` can be used to retrieve\nthe status of a SMS. It takes the following arguments:\n\n- `message_id`:Unique identifier for the message.\n\nIt returns an object with the following properties:\n\n- `to`: Where the message is delivered to.\n- `delivery_status`: Whether the delivery has been completed.\n- `received_timestamp`: When the message was received.\n- `sent_timestamp`: When the message was sent.\n\nFor example:\n\n```python\nfrom tls.messaging import sms\n\nsent_sms = sms.send(to=\"+61412345678\", body=\"Hi\")\nstatus = sms.get_status(sent_sms.message_id)\nprint(status)\n```\n\n### Retrieve Replies\n\nRetrieve SMS sent to the mobile number associated with the subscription. For\nmore information, please see here:\n<https://dev.telstra.com/content/messaging-api#operation/retrieveSmsReplies>.\n\nThe function `tls.messaging.sms.get_next_unread_reply` can be used to retrieve\nthe next unread reply for your phone number subscription. It takes no\narguments. It returns `None` if there are no more replies or an object with the\nfollowing properties:\n\n- `destination_address`: Where the message is delivered to.\n- `sender_address`: Who the message is from.\n- `status`: Whether the delivery has been completed.\n- `message`: The body of the message.\n- `message_id`: Unique identifier for the message.\n- `sent_timestamp`: When the message was sent.\n\nFor example:\n\n```python\nfrom tls.messaging import sms\n\nreply = sms.get_next_unread_reply()\nprint(reply)\n```\n\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "SDK for the Telstra Messaging API",
    "version": "0.6.2",
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "6c2cde89ba1694b116dca967733ad9ea",
                "sha256": "78c780f65e32d34ac053fc7641d04002c11ba7ba4243e81b25b363aad9eb4644"
            },
            "downloads": -1,
            "filename": "tls.messaging-0.6.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6c2cde89ba1694b116dca967733ad9ea",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8,<4.0",
            "size": 17097,
            "upload_time": "2021-01-20T02:04:41",
            "upload_time_iso_8601": "2021-01-20T02:04:41.192939Z",
            "url": "https://files.pythonhosted.org/packages/75/58/23e763a437b5584d1cd8ea0843b145e48dec502a685127a74649ad6ea1de/tls.messaging-0.6.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "35acb2ee3b1047fbc0a988e75b12cebe",
                "sha256": "05f2ed7a8d0cd07209a343e4f40dc4bd9a3b02bffc147bf4ea7416e287c7eebb"
            },
            "downloads": -1,
            "filename": "tls.messaging-0.6.2.tar.gz",
            "has_sig": false,
            "md5_digest": "35acb2ee3b1047fbc0a988e75b12cebe",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8,<4.0",
            "size": 15367,
            "upload_time": "2021-01-20T02:04:42",
            "upload_time_iso_8601": "2021-01-20T02:04:42.290781Z",
            "url": "https://files.pythonhosted.org/packages/54/f1/7aeb0a6389b702a9b452b57b31ae9c5ea5c1d249c01d8615658a7dbcfc7a/tls.messaging-0.6.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-01-20 02:04:42",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "tls.messaging"
}
        
Elapsed time: 0.25813s