2026/09/08 - Amazon Pinpoint SMS Voice V2 - 1 new 4 updated api methods
Changes This feature will allow customers to specify an area-code when requesting a 10DLC number. Why it matters- Customers can now select a number that matches where their business is located.
Search available phone numbers from aggregator inventory, optionally filtered by pattern. If NumberPreference is omitted, returns unfiltered available numbers. Returns empty list (not an exception) when no numbers match. ResourceNotFoundException is thrown only for invalid RegistrationId (campaign not found).
See also: AWS API Documentation
Request Syntax
client.list_available_phone_numbers(
IsoCountryCode='string',
NumberCapabilities=[
'SMS'|'VOICE'|'MMS'|'RCS',
],
NumberType='TEN_DLC',
RegistrationId='string',
NumberPreference=[
{
'PreferenceType': [
'StartsWith'|'EndsWith'|'Contains'|'ExactMatch',
],
'Filter': [
'string',
]
},
],
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The two-character code, in ISO 3166-1 alpha-2 format, for the country or region in which to search for available phone numbers. This operation currently supports only US.
list
[REQUIRED]
The capabilities to filter by, such as SMS. Only phone numbers that support all of the specified capabilities are returned.
(string) --
string
[REQUIRED]
The type of phone number to search for.
string
The registration associated with the request. A registration is required for regulated number types. You can specify either:
The unique identifier of the registration.
The Amazon Resource Name (ARN) of the registration.
list
Optional. If omitted, returns unfiltered available numbers. Max 1 element for List API.
(dict) --
A single number preference — specifies a pattern type and filter value.
PreferenceType (list) -- [REQUIRED]
The type of match to apply to the filter values.
StartsWith: Returns numbers that begin with the filter value.
EndsWith: Returns numbers that end with the filter value.
Contains: Returns numbers that contain the filter value.
ExactMatch: Returns the number that exactly matches the filter value.
(string) --
The type of pattern matching to apply.
Filter (list) -- [REQUIRED]
The digit pattern values to match against available phone numbers, using the specified preference type.
(string) --
A filter value — either a pattern (e.g., "+1510") or full E.164 number.
string
The token returned from a previous request to retrieve the next page of results.
integer
The maximum number of results to return per page. If you don't specify a value, the default is 10.
dict
Response Syntax
{
'AvailablePhoneNumbers': [
'string',
],
'NextToken': 'string'
}
Response Structure
(dict) --
AvailablePhoneNumbers (list) --
An array of phone numbers, in E.164 format, that are available to request based on the specified filters.
(string) --
NextToken (string) --
The token to include in the next request to retrieve the next page of results. This value is null when there are no more results.
{'PhoneNumbers': {'MessagingLimits': {'DailyMessageCaps': {'string': 'long'},
'RateLimits': {'string': 'long'}}}}
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'
)
list
The unique identifier of phone numbers to find information about. This is an array of strings that can be either the PhoneNumberId or PhoneNumberArn.
(string) --
list
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) --
string
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.
integer
The maximum number of results to return per each request.
string
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.
dict
Response Syntax
{
'PhoneNumbers': [
{
'PhoneNumberArn': 'string',
'PhoneNumberId': 'string',
'PhoneNumber': 'string',
'Status': 'PENDING'|'ACTIVE'|'ASSOCIATING'|'DISASSOCIATING'|'DELETED',
'IsoCountryCode': 'string',
'MessageType': 'TRANSACTIONAL'|'PROMOTIONAL',
'NumberCapabilities': [
'SMS'|'VOICE'|'MMS'|'RCS',
],
'NumberType': 'SHORT_CODE'|'LONG_CODE'|'TOLL_FREE'|'TEN_DLC'|'SIMULATOR',
'MonthlyLeasingPrice': 'string',
'TwoWayEnabled': True|False,
'TwoWayChannelArn': 'string',
'TwoWayChannelRole': 'string',
'SelfManagedOptOutsEnabled': True|False,
'OptOutListName': 'string',
'InternationalSendingEnabled': True|False,
'DeletionProtectionEnabled': True|False,
'PoolId': 'string',
'RegistrationId': 'string',
'MessagingLimits': {
'RateLimits': {
'string': 123
},
'DailyMessageCaps': {
'string': 123
}
},
'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 and 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 request. For more information see Self-managed opt-outs
OptOutListName (string) --
The name of the OptOutList associated with the phone number.
InternationalSendingEnabled (boolean) --
When set to true the international sending of phone number is Enabled.
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.
MessagingLimits (dict) --
The messaging limits that apply to the phone number, including the per-capability send rates and any advisory per-provider daily message caps.
RateLimits (dict) --
The maximum send rate for each supported capability, in messages per second. The map is keyed by capability, such as SMS, MMS, VOICE, or RCS.
(string) --
(integer) --
DailyMessageCaps (dict) --
The advisory maximum number of messages that can be sent per day, keyed by provider (for example, T-MOBILE). Applies to 10DLC phone numbers and is omitted when no daily cap applies.
(string) --
(integer) --
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.
{'RcsAgents': {'MessagingLimits': {'DailyMessageCaps': {'string': 'long'},
'RateLimits': {'string': 'long'}}}}
Retrieves the specified RCS agents or all RCS agents associated with your Amazon Web Services account.
If you specify RCS agent IDs, the output includes information for only the specified RCS agents. If you specify filters, the output includes information for only those RCS agents that meet the filter criteria. If you don't specify RCS agent IDs or filters, the output includes information for all RCS agents.
See also: AWS API Documentation
Request Syntax
client.describe_rcs_agents(
RcsAgentIds=[
'string',
],
Owner='SELF'|'SHARED',
Filters=[
{
'Name': 'status'|'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
)
list
An array of unique identifiers for the RCS agents. This is an array of strings that can be either the RcsAgentId or RcsAgentArn.
(string) --
string
Use SELF to filter the list of RCS agents to ones your account owns or use SHARED to filter on RCS agents shared with your account. The Owner and RcsAgentIds parameters can't be used at the same time.
list
An array of RcsAgentFilter objects to filter the results.
(dict) --
The information for an RCS agent 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) --
string
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.
integer
The maximum number of results to return per each request.
dict
Response Syntax
{
'RcsAgents': [
{
'RcsAgentArn': 'string',
'RcsAgentId': 'string',
'Status': 'CREATED'|'PENDING'|'TESTING'|'PARTIAL'|'ACTIVE'|'DELETED',
'CreatedTimestamp': datetime(2015, 1, 1),
'DeletionProtectionEnabled': True|False,
'OptOutListName': 'string',
'SelfManagedOptOutsEnabled': True|False,
'TwoWayChannelArn': 'string',
'TwoWayChannelRole': 'string',
'TwoWayEnabled': True|False,
'PoolId': 'string',
'TwoWayMediaS3BucketName': 'string',
'TwoWayMediaS3KeyPrefix': 'string',
'TwoWayMediaS3Role': 'string',
'TwoWayRcsEventsEnabled': [
'string',
],
'TestingAgent': {
'Status': 'CREATED'|'PENDING'|'ACTIVE',
'TestingAgentId': 'string',
'RegistrationId': 'string'
},
'MessagingLimits': {
'RateLimits': {
'string': 123
},
'DailyMessageCaps': {
'string': 123
}
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
RcsAgents (list) --
An array of RcsAgentInformation objects that contain the details for the requested RCS agents.
(dict) --
The information for an RCS agent in an Amazon Web Services account.
RcsAgentArn (string) --
The Amazon Resource Name (ARN) of the RCS agent.
RcsAgentId (string) --
The unique identifier for the RCS agent.
Status (string) --
The current status of the RCS agent.
CreatedTimestamp (datetime) --
The time when the RCS agent was created, in UNIX epoch time format.
DeletionProtectionEnabled (boolean) --
When set to true the RCS agent can't be deleted.
OptOutListName (string) --
The name of the OptOutList associated with the RCS agent.
SelfManagedOptOutsEnabled (boolean) --
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.
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.
TwoWayEnabled (boolean) --
When set to true you can receive incoming text messages from your end recipients using the TwoWayChannelArn.
PoolId (string) --
The unique identifier of the pool associated with the RCS agent.
TwoWayMediaS3BucketName (string) --
The name of the S3 bucket where inbound RCS media files are stored.
TwoWayMediaS3KeyPrefix (string) --
The key prefix used for inbound RCS media objects in the S3 bucket.
TwoWayMediaS3Role (string) --
The ARN of the IAM role used to write inbound RCS media files to the S3 bucket.
TwoWayRcsEventsEnabled (list) --
The list of RCS event types enabled for two-way messaging on the agent.
(string) --
RCS event type identifier. Validated at the service layer.
TestingAgent (dict) --
The testing agent information associated with the RCS agent.
Status (string) --
The current status of the testing agent.
TestingAgentId (string) --
The unique identifier for the testing agent.
RegistrationId (string) --
The unique identifier of the registration associated with the testing agent.
MessagingLimits (dict) --
The messaging limits that apply to the RCS agent, including the per-capability send rates.
RateLimits (dict) --
The maximum send rate for each supported capability, in messages per second. The map is keyed by capability, such as SMS, MMS, VOICE, or RCS.
(string) --
(integer) --
DailyMessageCaps (dict) --
The advisory maximum number of messages that can be sent per day, keyed by provider (for example, T-MOBILE). Applies to 10DLC phone numbers and is omitted when no daily cap applies.
(string) --
(integer) --
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.
{'SenderIds': {'MessagingLimits': {'DailyMessageCaps': {'string': 'long'},
'RateLimits': {'string': 'long'}}}}
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'
)
list
An array of SenderIdAndCountry objects to search for.
(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 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.
list
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) --
string
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.
integer
The maximum number of results to return per each request.
string
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.
dict
Response Syntax
{
'SenderIds': [
{
'SenderIdArn': 'string',
'SenderId': 'string',
'IsoCountryCode': 'string',
'MessageTypes': [
'TRANSACTIONAL'|'PROMOTIONAL',
],
'MonthlyLeasingPrice': 'string',
'DeletionProtectionEnabled': True|False,
'Registered': True|False,
'RegistrationId': 'string',
'MessagingLimits': {
'RateLimits': {
'string': 123
},
'DailyMessageCaps': {
'string': 123
}
}
},
],
'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.
MessagingLimits (dict) --
The messaging limits that apply to the sender ID, including the per-capability send rates.
RateLimits (dict) --
The maximum send rate for each supported capability, in messages per second. The map is keyed by capability, such as SMS, MMS, VOICE, or RCS.
(string) --
(integer) --
DailyMessageCaps (dict) --
The advisory maximum number of messages that can be sent per day, keyed by provider (for example, T-MOBILE). Applies to 10DLC phone numbers and is omitted when no daily cap applies.
(string) --
(integer) --
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.
{'NumberPreference': [{'Filter': ['string'],
'PreferenceType': ['StartsWith | EndsWith | Contains | '
'ExactMatch']}]}
Request an origination phone number for use in your account. For more information on phone number request see Request a phone number in the End User Messaging SMS User Guide.
See also: AWS API Documentation
Request Syntax
client.request_phone_number(
IsoCountryCode='string',
MessageType='TRANSACTIONAL'|'PROMOTIONAL',
NumberCapabilities=[
'SMS'|'VOICE'|'MMS'|'RCS',
],
NumberType='LONG_CODE'|'TOLL_FREE'|'TEN_DLC'|'SIMULATOR',
OptOutListName='string',
PoolId='string',
RegistrationId='string',
NumberPreference=[
{
'PreferenceType': [
'StartsWith'|'EndsWith'|'Contains'|'ExactMatch',
],
'Filter': [
'string',
]
},
],
InternationalSendingEnabled=True|False,
DeletionProtectionEnabled=True|False,
Tags=[
{
'Key': 'string',
'Value': 'string'
},
],
ClientToken='string'
)
string
[REQUIRED]
The two-character code, in ISO 3166-1 alpha-2 format, for the country or region.
string
[REQUIRED]
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.
list
[REQUIRED]
Indicates if the phone number will be used for text messages, voice messages, or both.
(string) --
string
[REQUIRED]
The type of phone number to request.
When you request a SIMULATOR phone number, you must set MessageType as TRANSACTIONAL.
string
The name of the OptOutList to associate with the phone number. You can use the OptOutListName or OptOutListArn.
string
The pool to associated with the phone number. You can use the PoolId or PoolArn.
string
Use this field to attach your phone number for an external registration process.
list
An optional selection preference used to request a specific phone number, such as a number that starts with, ends with, or contains a particular digit pattern. You can specify at most one preference. Number preferences apply only to TEN_DLC requests in the US.
(dict) --
A single number preference — specifies a pattern type and filter value.
PreferenceType (list) -- [REQUIRED]
The type of match to apply to the filter values.
StartsWith: Returns numbers that begin with the filter value.
EndsWith: Returns numbers that end with the filter value.
Contains: Returns numbers that contain the filter value.
ExactMatch: Returns the number that exactly matches the filter value.
(string) --
The type of pattern matching to apply.
Filter (list) -- [REQUIRED]
The digit pattern values to match against available phone numbers, using the specified preference type.
(string) --
A filter value — either a pattern (e.g., "+1510") or full E.164 number.
boolean
By default this is set to false. When set to true the international sending of phone number is Enabled.
boolean
By default this is set to false. When set to true the phone number can't be deleted.
list
An array of tags (key and value pairs) to associate with the requested phone number.
(dict) --
The list of tags to be added to the specified topic.
Key (string) -- [REQUIRED]
The key identifier, or name, of the tag.
Value (string) -- [REQUIRED]
The string value associated with the key of the tag.
string
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.
This field is autopopulated if not provided.
dict
Response Syntax
{
'PhoneNumberArn': 'string',
'PhoneNumberId': 'string',
'PhoneNumber': 'string',
'Status': 'PENDING'|'ACTIVE'|'ASSOCIATING'|'DISASSOCIATING'|'DELETED',
'IsoCountryCode': 'string',
'MessageType': 'TRANSACTIONAL'|'PROMOTIONAL',
'NumberCapabilities': [
'SMS'|'VOICE'|'MMS'|'RCS',
],
'NumberType': 'LONG_CODE'|'TOLL_FREE'|'TEN_DLC'|'SIMULATOR',
'MonthlyLeasingPrice': 'string',
'TwoWayEnabled': True|False,
'TwoWayChannelArn': 'string',
'TwoWayChannelRole': 'string',
'SelfManagedOptOutsEnabled': True|False,
'OptOutListName': 'string',
'InternationalSendingEnabled': True|False,
'DeletionProtectionEnabled': True|False,
'PoolId': 'string',
'RegistrationId': 'string',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'CreatedTimestamp': datetime(2015, 1, 1)
}
Response Structure
(dict) --
PhoneNumberArn (string) --
The Amazon Resource Name (ARN) of the requested phone number.
PhoneNumberId (string) --
The unique identifier of the new phone number.
PhoneNumber (string) --
The new phone number that was requested.
Status (string) --
The current status of the request.
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) --
Indicates if the phone number will be used for text messages, voice messages or both.
(string) --
NumberType (string) --
The type of number that was released.
MonthlyLeasingPrice (string) --
The monthly 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.
TwoWayChannelArn (string) --
The ARN used to identify 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) --
By default this is set to false. When set to false and 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.
OptOutListName (string) --
The name of the OptOutList that is associated with the requested phone number.
InternationalSendingEnabled (boolean) --
By default this is set to false. When set to true the international sending of phone number is Enabled.
DeletionProtectionEnabled (boolean) --
By default this is set to false. 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.
Tags (list) --
An array of key and value pair tags that are associated with the phone number.
(dict) --
The list of tags to be added to the specified topic.
Key (string) --
The key identifier, or name, of the tag.
Value (string) --
The string value associated with the key of the tag.
CreatedTimestamp (datetime) --
The time when the phone number was created, in UNIX epoch time format.