teamwire_api.connection

ConnectionConfig

class ConnectionConfig(object)

ConnectionConfig holds the configuration setup for the active connection

Attributes

  • hide_deleted_messages: boolean. Default True. Whether chat methods and message notifications should include already deleted messages. \ If hide_deleted_messages is False, messages that have been deleted by the sender are returned normally in message lists and notifications \ with the deleted attribute set to True, otherwise, deleted messages will not be reported.
  • default_timeout: integer. Timeout value in seconds to be used for all generic HTTP requests. Default: 10 seconds
  • long_timeout: integer. Timeout value in seconds to be used for long HTTP requests. Default: 15 seconds
  • assets_timeout: integer. Timeout value in seconds to be used for attachment assets uploading/downloading. Default: 60 seconds

Note

default values for http timeouts are tuned to allow bots to quickly recover from network failures, while still allowing long running requests to complete. There may be cases where longer timeout values are needed. They can be changed by passing custom values for the default_timeout, long_timeout and/or assets_timeout properties of the ConnectionConfig object. In particular, assets_timeout is used for HTTP requests related to uploading and downloading attachment assets; long_timeout is used for HTTP requests that might require a long time to complete (e.g. getting contacts and chat subscriptions); default_timeout is used for all other requests.

__init__

 | __init__(hide_deleted_messages=True, default_timeout=10, long_timeout=15, assets_timeout=60)

ConnectionConfig constructor

Arguments

  • hide_deleted_messages: boolean. Default True. Whether chat methods and message notifications should include already deleted messages
  • default_timeout: integer. Timeout value in seconds to be used for all generic HTTP requests. Default: 10 seconds
  • long_timeout: integer. Timeout value in seconds to be used for long HTTP requests. Default: 15 seconds
  • assets_timeout: integer. Timeout value in seconds to be used for attachment assets uploading/downloading. Default: 60 seconds

Connection

class Connection(object)

The Connection object is the entry point for the Teamwire SDK. On creation, you can pass three parameters, appid, secret and host corresponding to your API key, the matching secret for that API key, and the backend server URL of the Teamwire server on which the API key is valid. If you don’t pass these parameters, the Connection object will fetch these values from the environment variables, TW_API_APPID, TW_API_SECRET and TW_API_HOST; meaning you can change your installation without altering the source code.

__init__

 | __init__(appid=None, secret=None, host=None, config=ConnectionConfig(), loop=asyncio.get_event_loop())

Connection constructor

Arguments

  • appid: unicode. The APPID part of the bot API KEY. If None, the value is expected to be set in the TW_API_APPID environment variable
  • secret: unicode. The SECRET part of the bot API KEY. If None, the value is expected to be set in the TW_API_SECRET environment variable
  • host: unicode. The backend URL (e.g. "https://backend.teamwire.eu"). If None, the value is expected to be set in the TW_API_HOST environment variable
  • config: a ConnectionConfig object. Optional configuration settings for the connection
  • loop: optional Asyncio event loop to be used by the SDK

get_permissions

 | async get_permissions()

Coroutine to get the permissions and settings set for the SDK in the backend admin dashboard

Returns

a Permissions object

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

get_settings

 | async get_settings()

Coroutine to get the bot settings

Returns

a Settings object

Raises

exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

update_settings

 | async update_settings(read_receipts_enabled)

Coroutine to update the bot settings

Arguments

  • read_receipts_enabled: boolean. Whether sending read-receipts notifications to other users is enabled for the bot

Raises

exceptions.TWDisableReadReceiptsNotAllowed if disabling read receipts notification sending is disallowed by the TW admin exceptions.TWConnectionError in case of network error or timeout exceptions.TWServerError in case of backend-related problems

set_handler

 | set_handler(event_types, handler)

Set a handler for specific event types

Arguments

  • event_types: a list of values from the Events and ConnectionEvents enums
  • handler: a callable to be invoked when any of the registered events is triggered

exec_async

 | exec_async(coro)

Execute an async task or coroutine on the current run loop. The method returns only after the task execution is complete

Arguments

  • coro: an async task or coroutine to be executed

Returns

the coroutine's result (or raises its exception)

start_notifications

 | start_notifications(task=None)

Start the notifications loop and run the provided task

Arguments

  • task: a (possibly long running) task to be executed during the bot's life

run_task

 | run_task(task)

Start the main bot loop and run the provided task (deprecated: use start_notifications() instead)

Arguments

  • task: a (possibly long running) task to be executed during the bot's life