View a markdown version of this page

使用通知傳送訊息 - AWS 最終使用者傳訊簡訊
傳送簡訊訊息傳送語音訊息使用 DryRun 模式傳送請求參數訊息路由的運作方式訊息回饋交付事件錯誤處理重要說明疑難排解

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用通知傳送訊息

通知提供兩個用於傳送訊息APIs：

  • SendNotifyTextMessage – 使用預先核准的範本傳送簡訊。

  • SendNotifyVoiceMessage – 傳送語音呼叫，以使用text-to-speech讀取範本內容。

傳送簡訊訊息

Console

  1. 在 https：//https://console.aws.amazon.com/sms-voice/ 開啟 AWS 最終使用者傳訊簡訊主控台。

  2. 導覽至通知組態，然後選擇測試索引標籤。

  3. 針對頻道，選取文字。

  4. 從範本資料表中選取範本。

  5. 以 E.164 格式輸入目的地電話號碼。

  6. 填寫範本變數。

  7. 選擇傳送。

AWS CLI
aws pinpoint-sms-voice-v2 send-notify-text-message \
  --notify-configuration-id nc-1234567890abcdef0 \
  --destination-phone-number +12065550100 \
  --template-id notify-code-verification-english-001 \
  --template-variables '{"code":"123456"}'
Python (boto3)
import boto3

client = boto3.client('pinpoint-sms-voice-v2')

response = client.send_notify_text_message(
    NotifyConfigurationId='nc-1234567890abcdef0',
    DestinationPhoneNumber='+12065550100',
    TemplateId='notify-code-verification-english-001',
    TemplateVariables={
        'code': '123456'
    }
)

print(f"Message sent. MessageId: {response['MessageId']}")
print(f"Resolved body: {response.get('ResolvedMessageBody')}")

傳送語音訊息

語音訊息需要在通知組態上啟用VOICE頻道。

提示

對於語音訊息，請以句點或空格分隔數字 （例如 "1. 2. 3. 4. 5. 6.")，讓text-to-speech引擎個別讀取每個數字，而非單一數字。

Console

  1. 在 https：//https://console.aws.amazon.com/sms-voice/ 開啟 AWS 最終使用者傳訊簡訊主控台。

  2. 導覽至通知組態，然後選擇測試索引標籤。

  3. 針對頻道，選取語音。

  4. 從範本資料表中選取語音範本。

  5. 輸入目的地電話號碼並填入範本變數。

  6. 選擇傳送。

AWS CLI
aws pinpoint-sms-voice-v2 send-notify-voice-message \
  --notify-configuration-id nc-1234567890abcdef0 \
  --destination-phone-number +12065550100 \
  --template-id notify-code-verification-english-001 \
  --template-variables '{"code":"123456"}' \
  --voice-id JOANNA

使用 DryRun 模式

DryRun 設定為 true 以驗證傳送請求，而不實際傳遞訊息。DryRun 模式會檢查範本變數驗證、國家/地區限制和花費限制，但不傳送訊息或從您的花費限制中扣除。

aws pinpoint-sms-voice-v2 send-notify-text-message \
  --notify-configuration-id nc-1234567890abcdef0 \
  --destination-phone-number +12065550100 \
  --template-id notify-code-verification-english-001 \
  --template-variables '{"code":"123456"}' \
  --dry-run

傳送請求參數

SendNotifyTextMessage 和 都SendNotifyVoiceMessage接受下列參數：

NotifyConfigurationId （必要）

通知組態的 ID 或 ARN。

DestinationPhoneNumber （必要）

收件人的 E.164 格式電話號碼。

TemplateVariables （必要）

變數名稱與值的映射。所有值都是字串，即使是整數或布林值變數也是如此。

TemplateId

要使用的範本。如果省略，則會使用組態的預設範本。

ConfigurationSetName

事件路由的組態設定。

Context

包含在事件記錄中的鍵/值對。

DryRun

驗證請求而不傳送。

TimeToLive

訊息的有效時間長度，以秒為單位。預設為 72 小時。

MessageFeedbackEnabled

透過 PutMessageFeedback API 啟用訊息意見回饋追蹤。

VoiceId （僅限語音）

要使用的 Amazon Polly 語音 （例如 JOANNA、)MATTHEW。

訊息路由的運作方式

AWS 會根據目的地國家/地區，自動為每個訊息選取最佳起始身分。如果您已將電話集區與通知組態建立關聯，則會先嘗試集區中客戶擁有的身分。如果沒有適當的客戶擁有的身分可用，則會使用 AWS受管身分做為備用身分。

訊息回饋

如果您在傳送訊息MessageFeedbackEnabled時啟用 ，您可以報告最終使用者是否已成功接收並使用程式碼：

client.put_message_feedback(
    MessageId='msg-1234567890abcdef',
    MessageFeedbackStatus='RECEIVED'  # or 'FAILED'
)

交付事件

通知 會將交付事件發送到您設定的事件目的地 (CloudWatch、Amazon Data Firehose 或 Amazon SNS)。如需設定事件目的地的詳細資訊，請參閱 AWS 最終使用者傳訊簡訊中的組態設定。

交付事件類型
事件 Description
PENDING 訊息已排入交付佇列。
DELIVERED 訊息已交付至收件人的裝置。
FAILED 訊息傳遞失敗。如需詳細資訊，請檢查失敗原因。
BLOCKED 保護組態規則已封鎖訊息。

錯誤處理

ValidationException

範本變數遺失或無效、電話號碼格式無效，或未在組態上啟用目的地國家/地區。

ResourceNotFoundException

找不到通知組態或範本。

ServiceQuotaExceededException

達到每日訊息限制 （基本方案） 或每月花費限制。

ConflictException

通知組態未處於 ACTIVE 狀態。

重要說明

  • 雙向傳訊 – 使用 AWS受管原始身分時不支援雙向傳訊。如果您需要雙向傳訊，請將您自己的電話集區建立關聯。請參閱 搭配 Notify 使用專用號碼。

  • 選擇退出行為 – 對於具有 AWS受管身分的 OTP 使用案例，STOP 關鍵字回應僅供參考。不會維護持續選擇退出清單，因為每個 OTP 請求都是隱含選擇加入。如果您將自己的電話集區建立關聯，則會遵守集區的選擇退出清單。

疑難排解

未傳遞的訊息

如果您的訊息未交付，請確認下列事項：

  1. 確認目的地電話號碼為 E.164 格式 （開頭為 +和 國碼）。

  2. 檢查目的地國家/地區是否在您的EnabledCountries清單中。

  3. 驗證您的組態狀態為 ACTIVE。

  4. 檢查您的支出限制尚未超過。

封鎖狀態

訊息已被保護組態封鎖。常見原因包括目的地國家/地區不在已啟用的國家/地區清單中，或訊息標記為潛在 AIT （人工膨脹流量）。

驗證錯誤

確定TemplateVariables已提供所有必要項目。檢查變數值是否符合其宣告的類型 （例如，整數是有效的數字）。確認範本 ID 存在且處於作用中狀態。