pools

Creates, updates, deletes, gets or lists a pools resource.

Overview

Name	pools
Type	Resource
Id	aws.pinpoint_sms_voice_v2.pools

Fields

The following fields are returned by SELECT queries:

describe_pools

Name	Datatype	Description
created_timestamp	string (date-time)	The time when the pool was created, in UNIX epoch time format.
deletion_protection_enabled	boolean	When set to true the pool can't be deleted.
message_type	string	The type of message. Valid values are TRANSACTIONAL for messages that are critical or time-sensitive and PROMOTIONAL for messages that aren't critical or time-sensitive. (TRANSACTIONAL, PROMOTIONAL)
opt_out_list_name	string	The name of the OptOutList associated with the pool. (pattern: <code>[A-Za-z0-9_-]+</code>)
pool_arn	string	The Amazon Resource Name (ARN) for the pool.
pool_id	string	The unique identifier for the pool.
self_managed_opt_outs_enabled	boolean	When set to false, an end recipient sends a message that begins with HELP or STOP to one of your dedicated numbers, End User Messaging SMS automatically replies with a customizable message and adds the end recipient to the OptOutList. When set to true you're responsible for responding to HELP and STOP requests. You're also responsible for tracking and honoring opt-out requests. For more information see Self-managed opt-outs
shared_routes_enabled	boolean	Allows you to enable shared routes on your pool. By default, this is set to False. If you set this value to True, your messages are sent using phone numbers or sender IDs (depending on the country) that are shared with other users. In some countries, such as the United States, senders aren't allowed to use shared routes and must use a dedicated phone number or short code.
status	string	The current status of the pool. (CREATING, ACTIVE, DELETING)
two_way_channel_arn	string	The Amazon Resource Name (ARN) of the two way channel. (pattern: <code>\S+</code>)
two_way_channel_role	string	An optional IAM Role Arn for a service to assume, to be able to post inbound SMS messages. (pattern: <code>arn:\S+</code>)
two_way_enabled	boolean	When set to true you can receive incoming text messages from your end recipients using the TwoWayChannelArn.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_pools	select	region		Retrieves the specified pools or all pools associated with your Amazon Web Services account. If you specify pool IDs, the output includes information for only the specified pools. If you specify filters, the output includes information for only those pools that meet the filter criteria. If you don't specify pool IDs or filters, the output includes information for all pools. If you specify a pool ID that isn't valid, an error is returned. A pool is a collection of phone numbers and SenderIds. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account.
create_pool	insert	region, OriginationIdentity, MessageType		Creates a new pool and associates the specified origination identity to the pool. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account. The new pool inherits its configuration from the specified origination identity. This includes keywords, message type, opt-out list, two-way configuration, and self-managed opt-out configuration. Deletion protection isn't inherited from the origination identity and defaults to false. If the origination identity is a phone number and is already associated with another pool, an error is returned. A sender ID can be associated with multiple pools.
associate_origination_identity	update	region, PoolId, OriginationIdentity		Associates the specified origination identity with a pool. If the origination identity is a phone number and is already associated with another pool, an error is returned. A sender ID can be associated with multiple pools. If the origination identity configuration doesn't match the pool's configuration, an error is returned.
update_pool	update	region, PoolId		Updates the configuration of an existing pool. You can update the opt-out list, enable or disable two-way messaging, change the TwoWayChannelArn, enable or disable self-managed opt-outs, enable or disable deletion protection, and enable or disable shared routes.
delete_pool	delete	region		Deletes an existing pool. Deleting a pool disassociates all origination identities from that pool. If the pool status isn't active or if deletion protection is enabled, an error is returned. A pool is a collection of phone numbers and SenderIds. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account.
disassociate_origination_identity	exec	region, PoolId, OriginationIdentity		Removes the specified origination identity from an existing pool. If the origination identity isn't associated with the specified pool, an error is returned.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_pools

Retrieves the specified pools or all pools associated with your Amazon Web Services account. If you specify pool IDs, the output includes information for only the specified pools. If you specify filters, the output includes information for only those pools that meet the filter criteria. If you don't specify pool IDs or filters, the output includes information for all pools. If you specify a pool ID that isn't valid, an error is returned. A pool is a collection of phone numbers and SenderIds. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account.

SELECT
created_timestamp,
deletion_protection_enabled,
message_type,
opt_out_list_name,
pool_arn,
pool_id,
self_managed_opt_outs_enabled,
shared_routes_enabled,
status,
two_way_channel_arn,
two_way_channel_role,
two_way_enabled
FROM aws.pinpoint_sms_voice_v2.pools
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_pool

Creates a new pool and associates the specified origination identity to the pool. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account. The new pool inherits its configuration from the specified origination identity. This includes keywords, message type, opt-out list, two-way configuration, and self-managed opt-out configuration. Deletion protection isn't inherited from the origination identity and defaults to false. If the origination identity is a phone number and is already associated with another pool, an error is returned. A sender ID can be associated with multiple pools.

INSERT INTO aws.pinpoint_sms_voice_v2.pools (
OriginationIdentity,
IsoCountryCode,
MessageType,
DeletionProtectionEnabled,
Tags,
ClientToken,
region
)
SELECT 
'{{ OriginationIdentity }}' /* required */,
'{{ IsoCountryCode }}',
'{{ MessageType }}' /* required */,
{{ DeletionProtectionEnabled }},
'{{ Tags }}',
'{{ ClientToken }}',
'{{ region }}'
RETURNING
created_timestamp,
deletion_protection_enabled,
message_type,
opt_out_list_name,
pool_arn,
pool_id,
self_managed_opt_outs_enabled,
shared_routes_enabled,
status,
tags,
two_way_channel_arn,
two_way_channel_role,
two_way_enabled
;

Manifest

# Description fields are for documentation purposes
- name: pools
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the pools resource.
  - name: OriginationIdentity
    value: "{{ OriginationIdentity }}"
    description: |
      The origination identity to use such as a PhoneNumberId, PhoneNumberArn, SenderId or SenderIdArn. You can use DescribePhoneNumbers to find the values for PhoneNumberId and PhoneNumberArn, and use DescribeSenderIds can be used to get the values for SenderId and SenderIdArn. After the pool is created you can add more origination identities to the pool by using AssociateOriginationIdentity. If you are using a shared End User Messaging SMS resource then you must use the full Amazon Resource Name(ARN).
  - name: IsoCountryCode
    value: "{{ IsoCountryCode }}"
    description: |
      The new two-character code, in ISO 3166-1 alpha-2 format, for the country or region of the new pool. This field is optional and is not required for origination identity types that are not country-specific, such as RCS agents.
  - name: MessageType
    value: "{{ MessageType }}"
    description: |
      The type of message. Valid values are TRANSACTIONAL for messages that are critical or time-sensitive and PROMOTIONAL for messages that aren't critical or time-sensitive. After the pool is created the MessageType can't be changed.
    valid_values: ['TRANSACTIONAL', 'PROMOTIONAL']
  - name: DeletionProtectionEnabled
    value: {{ DeletionProtectionEnabled }}
    description: |
      By default this is set to false. When set to true the pool can't be deleted. You can change this value using the UpdatePool action.
  - name: Tags
    description: |
      An array of tags (key and value pairs) associated with the pool.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If you don't specify a client token, a randomly generated token is used for the request to ensure idempotency.

UPDATE examples

associate_origination_identity

Associates the specified origination identity with a pool. If the origination identity is a phone number and is already associated with another pool, an error is returned. A sender ID can be associated with multiple pools. If the origination identity configuration doesn't match the pool's configuration, an error is returned.

UPDATE aws.pinpoint_sms_voice_v2.pools
SET 
PoolId = '{{ PoolId }}',
OriginationIdentity = '{{ OriginationIdentity }}',
IsoCountryCode = '{{ IsoCountryCode }}',
ClientToken = '{{ ClientToken }}'
WHERE 
region = '{{ region }}' --required
AND PoolId = '{{ PoolId }}' --required
AND OriginationIdentity = '{{ OriginationIdentity }}' --required
RETURNING
iso_country_code,
origination_identity,
origination_identity_arn,
pool_arn,
pool_id;

update_pool

Updates the configuration of an existing pool. You can update the opt-out list, enable or disable two-way messaging, change the TwoWayChannelArn, enable or disable self-managed opt-outs, enable or disable deletion protection, and enable or disable shared routes.

UPDATE aws.pinpoint_sms_voice_v2.pools
SET 
PoolId = '{{ PoolId }}',
TwoWayEnabled = {{ TwoWayEnabled }},
TwoWayChannelArn = '{{ TwoWayChannelArn }}',
TwoWayChannelRole = '{{ TwoWayChannelRole }}',
SelfManagedOptOutsEnabled = {{ SelfManagedOptOutsEnabled }},
OptOutListName = '{{ OptOutListName }}',
SharedRoutesEnabled = {{ SharedRoutesEnabled }},
DeletionProtectionEnabled = {{ DeletionProtectionEnabled }}
WHERE 
region = '{{ region }}' --required
AND PoolId = '{{ PoolId }}' --required
RETURNING
created_timestamp,
deletion_protection_enabled,
message_type,
opt_out_list_name,
pool_arn,
pool_id,
self_managed_opt_outs_enabled,
shared_routes_enabled,
status,
two_way_channel_arn,
two_way_channel_role,
two_way_enabled;

DELETE examples

delete_pool

Deletes an existing pool. Deleting a pool disassociates all origination identities from that pool. If the pool status isn't active or if deletion protection is enabled, an error is returned. A pool is a collection of phone numbers and SenderIds. A pool can include one or more phone numbers and SenderIds that are associated with your Amazon Web Services account.

DELETE FROM aws.pinpoint_sms_voice_v2.pools
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

disassociate_origination_identity

Removes the specified origination identity from an existing pool. If the origination identity isn't associated with the specified pool, an error is returned.

EXEC aws.pinpoint_sms_voice_v2.pools.disassociate_origination_identity 
@region='{{ region }}' --required 
@@json=
'{
"PoolId": "{{ PoolId }}", 
"OriginationIdentity": "{{ OriginationIdentity }}", 
"IsoCountryCode": "{{ IsoCountryCode }}", 
"ClientToken": "{{ ClientToken }}"
}'
;