Message engagement events
Use the search bar or the checkboxes below to find the events you need to use Currents effectively.
These schema consist of the Braze Events that are directly related to message sending.
Contact your account manager or open a support ticket if you need access to additional event entitlements. If you can’t find what you need in this article, check out our Customer Behavior Events Library or our Currents sample data examples.
Explanation of message engagement event structure and platform values
Event structure
This event breakdown shows what type of information is generally included in a message engagement event. With a solid understanding of its components, your developers and business intelligence strategy team can use the incoming Currents event data to make data-driven reports, charts and take advantage of other valuable data metrics.
Message engagement events are comprised of user-specific properties, campaign/canvas tracking properties, and event-specific properties.
Platform values
Certain events return a platform value that specifies the platform of the user’s device.
The following table details the possible returned values:
| User device | Platform value |
|---|---|
| iOS | ios |
| Android | android |
| FireTV | kindle |
| Kindle | kindle |
| Web | web |
| tvOS | tvos |
| Roku | roku |
important:
These schemas only apply to the flat file event data we send to Data Warehouse partners (Google Cloud Storage, Amazon S3, and Microsoft Azure Blob Storage). For schemas that apply to the other partners, refer to our list of available partners and check their respective pages.
Additionally, note that Currents will drop events with excessively large payloads of greater than 900 KB.
update:
Human-readable names for objects related to Canvas Flow are coming soon to Currents. In the meantime, the IDs can be used for grouping, and translated to human-readable names via the Canvas Details endpoint.
WhatsApp read events
This event occurs when an WhatsApp message is read by the end user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// WhatsApp Read: users.messages.whatsapp.Read
{
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) ID of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"from_phone_number": (optional, string) phone number used to send,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"to_phone_number": (optional, string) phone number of User receiving the message,
"user_id": (required, string) BSON id of the user that performed this event
}
WhatsApp delivery events
This event occurs when an WhatsApp message sent made it successfully to the end-users device.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// WhatsApp Delivery: users.messages.whatsapp.Delivery
{
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) ID of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"from_phone_number": (optional, string) phone number used to send,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"to_phone_number": (optional, string) phone number of User receiving the message,
"user_id": (required, string) BSON id of the user that performed this event
}
WhatsApp failure events
This event occurs when an Internet Service Provider returns a hard bounce. A hard bounce signifies a permanent deliverability failure.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// WhatsApp Delivery Failure: users.messages.whatsapp.Failure
{
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) ID of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"from_phone_number": (optional, string) phone number used to send,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"provider_error_code": (optional, string) Error Code from WhatsApp,
"provider_error_title": (optional, string) Description of failure from WhatsApp,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"to_phone_number": (optional, string) phone number of User receiving the message,
"user_id": (required, string) BSON id of the user that performed this event
}
WhatsApp send events
This event occurs when an email send request was successfully communicated between Braze and WhatsApp. Though, this does not mean the message was received by the end user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// WhatsApp Send: users.messages.whatsapp.Send
{
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) ID of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"from_phone_number": (optional, string) phone number used to send,
"message_extras": (optional, string) Liquid tags related fields,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"to_phone_number": (optional, string) phone number of User receiving the message,
"user_id": (required, string) BSON id of the user that performed this event
}
WhatsApp abort message events
This event occurs if a WhatsApp message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// WhatsApp Abort: users.messages.whatsapp.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"action": (optional, string) action taken in response to this message (for example, Subscribed, Unsubscribed, or None),
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) id of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) id of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) id of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) id of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"send_id": (optional, string) message send ID this message belongs to,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"user_id": (required, string) BSON id of the user that performed this event
WhatsApp inbound received events
This event occurs when one of your users sends a WhatsApp message to a phone number in one of your Braze WhatsApp subscription groups.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// WhatsApp Inbound Received: users.messages.whatsapp.InboundReceive
{
"app_group_id": (required, string) BSON id of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"company_id": (optional, string) ID of the sending Company,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"inbound_phone_number": (optional, string)the inbound number that the message was sent to,
"medial_urls": (optional, string[]) media urls from the user,
"message_body": (optional, string) typed response from the user,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"quick_reply_text": (optional, string) test of button pressed by the user,
"subscription_group_id": (optional, string) ID of the sending Subscription Group,
"time": (optional, int) 10-digit UTC time of the event in seconds since the epoch,
"user_phone_number": (optional, string) the user’s phone number from which the message was received,
"user_id": (required, string) BSON id of the user that performed this event
}
Content Card abort message events
This event occurs if a Content Card message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Content Card Abort: users.messages.contentcard.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"device_id": (optional, string) ID of the device on which the event occurred,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"id": (required, string) globally unique ID of this event,
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"send_id": (optional, string) message send ID this message belongs to,
"time": (required, int) unix timestamp at which the event happened,
"timezone": (optional, string) timezone of the user,
"user_id": (required, string) BSON ID of the user that performed this event
}
Email abort message events
This event occurs if an email message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Email Abort: users.messages.email.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"app_group_id": (optional, string) BSON ID of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) Canvas variation ID of the variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation this event belongs to,
"device_id": (optional, string) ID of the device on which the event occurred,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"email_address": (required, string) email address of the user,
"external_user_id": (optional, string) External user ID of the user,
"id": (required, string) globally unique ID of this event,
"ip_pool": (optional, string) IP Pool from which the email send was made
"message_variation_id": (optional, string) message variation ID of the variation this user received,
"message_variation_name": (optional, string) name of the message variation this user received,
"send_id": (optional, string) message send ID this message belongs to,
"time": (required, int) unix timestamp at which the event happened,
"timezone": (optional, string) timezone of the user,
"user_id": (required, string) BSON ID of the user that performed this event,
}
Push notification abort events
This event occurs if a push notification message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Push Notification Abort: users.messages.pushnotification.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"app_id": (required, string) BSON ID of the app this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received
"canvas_step_name": (optional, string) API ID of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) ID of the Canvas variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"device_id": (optional, string), ID of the device on which the event occurred,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"id": (required, string) unique ID of this event,
"message_variation_id": (optional, string) ID of the message variation this user received,
"message_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"platform": (required, string) platform of the device,
"send_id": (optional, string) message send ID this message belongs to,
"time": (required, int) unix timestamp at which the event happened,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"user_id": (required, string) BSON ID of the user that performed this event
}
SMS abort message events
This event occurs if an SMS message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// SMS Abort: users.messages.sms.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received
"canvas_step_name": (optional, string) API ID of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) ID of the Canvas variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"external_user_id": (optional, string) External user ID of the user,
"id": (required, string) globally unique ID of this event,
"message_variation_id": (optional, string) ID of the message variation this user received,
"message_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"time": (required, int) unix timestamp at which the event happened,
"user_id": (required, string) BSON ID of the user that performed this event
}
Webhook abort message events
This event occurs if a webhook message was aborted based on Liquid aborts, Quiet Hours, etc.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Webhook Abort: users.messages.webhook.Abort
{
"abort_log": (optional, string) log message describing abort details (MAX: 128 CHARS),
"abort_type": (optional, string) type of abort, e.g.: "liquid_abort_message", "quiet_hours", etc.,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"campaign_id": (optional, string) internal-use Braze ID of the campaign this event belongs to,
"campaign_name": (optional, string) name of the campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_message_variation_id": (optional, string) ID of the Canvas step message variation this user received
"canvas_step_name": (optional, string) API ID of the Canvas step this event belongs to,
"canvas_variation_id": (optional, string) ID of the Canvas variation this event belongs to,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"device_id": (optional, string) ID of the device on which the event occurred,
"dispatch_id": (optional, string) ID of the dispatch this message belongs to,
"external_user_id": (optional, string) External user ID of the user,
"id": (required, string) globally unique ID of this event,
"message_variation_id": (optional, string) ID of the message variation this user received,
"message_variation_name": (optional, string) name of the message variation the user is in if from a Canvas,
"send_id": (optional, string) message send ID this message belongs to,
"time": (required, int) unix timestamp at which the event happened,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"user_id": (required, string) BSON ID of the user that performed this event
}
Canvas exit performed event events
This event occurs when a user has exited a Canvas by performing an event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Canvas Exit Performed Event: users.canvas.exit.PerformedEvent
{
"id": (required, string) globally unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External user ID of the user,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"app_group_api_id": (optional, string) API ID of the workspace this user belongs to,
"time": (required, int) unix timestamp at which the event happened,
"canvas_id": (required, string) ID of the Canvas if from a Canvas,
"canvas_variation_id": (required, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_api_id": (optional, string) BSON ID of the experiment step this event belongs to,
"canvas_variation_api_id": (optional, string) API ID of the Canvas variation this event belongs to,
"canvas_step_api_id": (optional, string) API ID of the Canvas step this event belongs to
}
Canvas exit matched audience events
This event occurs when a user has exited a Canvas by matching an audience.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Canvas Exit Matched Audience: users.canvas.exit.MatchedAudience
{
"id": (required, string) globally unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External user ID of the user,
"app_group_id": (required, string) BSON ID of the workspace this user belongs to,
"app_group_api_id": (optional, string) API ID of the workspace this user belongs to,
"time": (required, int) unix timestamp at which the event happened,
"canvas_id": (required, string) ID of the Canvas if from a Canvas,
"canvas_variation_id": (required, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_api_id": (optional, string) BSON ID of the experiment step this event belongs to,
"canvas_variation_api_id": (optional, string) API ID of the Canvas variation this event belongs to,
"canvas_step_api_id": (optional, string) API ID of the Canvas step this event belongs to
}
Experiment split entry events
This event occurs when a user enters a Canvas experiment step path.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Experiment Step Split Path Entry: users.canvas.experimentstep.SplitEntry
{
"id": (required, string) globally unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External user ID of the user,
"time": (required, int) unix timestamp at which the event happened,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"experiment_step_id": (required, string) BSON ID of the experiment step this event belongs to,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"experiment_split_id": (optional, string) BSON ID of the experiment split the user enrolled in,
"experiment_split_name": (optional, string) name of the experiment split the user enrolled in,
"in_control_group": (required, boolean) whether the user was enrolled in the control group
}
Experiment conversion events
This event occurs when a user convert for a Canvas experiment step.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Experiment Step Conversion: users.canvas.experimentstep.Conversion
{
"id": (required, string) globally unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External user ID of the user,
"app_id": (optional, string) BSON ID of the app this user belongs to,
"time": (required, int) unix timestamp at which the event happened,
"canvas_id": (required, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"experiment_step_id": (optional, string) BSON ID of the experiment step this event belongs to,
"experiment_split_id": (required, string) BSON ID of the experiment split variation this user received,
"experiment_split_name": (optional, string) name of the experiment split the user enrolled in,
"conversion_behavior_index": (optional, int) index of the conversion behavior,
"conversion_behavior": (optional, string) conversion behavior
}
Push send events
This event occurs when Braze processes a push message for a user, communicating this to Apple Push Notification Service or Fire Cloud Messaging. This does not mean the push was delivered to the device, just that a message was sent.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Push Notification Send: users.messages.pushnotification.Send
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the user action occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"platform": (required, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) name of the message variation the user is in if from a Canvas,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"device_id": (optional, string) ID of the device that we made a delivery attempt to,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device,
"message_extras": (optional, string) key-value pairs sent with this event
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ADID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id. message_extrasallow you to annotate your send events with dynamic data from Connected Content, custom attributes (such as language, country), and Canvas entry properties. Refer to Message extras to learn more.
Push open events
This event occurs when a user directly clicks on the Push notification to open the application. Currently, Push Open Events refer specifically to “Direct Opens” rather than “Total Opens”. This does not include statistics shown at the campaign level of “influenced opens” as these are not attributed at the user level.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// Push Notification Open: users.messages.pushnotification.Open
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"app_id": (required, string) ID for the app on which the user action occurred,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_step_message_variation_id": (optional, string) API ID of the Canvas step message variation this user received,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"device_id": (optional, string) ID of the device that we made a delivery attempt to,
"button_action_type": (optional, string) Action type of the push notification,
button. One of [URI, DEEP_LINK, NONE, CLOSE, SHARE]. null if not
from a button click,
"button_string": (optional, string) identifier (button_string) of the push notification button clicked. null if not from a button click,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ADID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Push notifications in the iOS foreground events
This event is not supported by our Swift SDK and is now deprecated using our Obj-C SDK.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Push Notification iOS Foreground: users.messages.pushnotification.IosForeground
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the user action occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"platform": (required, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"device_id": (optional, string) ID of the device that we made a delivery attempt to,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ADID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Push notifications bounce
This event occurs when an error is received from either Apple Push Notification Service or Fire Cloud Messaging. This means that the push message was bounced, and therefore not delivered to the user’s device.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Push Notification Bounce: users.messages.pushnotification.Bounce
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the bounce occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"device_id": (optional, string) ID of the device that we made a delivery attempt to,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Email send events
This event occurs when an email send request was successfully communicated between Braze and SendGrid. Though, this does not mean the email was received in the end user’s inbox.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Email Send: users.messages.email.Send
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"ip_pool": (optional, string) IP pool used for message sending,
"message_extras": (optional, string) key-value pairs sent with this event
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior. message_extrasallow you to annotate your send events with dynamic data from Connected Content, custom attributes (such as language, country), and Canvas entry properties. Refer to Message extras to learn more.
Email delivery events
This event occurs when an email sent made it successfully to the end-users inbox.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Email Delivery: users.messages.email.Delivery
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"sending_ip": (optional, string) the IP address from which the message was sent (Email Delivery, Bounce, and SoftBounce events only. Will only be shown on events if the message was actually attempted for delivery. For certain other bounces, the information could be lost if the recipient server has already accepted the mail and only later after the connection is closed decided it could not deliver the mail),
"ip_pool": (optional, string) IP pool used for message sending,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email open events
This event occurs when a user opens an email. Multiple events may be generated for the same campaign if a user opens the email multiple times.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Email Open: users.messages.email.Open
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"user_agent": (optional, string) description of the user's system and browser for the event,
"ip_pool": (optional, string) IP pool used for message sending,
"machine_open": (optional, string) Indicator of whether the email was opened by an automated process, such as Apple or Google mail pre-fetching. Currently "true" or null, but additional granularity (for example, "Apple" or "Google" to indicate which process made the fetch) may be added in the future.,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email,
"is_amp": (optional, boolean) indicates that this is an AMP event
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email clicks events
This event occurs when a user clicks an email. Multiple events may be generated for the same campaign if a user clicks multiple times or clicks different links within the email.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Email Click: users.messages.email.Click
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Only included when campaign_id is present. Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"url": (optional, string) the URL that was clicked,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"user_agent": (optional, string) description of the user's system and browser for the event,
"ip_pool": (optional, string) IP pool used for message sending,
"link_id": (optional, string) unique value generated by Braze for the URL - null unless link aliasing is enabled,
"link_alias": (optional, string) alias name set when the message was sent - null unless link aliasing is enabled,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email,
"is_amp": (optional, boolean) indicates that this is an AMP event
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email bounce event
This event occurs when an Internet Service Provider returns a hard bounce. A hard bounce signifies a permanent deliverability failure.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Email Bounce: users.messages.email.Bounce
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"sending_ip": (optional, string) the IP address from which the message was sent (Email Delivery, Bounce, and SoftBounce events only. Will only be shown on events if the message was actually attempted for delivery. For certain other bounces, the information could be lost if the recipient server has already accepted the mail and only later after the connection is closed decided it could not deliver the mail),
"ip_pool": (optional, string) IP pool used for message sending (for certain bounce cases, IP pool will not be provided) ,
"bounce_reason": (optional, string) reason for bounce provided by server,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email,
"is_drop": (optional, boolean) indicates that this event counts as a drop event
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email soft bounce event
This event occurs when an Internet Service Provider returns a soft bounce. A soft bounce signifies that an email could not be delivered because of a temporary deliverability failure.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Email Soft Bounce: users.messages.email.SoftBounce
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"sending_ip": (optional, string) the IP address from which the message was sent (Email Delivery, Bounce, and SoftBounce events only. Will only be shown on events if the message was actually attempted for delivery. For certain other bounces, the information could be lost if the recipient server has already accepted the mail and only later after the connection is closed decided it could not deliver the mail),
"ip_pool": (optional, string) IP pool used for message sending(for certain bounce cases, IP pool will not be provided),
"bounce_reason": (optional, string) reason for bounce provided by server,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email
}
Property details
- The behavior for
dispatch_iddiffers between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email spam events
This event occurs when the end-user hits the “spam” button on the email. Note that this does not represent the fact the email went into the spam folder as Braze does not track this.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Email Mark As Spam: users.messages.email.MarkAsSpam
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"user_agent": (optional, string) This field is no longer used in any destination for this event and will always be empty,
"ip_pool": (optional, string) IP pool used for message sending,
"esp": (optional, string) ESP related to the event (SparkPost or SendGrid),
"from_domain": (optional, string) sending domain for the email
}
Property details
The behavior for dispatch_id differs between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
Email unsubscribe events
This event occurs when the end-user has clicked “unsubscribe” from the email.
important:
The Unsubscribe event is actually a specialized click event that is fired when your user clicks on the unsubscribe link in the email (either a normal unsubscribe link within the email body or footer, or using the list-unsubscribe header), not when the user changes state to unsubscribed. If subscription state change is sent through the API, it will not trigger an event on Currents.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Email Unsubscribe: users.messages.email.Unsubscribe
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform). Users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user.,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"email_address": (required, string) email address for this event,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"ip_pool": (optional, string) IP pool used for message sending
}
Property details
The behavior for dispatch_id differs between Canvas and campaigns because Braze treats Canvas steps (except for Entry Steps, which can be scheduled) as triggered events, even when they are “scheduled”. Learn more about dispatch ID behavior.
In-app message impression events
This event occurs when a user views an in-app message.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// In-App Message Impression: users.messages.inappmessage.Impression
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"app_id": (required, string) ID for the app on which the user action occurred,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"card_id": (optional, string) ID of the card that was viewed,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"device_id": (optional, string) ID of the device on which the event occurred,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ADID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
In-app message click events
This event occurs when a user clicks on an in-app message.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// In-App Message Click: users.messages.inappmessage.Click
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the user action occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"card_id": (optional, string) ID of the card that was viewed,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"button_id": (optional, string) index of the button clicked if it was a button that was clicked, tracking ID of the click if the event came from an appboyBridge.logClick or brazeBridge.logClick invocation, or choice_id if the in app-message type is a simple survey,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"device_id": (optional, string) ID of the device on which the event occurred,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ADID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Webhook send events
This event occurs when a webhook was processed and sent to the third party specified in that webhook. Note that this does not signify whether or not the request was received.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Webhook Send: users.messages.webhook.Send
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types)
"message_extras": (optional, string) key-value pairs sent with this event
}
Property details
message_extrasallow you to annotate your send events with dynamic data from Connected Content, custom attributes (such as language, country), and Canvas entry properties. Refer to Message extras to learn more.
Content Card send events
This event occurs when a Content Card gets sent to a user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// Content Card Send: users.messages.contentcard.Send
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"content_card_id": (required, string) ID of the content card that was sent,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_name": (optional, string) name of the Canvas,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"device_id": (optional, string) ID of the device on which the event occurred,
"message_extras": (optional, string) key-value pairs sent with this event
}
Property details
message_extrasallow you to annotate your send events with dynamic data from Connected Content, custom attributes (such as language, country), and Canvas entry properties. Refer to Message extras to learn more.
Content Card impression events
This event occurs when a user views a Content Card.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Content Card Impression: users.messages.contentcard.Impression
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"content_card_id": (required, string) ID of the content card that was viewed/clicked/dismissed,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"app_id": (required, string) ID for the app on which the user action occurred,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_name": (optional, string) name of the Canvas,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"device_id": (optional, string) ID of the device on which the event occurred,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Content Card click events
This event occurs when a user clicks a Content Card.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Content Card Click: users.messages.contentcard.Click
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"content_card_id": (required, string) ID of the content card that was viewed/clicked/dismissed,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"app_id": (required, string) ID for the app on which the user action occurred,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_name": (optional, string) name of the Canvas,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"device_id": (optional, string) ID of the device on which the event occurred,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
Content Card dismissal events
This event occurs when a user dismisses a Content Card.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Content Card Dismiss: users.messages.contentcard.Dismiss
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"content_card_id": (required, string) ID of the content card that was viewed/clicked/dismissed,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"app_id": (required, string) ID for the app on which the user action occurred,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types),
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"canvas_name": (optional, string) name of the Canvas,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"device_id": (optional, string) ID of the device on which the event occurred,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"ad_id": (optional, string) advertising identifier,
"ad_id_type": (optional, string) One of 'ios_idfa', 'google_ad_id', OR 'roku_ad_id',
"ad_tracking_enabled": (optional, boolean) whether advertising tracking is enabled for the device
}
Property details
- For
ad_id,ad_id_typeandad_tracking_enabled, you will need to explicitly collect the iOS IDFA and Android Google ad ID through the native SDKs. Learn more about them here: iOS, Android. - If you are using Kafka to ingest Currents data, reach out to your customer success manager or account manager to enable the feature flipper for sending
ad_id.
News Feed impression event
note:
News Feed is being deprecated. Braze recommends that customers who use our News Feed tool move over to our Content Cards messaging channel—it’s more flexible, customizable, and reliable. Check out the migration guide for more.
This event occurs when a user views the News Feed.
tip:
The News Feed Impression schema (users.behaviors.app.NewsFeedImpression) is located in the Customer Behavior Events glossary, as this data is not categorized as a Message Engagement Event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// News Feed Card Impression: users.messages.newsfeedcard.Impression
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the user action occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"card_id": (required, string) ID of the card that was viewed,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"device_id": (optional, string) ID of the device on which the event occurred
}
News Feed click events
This event occurs when a user clicks the News Feed.
tip:
The News Feed Impression schema (users.behaviors.app.NewsFeedImpression) is located in the Customer Behavior Events glossary, as this data is not categorized as a Message Engagement Event.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// News Feed Card Click: users.messages.newsfeedcard.Click
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_id": (required, string) ID for the app on which the user action occurred,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"card_id": (required, string) ID of the card that was clicked,
"platform": (optional, string) platform of the device (one of 'ios', 'android', 'web', 'kindle', 'tvos', OR 'roku'),
"os_version": (optional, string) os version of device used for the action,
"device_model": (optional, string) hardware model of the device,
"device_id": (optional, string) ID of the device on which the event occurred
}
SMS click events
This event occurs when a user clicks an SMS short link.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// SMS Send: users.messages.sms.ShortLinkClick
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user targeted by short_url,
"external_user_id": (optional, string) External ID of the user, null if short_url,
"app_group_id": (required, string) API ID of the workspace associated with the inbound phone number,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA timezone of the user at the time of the event, null if short_url did not use user click tracking,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign if from a campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas if from a Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation a user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"url": (required, string) original URL contained in message that was shortened for click tracking,
"short_url": (required, string) shortened URL that is sent to user for click tracking,
"user_agent": (optional, string) User-Agent header of the device performing the click event,
"user_phone_number": (optional, string) Phone number of the user that short_url was sent to
}
SMS send events
This event occurs when a user sends an SMS.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// SMS Send: users.messages.sms.Send
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform and users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"to_phone_number": (optional, string) the number the message was sent to,
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) message send ID this message belongs to,
"category": (optional, string) If the SMS was sent as a result of auto-response to one of your global SMS keywords, the Category will be reflected here (e.g Opt-In, Opt-Out, Help)
"message_extras": (optional, string) key-value pairs sent with this event
}
Property details
message_extrasallow you to annotate your send events with dynamic data from Connected Content, custom attributes (such as language, country), and Canvas entry properties. Refer to Message extras to learn more.
SMS sends to carrier events
This event occurs when an SMS is sent to the carrier.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// SMS Delivery: users.messages.sms.CarrierSend
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform and users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"to_phone_number": (optional, string) the number the message was sent to,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"from_phone_number": (optional, string) the from phone number of the message (Delivered and Undelivered only),
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) message send ID this message belongs to
}
SMS delivery events
This event occurs when an SMS was successfully delivered to the users mobile phone.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// SMS Delivery: users.messages.sms.Delivery
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform and users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user,
"external_user_id": (optional, string) External ID of the user,
"time": (required, required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"to_phone_number": (optional, string) the number the message was sent to,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"from_phone_number": (optional, string) the from phone number of the message (Delivered and Undelivered only),
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) message send ID this message belongs to
}
SMS rejection events
This event occurs when an SMS send gets rejected by the carrier, this can happen for several reasons. Use this event and the provided error codes to help troubleshoot issues with SMS delivery.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// SMS Rejection: users.messages.sms.Rejection
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform and users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user
"external_user_id": (optional, string) External ID of the user,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"to_phone_number": (optional, string) the number the message was sent to,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"from_phone_number": (optional, string) the from phone number of the message (Delivered and Undelivered only),
"error": (optional, string) the Braze provided error (Rejection and Delivery Failure events only),
"provider_error_code": (optional, string) the provider's reason code as to why the message was not sent (Rejection and Delivery Failure events only),
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) ID of the message if specified for the campaign (See Send Identifier under API Identifier Types)
}
SMS delivery failure events
This event occurs when an SMS experiences delivery failure. Use this event and the provided error codes to help troubleshoot issues with SMS delivery.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// SMS Delivery Failure: users.messages.sms.DeliveryFailure
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"dispatch_id": (optional, string) ID of the message dispatch (unique ID for each 'transmission' sent from the Braze platform and users who are sent a schedule message get the same dispatch_id. Action-based or API-triggered messages get a unique dispatch_id per user,
"external_user_id": (optional, string) External ID of the user,
"time": (required int) 10-digit UTC time of the event in seconds since the epoch,
"timezone": (optional, string) IANA time zone of the user at the time of the event,
"campaign_id": (optional, string) ID of the campaign if from a campaign,
"campaign_name": (optional, string) name of the campaign,
"message_variation_id": (optional, string) ID of the message variation if from a campaign,
"message_variation_name": (optional, string) the name of the message variation if from a campaign,
"to_phone_number": (optional, string) the number the message was sent to,
"subscription_group_id": (optional, string) ID of the subscription group targeted for this SMS message,
"error": (optional, string) the Braze provided error (Rejection and Delivery Failure events only),
"provider_error_code": (optional, string) the provider's reason code as to why the message was not sent (Rejection and Delivery Failure events only),
"canvas_id": (optional, string) ID of the Canvas if from a Canvas,
"canvas_name": (optional, string) name of the Canvas,
"canvas_variation_id": (optional, string) ID of the Canvas variation the user is in if from a Canvas,
"canvas_variation_name": (optional, string) name of the Canvas variation the user is in if from a Canvas,
"canvas_step_id": (optional, string) ID of the step for this message if from a Canvas,
"canvas_step_name": (optional, string) name of the Canvas step this event belongs to,
"send_id": (optional, string) message send ID this message belongs to
}
SMS inbound received events
This event occurs when one of your users sends an SMS to a phone number in one of your Braze SMS subscription groups.
When Braze receives an inbound SMS, we attribute that inbound message to any user that shares that phone number. As a result, you may receive multiple events per inbound message if multiple users in your Braze instance share the same phone number. If you require attribution of specific user IDs based on previous messages sent to that user, you can use the SMS Delivered event to attribute Inbound Received events to the user ID who most recently received a message from your Braze number.
If we detect that this inbound message is a reply to an outbound campaign or Canvas component sent from Braze, we will also include the campaign or Canvas metadata with the event. Braze defines a reply as an inbound message coming within four hours of an outbound message. However, there is a one-minute cache for the attributed campaign information of the last outbound SMS received.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// SMS Inbound Received: users.messages.sms.InboundReceive
{
"id": (required, string) unique ID of this event,
"user_id": (required, string) Braze user ID of the user,
"external_user_id": (optional, string) External ID of the user,
"app_group_id": (required, string) API ID of the workspace associated with the inbound phone number,
"time": (required, int) 10-digit UTC time of the event in seconds since the epoch,
"user_phone_number": (required, string) the phone number of the user who sent the message to your Braze number,
"subscription_group_id": (optional, string) ID of the subscription group which the phone number the user messaged belongs to,
"inbound_phone_number": (required, string) the phone number the message was sent to,
"action": (required, string) the subscription action Braze took as a r