Amazon Pinpoint
Developer Guide

SMS Events

If the SMS channel is enabled, Amazon Pinpoint streams events about SMS deliveries.

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

Event

Attribute Description
event_type

The type of event. Possible values:

  • _SMS.SEND – Amazon Pinpoint accepted the message and attempted to deliver it to the recipient.

  • _SMS.BUFFERED – The message is still in the process of being delivered to the recipient.

  • _SMS.SUCCESS – The message was successfully 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. See the Application table for more information.

client

The app client installed on the device that reports the event. See the Client table for more information.

device

The device that reports the event. See the Device table for more information.

In events that are generated when you send a transactional message, 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.

See the Attributes table for more information.

metrics

Additional metrics that are associated with the event. See the Metrics table for more information.

awsAccountId

The ID of the AWS account that was used to send the message.

Application

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 calling the Amazon Pinpoint API directly, or by using the Amazon Pinpoint console, this object is empty.

Attributes

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 – The message was accepted by the carrier.

  • DELIVERED – The message was delivered to the recipient's device.

  • 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 limit. 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 limit for your account. You can request an increase to this limit by completing the procedure in Requesting Increases to Your Monthly SMS Spend Threshold for Amazon Pinpoint in the Amazon Pinpoint User Guide.

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 only contain 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 messages 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

Attribute Description
client_id

For events that are generated by apps, this value is the unique ID of the app client 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

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

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.