Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.
Twilio Notifications connector
Warning
This connector has moved into the extended life phase, and Amazon IoT Greengrass won't release updates that provide features, enhancements to existing features, security patches, or bug fixes. For more information, see Amazon IoT Greengrass Version 1 maintenance policy.
The Twilio Notifications connector makes automated phone calls or sends text messages through Twilio. You can use this connector to send notifications in response to events in the Greengrass group. For phone calls, the connector can forward a voice message to the recipient.
This connector receives Twilio message information on an MQTT topic, and then triggers a Twilio notification.
Note
For a tutorial that shows how to use the Twilio Notifications connector, see Getting started with Greengrass connectors (console) or Getting started with Greengrass connectors (CLI).
This connector has the following versions.
Version |
ARN |
---|---|
5 |
|
4 |
|
3 |
|
2 |
|
1 |
|
For information about version changes, see the Changelog.
Requirements
This connector has the following requirements:
Connector Parameters
This connector provides the following parameters.
Create Connector Example (Amazon CLI)
The following example CLI command creates a ConnectorDefinition
with an initial version that
contains the Twilio Notifications connector.
aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{ "Connectors": [ { "Id": "MyTwilioNotificationsConnector", "ConnectorArn": "arn:aws:greengrass:
region
::/connectors/TwilioNotifications/versions/5", "Parameters": { "TWILIO_ACCOUNT_SID": "abcd12345xyz", "TwilioAuthTokenSecretArn": "arn:aws-cn:secretsmanager:region
:account-id
:secret:greengrass-secret-hash
", "TwilioAuthTokenSecretArn-ResourceId": "MyTwilioSecret", "DefaultFromPhoneNumber": "+19999999999", "IsolationMode" : "GreengrassContainer" } } ] }'
For tutorials that show how add the Twilio Notifications connector to a group, see Getting started with Greengrass connectors (CLI) and Getting started with Greengrass connectors (console).
Input data
This connector accepts Twilio message information on two MQTT topics. Input messages must be in JSON format.
-
Text message information on the
twilio/txt
topic. -
Phone message information on the
twilio/call
topic.
Note
The input message payload can include a text message (message
) or voice
message (voice_message_location
), but not both.
- Topic filter:
twilio/txt
-
- Message properties
-
request
-
Information about the Twilio notification.
Required:
true
Type:
object
that includes the following properties:recipient
-
The message recipient. Only one recipient is supported.
Required:
true
Type:
object
that include the following properties:name
-
The name of the recipient.
Required:
true
Type:
string
Valid pattern:
.*
phone_number
-
The phone number of the recipient.
Required:
true
Type:
string
Valid pattern:
\+[1-9]+
message
-
The text content of the text message. Only text messages are supported on this topic. For voice messages, use
twilio/call
.Required:
true
Type:
string
Valid pattern:
.+
from_number
-
The phone number of the sender. Twilio uses this phone number to initiate the message. This property is required if the
DefaultFromPhoneNumber
parameter isn't configured. IfDefaultFromPhoneNumber
is configured, you can use this property to override the default.Required:
false
Type:
string
Valid pattern:
\+[1-9]+
retries
-
The number of retries. The default is 0.
Required:
false
Type:
integer
id
-
An arbitrary ID for the request. This property is used to map an input request to an output response.
Required:
true
Type:
string
Valid pattern:
.+
- Example input
-
{ "request": { "recipient": { "name": "Darla", "phone_number": "+12345000000", "message": "Hello from the edge" }, "from_number": "+19999999999", "retries": 3 }, "id": "request123" }
- Topic filter:
twilio/call
-
- Message properties
-
request
-
Information about the Twilio notification.
Required:
true
Type:
object
that includes the following properties:recipient
-
The message recipient. Only one recipient is supported.
Required:
true
Type:
object
that include the following properties:name
-
The name of the recipient.
Required:
true
Type:
string
Valid pattern:
.+
phone_number
-
The phone number of the recipient.
Required:
true
Type:
string
Valid pattern:
\+[1-9]+
voice_message_location
-
The URL of the audio content for the voice message. This must be in TwiML format. Only voice messages are supported on this topic. For text messages, use
twilio/txt
.Required:
true
Type:
string
Valid pattern:
.+
from_number
-
The phone number of the sender. Twilio uses this phone number to initiate the message. This property is required if the
DefaultFromPhoneNumber
parameter isn't configured. IfDefaultFromPhoneNumber
is configured, you can use this property to override the default.Required:
false
Type:
string
Valid pattern:
\+[1-9]+
retries
-
The number of retries. The default is 0.
Required:
false
Type:
integer
id
-
An arbitrary ID for the request. This property is used to map an input request to an output response.
Required:
true
Type:
string
Valid pattern:
.+
- Example input
-
{ "request": { "recipient": { "name": "Darla", "phone_number": "+12345000000", "voice_message_location": "https://some-public-TwiML" }, "from_number": "+19999999999", "retries": 3 }, "id": "request123" }
Output data
This connector publishes status information as output data on an MQTT topic.
- Topic filter in subscription
-
twilio/message/status
- Example output: Success
-
{ "response": { "status": "success", "payload": { "from_number": "+19999999999", "messages": { "message_status": "queued", "to_number": "+12345000000", "name": "Darla" } } }, "id": "request123" }
- Example output: Failure
-
{ "response": { "status": "fail", "error_message": "Recipient name cannot be None", "error": "InvalidParameter", "payload": None } }, "id": "request123" }
The
payload
property in the output is the response from the Twilio API when the message is sent. If the connector detects that the input data is invalid (for example, it doesn't specify a required input field), the connector returns an error and sets the value toNone
. The following are example payloads:{ 'from_number':'+19999999999', 'messages': { 'name':'Darla', 'to_number':'+12345000000', 'message_status':'undelivered' } }
{ 'from_number':'+19999999999', 'messages': { 'name':'Darla', 'to_number':'+12345000000', 'message_status':'queued' } }
Usage Example
Use the following high-level steps to set up an example Python 3.7 Lambda function that you can use to try out the connector.
Note
The Getting started with Greengrass connectors (console) and Getting started with Greengrass connectors (CLI) topics contain end-to-end steps that show how to set up, deploy, and test the Twilio Notifications connector.
Make sure you meet the requirements for the connector.
-
Create and publish a Lambda function that sends input data to the connector.
Save the example code as a PY file. Download and unzip the Amazon IoT Greengrass Core SDK for Python. Then, create a zip package that contains the PY file and the
greengrasssdk
folder at the root level. This zip package is the deployment package that you upload to Amazon Lambda.After you create the Python 3.7 Lambda function, publish a function version and create an alias.
-
Configure your Greengrass group.
-
Add the Lambda function by its alias (recommended). Configure the Lambda lifecycle as long-lived (or
"Pinned": true
in the CLI). -
Add the required secret resource and grant read access to the Lambda function.
-
Add the connector and configure its parameters.
-
Add subscriptions that allow the connector to receive input data and send output data on supported topic filters.
Set the Lambda function as the source, the connector as the target, and use a supported input topic filter.
Set the connector as the source, Amazon IoT Core as the target, and use a supported output topic filter. You use this subscription to view status messages in the Amazon IoT console.
-
-
Deploy the group.
-
In the Amazon IoT console, on the Test page, subscribe to the output data topic to view status messages from the connector. The example Lambda function is long-lived and starts sending messages immediately after the group is deployed.
When you're finished testing, you can set the Lambda lifecycle to on-demand (or
"Pinned": false
in the CLI) and deploy the group. This stops the function from sending messages.
Example
The following example Lambda function sends an input message to the connector. This example triggers a text message.
import greengrasssdk import json iot_client = greengrasssdk.client('iot-data') TXT_INPUT_TOPIC = 'twilio/txt' CALL_INPUT_TOPIC = 'twilio/call' def publish_basic_message(): txt = { "request": { "recipient" : { "name": "Darla", "phone_number": "+12345000000", "message": 'Hello from the edge' }, "from_number" : "+19999999999" }, "id" : "request123" } print("Message To Publish: ", txt) client.publish(topic=TXT_INPUT_TOPIC, payload=json.dumps(txt)) publish_basic_message() def lambda_handler(event, context): return
Licenses
The Twilio Notifications connector includes the following third-party software/licensing:
twilio-python
/MIT
This connector is released under the
Greengrass Core Software License Agreement
Changelog
The following table describes the changes in each version of the connector.
Version |
Changes |
---|---|
5 |
Added the |
4 |
Upgraded the Lambda runtime to Python 3.7, which changes the runtime requirement. |
3 |
Fix to reduce excessive logging. |
2 |
Minor bug fixes and improvements. |
1 |
Initial release. |
A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.