SMS events

If the SMS channel is enabled for a project, Amazon Pinpoint can stream event data about SMS message deliveries for the project. SMS events generated by carriers can take up to 72 hours to be received and should not be used to determine if there is a delay in outbound message delivery. After 72 hours, if Amazon Pinpoint has not received a final event from a carrier, the service will automatically return an UNKNOWN record_status as we do not know what happened to that message. Before you can view your events you have to setup event streaming, see Setting up event streaming. When setting up event streaming you specify a destination for your event data to be saved to and then you can use the destination to retrieve your event data for viewing.

Example

The JSON object for an SMS event contains the data shown in the following example.


{
  "event_type": "_SMS.SUCCESS",
  "event_timestamp": 1553104954322,
  "arrival_timestamp": 1553104954064,
  "event_version": "3.1",
  "application": {
    "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "sdk": {}
  },
  "client": {
    "client_id": "123456789012"
  },
  "device": {
    "platform": {}
  },
  "session": {},
  "attributes": {
    "sender_request_id": "565d4425-4b3a-11e9-b0a5-example",
    "campaign_activity_id": "cbcfc3c5e3bd48a8ae2b9cb41example",
    "origination_phone_number": "+12065550142",
    "destination_phone_number": "+14255550199",
    "record_status": "DELIVERED",
    "iso_country_code": "US",
    "treatment_id": "0",
    "number_of_message_parts": "1",
    "message_id": "1111-2222-3333",
    "message_type": "Transactional",
    "campaign_id": "52dc44b35c4742c98c5935269example"
  },
  "metrics": {
    "price_in_millicents_usd": 645.0
  },
  "awsAccountId": "123456789012"
}

SMS event attributes

This section defines the attributes that are included in the event stream data that Amazon Pinpoint generates when you send SMS messages.

Event
Attribute	Description
`event_type`	The type of event. Possible values are: _SMS.BUFFERED – The message is still in the process of being delivered to the recipient. _SMS.SUCCESS – The message was successfully accepted by the carrier/delivered to the recipient. _SMS.FAILURE – Amazon Pinpoint wasn't able to deliver the message to the recipient. To learn more about the error that prevented the message from being delivered, see `attributes.record_status`. _SMS.OPTOUT – The customer received the message and replied by sending the opt-out keyword (usually "STOP").
`event_timestamp`	The time when the event was reported, shown as Unix time in milliseconds.
`arrival_timestamp`	The time when the event was received by Amazon Pinpoint, shown as Unix time in milliseconds.
`event_version`	The version of the event JSON schema. Tip Check this version in your event-processing application so that you know when to update the application in response to a schema update.
`application`	Information about the Amazon Pinpoint project that's associated with the event. For more information, see the Application table.
`client`	Information about the app client installed on the device that reported the event. For more information, see the Client table.
`device`	Information about the device that reported the event. For more information, see the Device table. For SMS events, this object is empty.
`session`	For SMS events, this object is empty.
`attributes`	Attributes that are associated with the event. For events that are reported by one of your apps, this object can include custom attributes that are defined by the app. For events that are created when you send a campaign, this object contains attributes that are associated with the campaign. For events that are generated when you send transactional messages, this object contains information that's related to the message itself. For more information, see the Attributes table.
`metrics`	Additional metrics that are associated with the event. For more information, see the Metrics table.
`awsAccountId`	The ID of the AWS account that was used to send the message.

Application

Includes information about the Amazon Pinpoint project that the event is associated with and, if applicable, the SDK that was used to report the event.

Attribute	Description
`app_id`	The unique ID of the Amazon Pinpoint project that reported the event.
`sdk`	The SDK that was used to report the event. If you send a transactional SMS message by calling the Amazon Pinpoint API directly or by using the Amazon Pinpoint console, this object is empty.

Attributes

Includes information about the attributes that are associated with the event.

Attribute	Description
`sender_request_id`	A unique ID that's associated with the request to send the SMS message.
`campaign_activity_id`	The unique ID of the activity within the campaign.
`origination_phone_number`	The phone number that the message was sent from.
`destination_phone_number`	The phone number that you attempted to send the message to.
`record_status`	Additional information about the status of the message. Possible values include: SUCCESSFUL/DELIVERED – The message was successfully delivered. PENDING – The message hasn't yet been delivered to the recipient's device. INVALID – The destination phone number is invalid. UNREACHABLE – The recipient's device is currently unreachable or unavailable. For example, the device might be powered off, or might be disconnected from the network. You can try to send the message again later. UNKNOWN – An error occurred that prevented the delivery of the message. This error is usually transient, and you can attempt to send the message again later. BLOCKED – The recipient's device is blocking SMS messages from the origination number. CARRIER_UNREACHABLE – An issue with the mobile network of the recipient prevented the message from being delivered. This error is usually transient, and you can attempt to send the message again later. SPAM – The recipient's mobile carrier identified the contents of the message as spam and blocked delivery of the message. INVALID_MESSAGE – The body of the SMS message is invalid and can't be delivered. CARRIER_BLOCKED – The recipient's carrier has blocked delivery of this message. This often occurs when the carrier identifies the contents of the message as unsolicited or malicious. TTL_EXPIRED – The SMS message couldn't be delivered within a certain time frame. This error is usually transient, and you can attempt to send the message again later. MAX_PRICE_EXCEEDED – Sending the message would have resulted in a charge that exceeded the monthly SMS spending quota for your account. You can request an increase to this quota by completing the procedure in Requesting increases to your monthly SMS spending quota in the Amazon Pinpoint User Guide. OPTED_OUT – The SMS message wasn't sent because the recipient opted out of receiving messages from you. NO_QUOTA_LEFT_ON_ACCOUNT – There isn't enough spending quota left on your account to send the message. You can request an increase to this quota by completing the procedure in Requesting increases to your monthly SMS spending quota in the Amazon Pinpoint SMS User Guide. NO_ORIGINATION_IDENTITY_AVAILABLE_TO_SEND – Your account doesn’t contain a phone number that can be used to send the message to the destination. DESTINATION_COUNTRY_NOT_SUPPORTED – The destination country is blocked. For all supported countries, see Supported countries and regions (SMS channel) in the Amazon Pinpoint SMS User Guide. ACCOUNT_IN_SANDBOX – Your account is in sandbox and it can only send to verified destination numbers. You can verified the destination number in Amazon Pinpoint console or start the process to move the account out of sandbox, see Moving from the Amazon Pinpoint SMS sandbox to production in the Amazon Pinpoint SMS User Guide. RATE_EXCEEDED – You attempted to send message too fast and were throttled. You need to slow down your call rate. For details about our limits, see Message Parts per Second (MPS) limits in the Amazon Pinpoint SMS User Guide. INVALID_ORIGINATION_IDENTITY – The provided origination identity is invalid. ORIGINATION_IDENTITY_DOES_NOT_EXIST – The provided origination identity doesn't exist. INVALID_DLT_PARAMETERS – Invalid DLT parameters (required for destinations in India) were provided. INVALID_PARAMETERS – Invalid parameters were provided. ACCESS_DENIED – Your account is blocked from sending messages. Contact customer support to find out the cause and resolve the issue. INVALID_KEYWORD – The provided keyword is invalid. The keyword could be in incorrect format or not set in your account. INVALID_SENDER_ID – The provided Sender ID is invalid. The Sender ID could be in incorrect format or length. INVALID_POOL_ID – The provided Pool ID is invalid. The Pool ID could be in incorrect format or not belong to your account. SENDER_ID_NOT_SUPPORTED_FOR_DESTINATION – The destination country does not support Sender ID. You have to use a phone number or another origination identity for sending. INVALID_PHONE_NUMBER – The provided origination phone number is invalid. The phone number could be in incorrect format or length.
`iso_country_code`	The country that's associated with the recipient's phone number, shown in ISO 3166-1 alpha-2 format.
`treatment_id`	The ID of the message treatment, if the message was sent in an A/B campaign.
`treatment_id`	If the message was sent using an A/B test campaign, this value represents the treatment number of the message. For transactional SMS messages, this value is 0.
`number_of_message_parts`	The number of message parts that Amazon Pinpoint created in order to send the message. Generally, SMS messages can contain only 160 GSM-7 characters or 67 non-GSM characters, although these limits can vary by country . If you send a message that exceeds these limits, Amazon Pinpoint automatically splits the message into smaller parts. We bill you based on the number of message parts that you send.
`message_id`	The unique ID that Amazon Pinpoint generates when it accepts the message.
`message_type`	The type of message. Possible values are Promotional and Transactional. You specify this value when you create a campaign, or when you send transactional messages by using the SendMessages operation in the Amazon Pinpoint API.
`campaign_id`	The unique ID of the Amazon Pinpoint campaign that sent the message.

Client

Includes information about the app client that's installed on the device that reported the event.

Attribute Description

Attribute	Description
`client_id`	For events that are generated by apps, this value is the unique ID of the app client that's installed on the device. This ID is automatically generated by the AWS Mobile SDK for iOS and the AWS Mobile SDK for Android. For events that are generated when you send campaigns and transactional messages, this value is equal to the ID of the endpoint that you sent the message to.
`cognito_id`	The unique ID assigned to the app client in the Amazon Cognito identity pool used by your app.

client_id

For events that are generated by apps, this value is the unique ID of the app client that's installed on the device. This ID is automatically generated by the AWS Mobile SDK for iOS and the AWS Mobile SDK for Android.

For events that are generated when you send campaigns and transactional messages, this value is equal to the ID of the endpoint that you sent the message to.

cognito_id The unique ID assigned to the app client in the Amazon Cognito identity pool used by your app.

Device

Includes information about the device that reported the event.

Attribute	Description
`locale`	The device locale.
`make`	The device make, such as `Apple` or `Samsung`.
`model`	The device model, such as `iPhone`.
`platform`	The device platform, such as `ios` or `android`.

Metrics

Includes information about metrics that are associated with the event.

Attribute	Description
`price_in_millicents_usd`	The amount that we charged you to send the message. This price is shown in thousandths of a United States cent. For example, if the value of this attribute is `645`, then we charged you 0.645¢ to send the message (645 / 1000 = 0.645¢ = $0.00645). Note This property doesn't appear for messages with an `event_type` of _SMS.BUFFERED.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Email events

Querying analytics data