SMS events - Amazon Pinpoint

SMS events

If the SMS channel is enabled for a project, Amazon Pinpoint can stream event data about SMS message deliveries for the project.

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 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 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.

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 – 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 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 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 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
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.