Amazon Pinpoint SMS Voice V2

2024/09/24 - Amazon Pinpoint SMS Voice V2 - 3 new 4 updated api methods

Changes  AWS End User Messaging SMS-Voice V2 has added support for resource policies. Use the three new APIs to create, view, edit, and delete resource policies.

PutResourcePolicy (new) Link ¶

Attaches a resource-based policy to a AWS End User Messaging SMS and Voice resource(phone number, sender Id, phone poll, or opt-out list) that is used for sharing the resource. A shared resource can be a Pool, Opt-out list, Sender Id, or Phone number. For more information about resource-based policies, see Working with shared resources in the AWS End User Messaging SMS User Guide .

See also: AWS API Documentation

Request Syntax

client.put_resource_policy(
    ResourceArn='string',
    Policy='string'
)
type ResourceArn

string

param ResourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource to attach the resource-based policy to.

type Policy

string

param Policy

[REQUIRED]

The JSON formatted resource-based policy to attach.

rtype

dict

returns

Response Syntax

{
    'ResourceArn': 'string',
    'Policy': 'string',
    'CreatedTimestamp': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • ResourceArn (string) --

      The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource attached to the resource-based policy.

    • Policy (string) --

      The JSON formatted Resource Policy.

    • CreatedTimestamp (datetime) --

      The time when the resource-based policy was created, in UNIX epoch time format.

DeleteResourcePolicy (new) Link ¶

Deletes the resource-based policy document attached to the AWS End User Messaging SMS and Voice resource. A shared resource can be a Pool, Opt-out list, Sender Id, or Phone number.

See also: AWS API Documentation

Request Syntax

client.delete_resource_policy(
    ResourceArn='string'
)
type ResourceArn

string

param ResourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource you're deleting the resource-based policy from.

rtype

dict

returns

Response Syntax

{
    'ResourceArn': 'string',
    'Policy': 'string',
    'CreatedTimestamp': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • ResourceArn (string) --

      The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource that the resource-based policy was deleted from.

    • Policy (string) --

      The JSON formatted resource-based policy that was deleted.

    • CreatedTimestamp (datetime) --

      The time when the resource-based policy was created, in UNIX epoch time format.

GetResourcePolicy (new) Link ¶

Retrieves the JSON text of the resource-based policy document attached to the AWS End User Messaging SMS and Voice resource. A shared resource can be a Pool, Opt-out list, Sender Id, or Phone number.

See also: AWS API Documentation

Request Syntax

client.get_resource_policy(
    ResourceArn='string'
)
type ResourceArn

string

param ResourceArn

[REQUIRED]

The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource attached to the resource-based policy.

rtype

dict

returns

Response Syntax

{
    'ResourceArn': 'string',
    'Policy': 'string',
    'CreatedTimestamp': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • ResourceArn (string) --

      The Amazon Resource Name (ARN) of the AWS End User Messaging SMS and Voice resource attached to the resource-based policy.

    • Policy (string) --

      The JSON formatted string that contains the resource-based policy attached to the AWS End User Messaging SMS and Voice resource.

    • CreatedTimestamp (datetime) --

      The time when the resource-based policy was created, in UNIX epoch time format.

DescribeOptOutLists (updated) Link ¶
Changes (request)
{'Owner': 'SELF | SHARED'}

Describes the specified opt-out list or all opt-out lists in your account.

If you specify opt-out list names, the output includes information for only the specified opt-out lists. Opt-out lists include only those that meet the filter criteria. If you don't specify opt-out list names or filters, the output includes information for all opt-out lists.

If you specify an opt-out list name that isn't valid, an error is returned.

See also: AWS API Documentation

Request Syntax

client.describe_opt_out_lists(
    OptOutListNames=[
        'string',
    ],
    NextToken='string',
    MaxResults=123,
    Owner='SELF'|'SHARED'
)
type OptOutListNames

list

param OptOutListNames

The OptOutLists to show the details of. This is an array of strings that can be either the OptOutListName or OptOutListArn.

Warning

If you are using a shared AWS End User Messaging SMS and Voice resource then you must use the full Amazon Resource Name(ARN).

  • (string) --

type NextToken

string

param NextToken

The token to be used for the next set of paginated results. You don't need to supply a value for this field in the initial request.

type MaxResults

integer

param MaxResults

The maximum number of results to return per each request.

type Owner

string

param Owner

Use SELF to filter the list of Opt-Out List to ones your account owns or use SHARED to filter on Opt-Out List shared with your account. The Owner and OptOutListNames parameters can't be used at the same time.

rtype

dict

returns

Response Syntax

{
    'OptOutLists': [
        {
            'OptOutListArn': 'string',
            'OptOutListName': 'string',
            'CreatedTimestamp': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • OptOutLists (list) --

      An array of OptOutListInformation objects that contain the details for the requested OptOutLists.

      • (dict) --

        The information for all OptOutList in an Amazon Web Services account.

        • OptOutListArn (string) --

          The Amazon Resource Name (ARN) of the OptOutList.

        • OptOutListName (string) --

          The name of the OptOutList.

        • CreatedTimestamp (datetime) --

          The time when the OutOutList was created, in UNIX epoch time format.

    • NextToken (string) --

      The token to be used for the next set of paginated results. If this field is empty then there are no more results.

DescribePhoneNumbers (updated) Link ¶
Changes (request)
{'Owner': 'SELF | SHARED'}

Describes the specified origination phone number, or all the phone numbers in your account.

If you specify phone number IDs, the output includes information for only the specified phone numbers. If you specify filters, the output includes information for only those phone numbers that meet the filter criteria. If you don't specify phone number IDs or filters, the output includes information for all phone numbers.

If you specify a phone number ID that isn't valid, an error is returned.

See also: AWS API Documentation

Request Syntax

client.describe_phone_numbers(
    PhoneNumberIds=[
        'string',
    ],
    Filters=[
        {
            'Name': 'status'|'iso-country-code'|'message-type'|'number-capability'|'number-type'|'two-way-enabled'|'self-managed-opt-outs-enabled'|'opt-out-list-name'|'deletion-protection-enabled'|'two-way-channel-arn',
            'Values': [
                'string',
            ]
        },
    ],
    NextToken='string',
    MaxResults=123,
    Owner='SELF'|'SHARED'
)
type PhoneNumberIds

list

param PhoneNumberIds

The unique identifier of phone numbers to find information about. This is an array of strings that can be either the PhoneNumberId or PhoneNumberArn.

Warning

If you are using a shared AWS End User Messaging SMS and Voice resource then you must use the full Amazon Resource Name(ARN).

  • (string) --

type Filters

list

param Filters

An array of PhoneNumberFilter objects to filter the results.

  • (dict) --

    The information for a phone number that meets a specified criteria.

    • Name (string) -- [REQUIRED]

      The name of the attribute to filter on.

    • Values (list) -- [REQUIRED]

      An array values to filter for.

      • (string) --

type NextToken

string

param NextToken

The token to be used for the next set of paginated results. You don't need to supply a value for this field in the initial request.

type MaxResults

integer

param MaxResults

The maximum number of results to return per each request.

type Owner

string

param Owner

Use SELF to filter the list of phone numbers to ones your account owns or use SHARED to filter on phone numbers shared with your account. The Owner and PhoneNumberIds parameters can't be used at the same time.

rtype

dict

returns

Response Syntax

{
    'PhoneNumbers': [
        {
            'PhoneNumberArn': 'string',
            'PhoneNumberId': 'string',
            'PhoneNumber': 'string',
            'Status': 'PENDING'|'ACTIVE'|'ASSOCIATING'|'DISASSOCIATING'|'DELETED',
            'IsoCountryCode': 'string',
            'MessageType': 'TRANSACTIONAL'|'PROMOTIONAL',
            'NumberCapabilities': [
                'SMS'|'VOICE'|'MMS',
            ],
            'NumberType': 'SHORT_CODE'|'LONG_CODE'|'TOLL_FREE'|'TEN_DLC'|'SIMULATOR',
            'MonthlyLeasingPrice': 'string',
            'TwoWayEnabled': True|False,
            'TwoWayChannelArn': 'string',
            'TwoWayChannelRole': 'string',
            'SelfManagedOptOutsEnabled': True|False,
            'OptOutListName': 'string',
            'DeletionProtectionEnabled': True|False,
            'PoolId': 'string',
            'RegistrationId': 'string',
            'CreatedTimestamp': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • PhoneNumbers (list) --

      An array of PhoneNumberInformation objects that contain the details for the requested phone numbers.

      • (dict) --

        The information for a phone number, in E.164 format, in an Amazon Web Services account.

        • PhoneNumberArn (string) --

          The Amazon Resource Name (ARN) associated with the phone number.

        • PhoneNumberId (string) --

          The unique identifier for the phone number.

        • PhoneNumber (string) --

          The phone number in E.164 format.

        • Status (string) --

          The current status of the phone number.

        • IsoCountryCode (string) --

          The two-character code, in ISO 3166-1 alpha-2 format, for the country or region.

        • MessageType (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.

        • NumberCapabilities (list) --

          Describes if the origination identity can be used for text messages, voice calls or both.

          • (string) --

        • NumberType (string) --

          The type of phone number.

        • MonthlyLeasingPrice (string) --

          The price, in US dollars, to lease the phone number.

        • TwoWayEnabled (boolean) --

          By default this is set to false. When set to true you can receive incoming text messages from your end recipients using the TwoWayChannelArn.

        • TwoWayChannelArn (string) --

          The Amazon Resource Name (ARN) of the two way channel.

        • TwoWayChannelRole (string) --

          An optional IAM Role Arn for a service to assume, to be able to post inbound SMS messages.

        • SelfManagedOptOutsEnabled (boolean) --

          When set to false an end recipient sends a message that begins with HELP or STOP to one of your dedicated numbers, AWS End User Messaging SMS and Voice 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 request. For more information see Self-managed opt-outs

        • OptOutListName (string) --

          The name of the OptOutList associated with the phone number.

        • DeletionProtectionEnabled (boolean) --

          When set to true the phone number can't be deleted.

        • PoolId (string) --

          The unique identifier of the pool associated with the phone number.

        • RegistrationId (string) --

          The unique identifier for the registration.

        • CreatedTimestamp (datetime) --

          The time when the phone number was created, in UNIX epoch time format.

    • NextToken (string) --

      The token to be used for the next set of paginated results. If this field is empty then there are no more results.

DescribePools (updated) Link ¶
Changes (request)
{'Owner': 'SELF | SHARED'}

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.

See also: AWS API Documentation

Request Syntax

client.describe_pools(
    PoolIds=[
        'string',
    ],
    Filters=[
        {
            'Name': 'status'|'message-type'|'two-way-enabled'|'self-managed-opt-outs-enabled'|'opt-out-list-name'|'shared-routes-enabled'|'deletion-protection-enabled'|'two-way-channel-arn',
            'Values': [
                'string',
            ]
        },
    ],
    NextToken='string',
    MaxResults=123,
    Owner='SELF'|'SHARED'
)
type PoolIds

list

param PoolIds

The unique identifier of pools to find. This is an array of strings that can be either the PoolId or PoolArn.

Warning

If you are using a shared AWS End User Messaging SMS and Voice resource then you must use the full Amazon Resource Name(ARN).

  • (string) --

type Filters

list

param Filters

An array of PoolFilter objects to filter the results.

  • (dict) --

    The information for a pool that meets a specified criteria.

    • Name (string) -- [REQUIRED]

      The name of the attribute to filter on.

    • Values (list) -- [REQUIRED]

      An array values to filter for.

      • (string) --

type NextToken

string

param NextToken

The token to be used for the next set of paginated results. You don't need to supply a value for this field in the initial request.

type MaxResults

integer

param MaxResults

The maximum number of results to return per each request.

type Owner

string

param Owner

Use SELF to filter the list of Pools to ones your account owns or use SHARED to filter on Pools shared with your account. The Owner and PoolIds parameters can't be used at the same time.

rtype

dict

returns

Response Syntax

{
    'Pools': [
        {
            'PoolArn': 'string',
            'PoolId': 'string',
            'Status': 'CREATING'|'ACTIVE'|'DELETING',
            'MessageType': 'TRANSACTIONAL'|'PROMOTIONAL',
            'TwoWayEnabled': True|False,
            'TwoWayChannelArn': 'string',
            'TwoWayChannelRole': 'string',
            'SelfManagedOptOutsEnabled': True|False,
            'OptOutListName': 'string',
            'SharedRoutesEnabled': True|False,
            'DeletionProtectionEnabled': True|False,
            'CreatedTimestamp': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Pools (list) --

      An array of PoolInformation objects that contain the details for the requested pools.

      • (dict) --

        The information for a pool in an Amazon Web Services account.

        • PoolArn (string) --

          The Amazon Resource Name (ARN) for the pool.

        • PoolId (string) --

          The unique identifier for the pool.

        • Status (string) --

          The current status of the pool.

        • MessageType (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.

        • TwoWayEnabled (boolean) --

          When set to true you can receive incoming text messages from your end recipients using the TwoWayChannelArn.

        • TwoWayChannelArn (string) --

          The Amazon Resource Name (ARN) of the two way channel.

        • TwoWayChannelRole (string) --

          An optional IAM Role Arn for a service to assume, to be able to post inbound SMS messages.

        • SelfManagedOptOutsEnabled (boolean) --

          When set to false, an end recipient sends a message that begins with HELP or STOP to one of your dedicated numbers, AWS End User Messaging SMS and Voice 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

        • OptOutListName (string) --

          The name of the OptOutList associated with the pool.

        • SharedRoutesEnabled (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.

        • DeletionProtectionEnabled (boolean) --

          When set to true the pool can't be deleted.

        • CreatedTimestamp (datetime) --

          The time when the pool was created, in UNIX epoch time format.

    • NextToken (string) --

      The token to be used for the next set of paginated results. If this field is empty then there are no more results.

DescribeSenderIds (updated) Link ¶
Changes (request)
{'Owner': 'SELF | SHARED'}

Describes the specified SenderIds or all SenderIds associated with your Amazon Web Services account.

If you specify SenderIds, the output includes information for only the specified SenderIds. If you specify filters, the output includes information for only those SenderIds that meet the filter criteria. If you don't specify SenderIds or filters, the output includes information for all SenderIds.

f you specify a sender ID that isn't valid, an error is returned.

See also: AWS API Documentation

Request Syntax

client.describe_sender_ids(
    SenderIds=[
        {
            'SenderId': 'string',
            'IsoCountryCode': 'string'
        },
    ],
    Filters=[
        {
            'Name': 'sender-id'|'iso-country-code'|'message-type'|'deletion-protection-enabled'|'registered',
            'Values': [
                'string',
            ]
        },
    ],
    NextToken='string',
    MaxResults=123,
    Owner='SELF'|'SHARED'
)
type SenderIds

list

param SenderIds

An array of SenderIdAndCountry objects to search for.

Warning

If you are using a shared AWS End User Messaging SMS and Voice resource then you must use the full Amazon Resource Name(ARN).

  • (dict) --

    The alphanumeric sender ID in a specific country that you want to describe. For more information on sender IDs see Requesting sender IDs in the AWS End User Messaging SMS User Guide .

    • SenderId (string) -- [REQUIRED]

      The unique identifier of the sender.

    • IsoCountryCode (string) -- [REQUIRED]

      The two-character code, in ISO 3166-1 alpha-2 format, for the country or region.

type Filters

list

param Filters

An array of SenderIdFilter objects to filter the results.

  • (dict) --

    The information for a sender ID that meets a specified criteria.

    • Name (string) -- [REQUIRED]

      The name of the attribute to filter on.

    • Values (list) -- [REQUIRED]

      An array of values to filter for.

      • (string) --

type NextToken

string

param NextToken

The token to be used for the next set of paginated results. You don't need to supply a value for this field in the initial request.

type MaxResults

integer

param MaxResults

The maximum number of results to return per each request.

type Owner

string

param Owner

Use SELF to filter the list of Sender Ids to ones your account owns or use SHARED to filter on Sender Ids shared with your account. The Owner and SenderIds parameters can't be used at the same time.

rtype

dict

returns

Response Syntax

{
    'SenderIds': [
        {
            'SenderIdArn': 'string',
            'SenderId': 'string',
            'IsoCountryCode': 'string',
            'MessageTypes': [
                'TRANSACTIONAL'|'PROMOTIONAL',
            ],
            'MonthlyLeasingPrice': 'string',
            'DeletionProtectionEnabled': True|False,
            'Registered': True|False,
            'RegistrationId': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • SenderIds (list) --

      An array of SernderIdInformation objects that contain the details for the requested SenderIds.

      • (dict) --

        The information for all SenderIds in an Amazon Web Services account.

        • SenderIdArn (string) --

          The Amazon Resource Name (ARN) associated with the SenderId.

        • SenderId (string) --

          The alphanumeric sender ID in a specific country that you'd like to describe.

        • IsoCountryCode (string) --

          The two-character code, in ISO 3166-1 alpha-2 format, for the country or region.

        • MessageTypes (list) --

          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.

          • (string) --

        • MonthlyLeasingPrice (string) --

          The monthly leasing price, in US dollars.

        • DeletionProtectionEnabled (boolean) --

          By default this is set to false. When set to true the sender ID can't be deleted.

        • Registered (boolean) --

          True if the sender ID is registered.

        • RegistrationId (string) --

          The unique identifier for the registration.

    • NextToken (string) --

      The token to be used for the next set of paginated results. If this field is empty then there are no more results.