Overview
The View message API allows you to fetch data from a single push, email, or SMS message at a time. If you want to get multiple messages at a time, use the View messages API. In most cases, you will likely want to use Event Streams instead. Currently this API does not provide Journey-sent messages. See Journey analytics for details. Messages sent through the API are only accessible 30 days after creation; however, messages sent using the OneSignal dashboard are accessible for the app’s lifetime. See our Rate limits for details on how often you can pull your message data with this API.How to use this API
This API is most commonly used when sending Transactional messages to individual users. The response of our Create message API has anid
which corresponds to the message_id
used in this request. You can store this message_id
on your server and (after giving your users some time to interact with the message) pull the data if desired.
For example, if you send a message targeting the include_aliases
parameter, the response will include the aliases you set. If you send with the included_segments
parameter, then the response will only provide the segments you set. When targeting segments or filters, you can use the Export audience activity CSV API to get the user event data.
To view outcome data for the message, you must include the outcome_name
parameter with the name of the outcome you want to fetch, along with the accompanying aggregation type (.count or .sum), for example: os__click.count
. For more information on outcome definitions, see View Outcomes.
Headers
Your App API key with prefix Key
. See Keys & IDs.
Path Parameters
The identifier of the message in UUID v4 format. Get this id
in the response of your Create Message API request, the View Messages API, and in your OneSignal dashboard Message Reports.
Query Parameters
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The name and aggregation type of the outcome(s) you want to fetch. Example: my_outcome.count
or my_outcome.sum
. For clicks, use os__click.count
. For confirmed deliveries, use os__confirmed_delivery.count
. For session duration, use os__session_duration.count
.
Time range for the returned data. Available values: 1h
(1 hour), 1d
(1 day), 1mo
(1 month)
1h
, 1d
, 1mo
The platforms in which you want to pull the data represented as the device_type
integer.
Attribution type for the outcomes.
direct
, influenced
, unattributed
, total
Response
200
Returns all message properties set. See the Push notifications, Email, and/or SMS Message Create APIs for all properties. Most commonly used properties for this endpoint are listed.
Your OneSignal App ID in UUID v4 format. See Keys & IDs.
The URL of the image set in the push notification.
Whether the message was canceled.
The URL of the icon set in the push notification.
The URL of the image set in the push notification.
An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
The main message body with language-specific values.
The number of times the push was clicked.
The JSON data set in the push notification if applicable.
The per-user delay option set for the message.
The delivery time of day set for the message if delayed_option
is timezone
.
The number of messages that have not been sent yet. If null
, then the system is still processing the audience, try again later.
The number of times the message errored.
The segments excluded from the message if applicable.
The number of subscriptions reported unsubscribed for the message.
The URL of the image set in the push notification.
The title of the push notification.
The identifier of the message in UUID v4 format.
The segments included in the message if applicable.
The badge count set for the message if applicable.
The badge type set for the message if applicable.
Unix timestamp of when the message was created.
Unix timestamp of when the message delivery was scheduled to begin.
Unix timestamp of when the message delivery was completed. The delivery duration from start to finish can be calculated with completed_at - send_after
.
The number of messages successfully delivered to the push, email, or SMS servers.
The number of messages that confirmed being received aka Confirmed Deliveries.
The filters set for the message if applicable.
The URL of the push notification.
The URL of the push notification for web push subscriptions.
The URL of the push notification for mobile subscriptions.
The successful, errored, failed, converted, received and frequency cap counts for each platform applicable.
The throttle rate of the push notification if applicable.
The frequency cap status of the push notification if applicable.
The id, value, and aggregation type of the outcome set in the request.