twilio

twilio#

Description#

The Twilio plugin allows you to send messages and WhatsApp texts and make programmable phone call by using a Twilio account. Note that some features may require a Premium account.

Configuration#

twilio:
  # [Required]
  # Account SID.
  account_sid:   # type=str

  # [Required]
  # Account authentication token.
  auth_token:   # type=str

  # [Optional]
  # SID of the default physical address - required to
  # register a new number in some countries.
  # address_sid:   # type=Optional[str]

  # [Optional]
  # Default phone number associated to the account to
  # be used for messages and calls.
  # phone_number:   # type=Optional[str]

  # [Optional]
  # ``name``->``phone_number`` mapping of contacts.
  # You can use directly these names to send messages and make calls
  # instead of the full phone number.
  # address_book:   # type=Optional[Dict[str, str]]

Dependencies#

pip

pip install twilio

Debian

apt install python3-twilio

Fedora

yum install python-twilio

Actions#

Module reference#

class platypush.plugins.twilio.TwilioPhoneNumberType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

class platypush.plugins.twilio.TwilioPlugin(account_sid: str, auth_token: str, address_sid: str | None = None, phone_number: str | None = None, address_book: Dict[str, str] | None = None, **kwargs)[source]#

Bases: Plugin

The Twilio plugin allows you to send messages and WhatsApp texts and make programmable phone call by using a Twilio account. Note that some features may require a Premium account.

__init__(account_sid: str, auth_token: str, address_sid: str | None = None, phone_number: str | None = None, address_book: Dict[str, str] | None = None, **kwargs)[source]#
Parameters:

  • account_sid – Account SID.

  • auth_token – Account authentication token.

  • address_sid – SID of the default physical address - required to register a new number in some countries.

  • phone_number – Default phone number associated to the account to be used for messages and calls.

  • address_book – name->``phone_number`` mapping of contacts. You can use directly these names to send messages and make calls instead of the full phone number.

create_address(customer_name: str, street: str, city: str, region: str, postal_code: str, iso_country: str)[source]#

Create a new address associated to your account.

Parameters:

  • customer_name – Full name of the customer.

  • street – Street name.

  • city – City name.

  • region – Region name.

  • postal_code – Postal code.

  • iso_country – ISO code of the country.

Returns:

Details of the newly created address. Example:

{
  "account_sid": "ACXXX",
  "city": "city",
  "customer_name": "customer_name",
  "date_created": "Tue, 18 Aug 2015 17:07:30 +0000",
  "date_updated": "Tue, 18 Aug 2015 17:07:30 +0000",
  "emergency_enabled": false,
  "friendly_name": null,
  "iso_country": "US",
  "postal_code": "postal_code",
  "region": "region",
  "sid": "ADXXX",
  "street": "street",
  "validated": false,
  "verified": false,
  "uri": "/2010-04-01/Accounts/ACXXX/Addresses/ADXXX.json"
}

delete_message(message_sid: str)[source]#

Delete a send/received message.

Parameters:

message_sid – Message SID to be deleted.

get_available_phone_numbers(country: str, number_type: str) → List[dict][source]#

Get a list of phone numbers of a certain type available for a certain country.

Parameters:

  • country – Country code (e.g. US or NL).

  • number_type – Phone number type - e.g. mobile, local or toll_free.

Returns:

A list of the available phone numbers with their properties and capabilities. Example:

  [
    {
      "friendly_name": "+311234567890",
      "phone_number": "+311234567890",
      "lata": null,
      "rate_center": null,
      "latitude": null,
      "longitude": null,
      "locality": null,
      "region": null,
      "postal_code": null,
      "iso_country": "NL",
      "address_requirements": "any",
      "beta": false,
      "capabilities": {
        "voice": true,
        "SMS": true,
        "MMS": false,
        "fax": false
      }
    }
]

get_message(message_sid: str) → dict[source]#

Get the details of a stored message.

Parameters:

message_sid – Message SID to be retrieved.

Returns:

Message with its properties - see send_message().

list_calls(to: str | None = None, from_: str | None = None, parent_call_sid: str | None = None, status: str | None = None, start_time_before: str | None = None, start_time: str | None = None, start_time_after: str | None = None, end_time_before: str | None = None, end_time: str | None = None, end_time_after: str | None = None, limit: int | None = None, page_size: int | None = None) → List[dict][source]#

List the calls performed by the account, either the full list or those that match some filter.

Parameters:

  • to – Phone number or Client identifier of calls to include

  • from – Phone number or Client identifier to filter from on

  • parent_call_sid – Parent call SID to filter on

  • status – The status of the resources to read

  • start_time_before – Only include calls that started on this date

  • start_time – Only include calls that started on this date

  • start_time_after – Only include calls that started on this date

  • end_time_before – Only include calls that ended on this date

  • end_time – Only include calls that ended on this date

  • end_time_after – Only include calls that ended on this date

  • limit – Upper limit for the number of records to return. list() guarantees never to return more than limit. Default is no limit

  • page_size – Number of records to fetch per request, when not set will use the default value of 50 records. If no page_size is defined but a limit is defined, list() will attempt to read the limit with the most efficient page size, i.e. min(limit, 1000)

Returns:

A list of dictionaries, each representing the information of a call. Example:

[
   {
      "account_sid": "ACXXX",
      "annotation": "billingreferencetag1",
      "answered_by": "machine_start",
      "api_version": "2010-04-01",
      "caller_name": "callerid1",
      "date_created": "Fri, 18 Oct 2019 17:00:00 +0000",
      "date_updated": "Fri, 18 Oct 2019 17:01:00 +0000",
      "direction": "outbound-api",
      "duration": "4",
      "end_time": "Fri, 18 Oct 2019 17:03:00 +0000",
      "forwarded_from": "calledvia1",
      "from": "+13051416799",
      "from_formatted": "(305) 141-6799",
      "group_sid": "GPXXX",
      "parent_call_sid": "CAXXX",
      "phone_number_sid": "PNXXX",
      "price": "-0.200",
      "price_unit": "USD",
      "sid": "CAXXX",
      "start_time": "Fri, 18 Oct 2019 17:02:00 +0000",
      "status": "completed",
      "subresource_uris": {
        "feedback": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Feedback.json",
        "feedback_summaries": "/2010-04-01/Accounts/ACXXX/Calls/FeedbackSummary.json",
        "notifications": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Notifications.json",
        "recordings": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Recordings.json",
        "payments": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Payments.json"
      },
      "to": "+13051913581",
      "to_formatted": "(305) 191-3581",
      "trunk_sid": "TKXXX",
      "uri": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX.json",
      "queue_time": "1000"
  }
]

list_messages(to: str | None = None, from_: str | None = None, date_sent_before: str | None = None, date_sent: str | None = None, date_sent_after: str | None = None, limit: int | None = None, page_size: int | None = None) → List[dict][source]#

List all messages matching the specified criteria.

Parameters:

  • to – Recipient phone number or address book name.

  • from – Sender phone number.

  • date_sent_before – Maximum date filter (ISO format: YYYYMMDD with or without time).

  • date_sent – Date filter (ISO format: YYYYMMDD with or without time).

  • date_sent_after – Minimum date filter (ISO format: YYYYMMDD with or without time).

  • limit – Maximum number of messages to be returned.

  • page_size – Maximum number of messages per page.

Returns:

List of selected messages. Example:

{
  "account_sid": "ACXXX",
  "api_version": "2010-04-01",
  "body": "testing",
  "date_created": "Fri, 24 May 2019 17:44:46 +0000",
  "date_sent": "Fri, 24 May 2019 17:44:50 +0000",
  "date_updated": "Fri, 24 May 2019 17:44:50 +0000",
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from": "+12019235161",
  "messaging_service_sid": null,
  "num_media": "0",
  "num_segments": "1",
  "price": "-0.00750",
  "price_unit": "USD",
  "sid": "SMded05904ccb347238880ca9264e8fe1c",
  "status": "sent",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXX/Messages/SMXXX/Media.json",
    "feedback": "/2010-04-01/Accounts/ACXXX/Messages/SMXXX/Feedback.json"
  },
  "to": "+18182008801",
  "uri": "/2010-04-01/Accounts/ACXXX/Messages/SMXXX.json"
}

make_call(twiml: str, to: str, from_: str | None = None, method: str | None = None, status_callback: str | None = None, status_callback_event: str | None = None, status_callback_method: str | None = None, fallback_url: str | None = None, fallback_method: str | None = None, send_digits: str | None = None, timeout: int | None = 30, record: bool = False, recording_channels: int | None = None, recording_status_callback: str | None = None, recording_status_callback_method: str | None = None, recording_status_callback_event: str | None = None, sip_auth_username: str | None = None, sip_auth_password: str | None = None, caller_id: str | None = None, call_reason: str | None = None) → dict[source]#

Make an automated phone call from a registered Twilio number.

Parameters:

  • twiml – TwiML containing the logic to be executed in the call (see https://www.twilio.com/docs/voice/twiml).

  • to – Recipient phone number or address book name.

  • from – Registered Twilio phone number that will perform the call (default: default configured phone number).

  • method – HTTP method to use to fetch TwiML if it’s provided remotely.

  • status_callback – The URL that should be called to send status information to your application.

  • status_callback_event – The call progress events to be sent to the status_callback URL.

  • status_callback_method – HTTP Method to use with status_callback.

  • fallback_url – Fallback URL in case of error.

  • fallback_method – HTTP Method to use with fallback_url.

  • send_digits – The digits to dial after connecting to the number.

  • timeout – Number of seconds to wait for an answer.

  • record – Whether to record the call.

  • recording_channels – The number of channels in the final recording.

  • recording_status_callback – The URL that we call when the recording is available to be accessed.

  • recording_status_callback_method – The HTTP method to use when calling the recording_status_callback URL.

  • recording_status_callback_event – The recording status events that will trigger calls to the URL specified in recording_status_callback

  • sip_auth_username – The username used to authenticate the caller making a SIP call.

  • sip_auth_password – The password required to authenticate the user account specified in sip_auth_username.

  • caller_id – The phone number, SIP address, or Client identifier that made this call. Phone numbers are in E.164 format (e.g., +16175551212). SIP addresses are formatted as name@company.com.

  • call_reason – Reason for the call (Branded Calls Beta).

Returns:

The call properties and details, as a dictionary. Example:

{
   "account_sid": "ACXXX",
   "annotation": null,
   "answered_by": null,
   "api_version": "2010-04-01",
   "caller_name": null,
   "date_created": "Tue, 31 Aug 2010 20:36:28 +0000",
   "date_updated": "Tue, 31 Aug 2010 20:36:44 +0000",
   "direction": "inbound",
   "duration": "15",
   "end_time": "Tue, 31 Aug 2010 20:36:44 +0000",
   "forwarded_from": "+141586753093",
   "from": "+15017122661",
   "from_formatted": "(501) 712-2661",
   "group_sid": null,
   "parent_call_sid": null,
   "phone_number_sid": "PNXXX",
   "price": "-0.03000",
   "price_unit": "USD",
   "sid": "CAXXX",
   "start_time": "Tue, 31 Aug 2010 20:36:29 +0000",
   "status": "completed",
   "subresource_uris": {
     "notifications": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Notifications.json",
     "recordings": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Recordings.json",
     "feedback": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Feedback.json",
     "feedback_summaries": "/2010-04-01/Accounts/ACXXX/Calls/FeedbackSummary.json",
     "payments": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX/Payments.json"
   },
   "to": "+14155551212",
   "to_formatted": "(415) 555-1212",
   "trunk_sid": null,
   "uri": "/2010-04-01/Accounts/ACXXX/Calls/CAXXX.json",
   "queue_time": "1000"
}

register_phone_number(phone_number: str, friendly_name: str | None = None, address_sid: str | None = None, sms_url: str | None = None, sms_fallback_url: str | None = None, status_callback: str | None = None, voice_caller_id_lookup: bool = True, voice_url: str | None = None, voice_fallback_url: str | None = None, area_code: str | None = None) → dict[source]#

Request to allocate a phone number on your Twilio account. The phone number should first be displayed as available in get_available_phone_numbers().

Parameters:

  • phone_number – Phone number to be allocated.

  • friendly_name – A string used to identify your new phone number.

  • address_sid – Address SID. NOTE: some countries may require you to specify a valid address in order to register a new phone number (see meth:create_address). If none is specified then the configured address_sid (if available) will be applied.

  • sms_url – URL to call when an SMS is received.

  • sms_fallback_url – URL to call when an error occurs on SMS delivery/receipt.

  • status_callback – URL to call when a status change occurs.

  • voice_caller_id_lookup – Whether to perform ID lookup for incoming caller numbers.

  • voice_url – URL to call when the number receives a call.

  • voice_fallback_url – URL to call when a call fails.

  • area_code – Override the area code for the new number.

Returns:

Status of the newly created number. Example:

{
  "account_sid": "ACXXX",
  "address_requirements": "none",
  "address_sid": "ADXXX",
  "api_version": "2010-04-01",
  "beta": false,
  "capabilities": {
    "voice": true,
    "sms": false,
    "mms": true,
    "fax": false
  },
  "date_created": "Thu, 30 Jul 2015 23:19:04 +0000",
  "date_updated": "Thu, 30 Jul 2015 23:19:04 +0000",
  "emergency_status": "Active",
  "emergency_address_sid": "ADXXX",
  "friendly_name": "friendly_name",
  "identity_sid": "RIXXX",
  "origin": "origin",
  "phone_number": "+18089255327",
  "sid": "PNXXX",
  "sms_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "sms_fallback_method": "GET",
  "sms_fallback_url": "https://example.com",
  "sms_method": "GET",
  "sms_url": "https://example.com",
  "status_callback": "https://example.com",
  "status_callback_method": "GET",
  "trunk_sid": null,
  "uri": "/2010-04-01/Accounts/ACXXX/IncomingPhoneNumbers/PNXXX.json",
  "voice_application_sid": "APXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "voice_caller_id_lookup": false,
  "voice_fallback_method": "GET",
  "voice_fallback_url": "https://example.com",
  "voice_method": "GET",
  "voice_url": "https://example.com",
  "bundle_sid": "BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "voice_receive_mode": "voice",
  "status": "in-use"
}

send_message(body: str, to: str, from_: str | None = None, status_callback: str | None = None, max_price: str | None = None, attempt: int | None = None, validity_period: int | None = None, smart_encoded: bool = True, media_url: str | None = None) → dict[source]#

Send an SMS/MMS.

Note: WhatsApp messages are also supported (and free of charge), although the functionality is currently quite limited. Full support is only available to WhatsApp Business profiles and indipendent software vendors approved by WhatsApp. If that’s not the case, you can send WhatsApp messages through the Twilio Test account/number - as of now the from_ field should be whatsapp:+14155238886 and the to field should be whatsapp:+<phone_number_here>. More information here.

Parameters:

  • body – Message body.

  • to – Recipient number or address book name.

  • from – Sender number. If none is specified then the default configured phone_number will be used if available.

  • status_callback – The URL to call to send status information to the application.

  • max_price – The total maximum price up to 4 decimal places in US dollars acceptable for the message to be delivered.

  • attempt – Total numer of attempts made , this inclusive to send out the message.

  • validity_period – The number of seconds that the message can remain in our outgoing queue.

  • smart_encoded – Whether to detect Unicode characters that have a similar GSM-7 character and replace them.

  • media_url – The URL of the media to send with the message.

Returns:

A mapping representing the status of the delivery. Example:

{
  "account_sid": "ACXXX",
  "api_version": "2010-04-01",
  "body": "Sent from your Twilio trial account - It works!",
  "date_created": "2020-08-17T16:32:09.341",
  "date_updated": "2020-08-17T16:32:09.526",
  "date_sent": null,
  "direction": "outbound-api",
  "error_code": null,
  "error_message": null,
  "from_": "+XXXXXXXXX",
  "messaging_service_sid": null,
  "num_media": "0",
  "num_segments": "1",
  "price": null,
  "price_unit": "USD",
  "sid": "XXXXXXXXXXXXX",
  "status": "queued",
  "subresource_uris": {
    "media": "/2010-04-01/Accounts/ACXXX/Messages/SMXXX/Media.json"
  },
  "to": "+XXXXXXXXXXXXXX",
  "uri": "/2010-04-01/Accounts/ACXXX/Messages/SMXXX.json"
}

update_message(message_sid: str, body: str) → dict[source]#

Update/redact the body of a message.

Parameters:

  • message_sid – Message SID to be updated.

  • body – New message body.

Returns:

Updated message with its properties - see send_message().