SMS event data stream from Amazon Pinpoint - Amazon Pinpoint
SMS event exampleSMS event attributes

SMS event data stream from Amazon Pinpoint

If the SMS channel is enabled for a project, Amazon Pinpoint can stream event data about SMS message deliveries for the project. After you set up event streaming, Amazon Pinpoint retrieves your event data from the destination that you specified during setup for you to view. For information about how to set up event streaming, see Set up Amazon Pinpoint to stream app event data through Amazon Kinesis or Amazon Data Firehose .

Note

SMS events that are generated by carriers can take up to 72 hours to be received and shouldn't be used to determine if there is a delay in outbound message delivery. After 72 hours, if Amazon Pinpoint hasn't received a final event from a carrier, the service automatically returns an UNKNOWN record_status, as Amazon Pinpoint doesn't know what happened to that message.

SMS event 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 previous example of 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 AWS End User Messaging 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 AWS End User Messaging 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 About the SMS/MMS and Voice sandbox in the AWS End User Messaging 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 AWS End User Messaging 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.
customer_context

A JSON string of the contents from the Context map sent in a Amazon Pinpoint SendMessages operation.

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.