The api_key
indicates the app title with which the data in this request is associated and authenticates the requester as someone who is allowed to send messages to the app. It must be included with every request as a HTTP Authorization header. It can be found in the Developer Console section of the Braze dashboard.
Parameters
Use these parameters to define your API requests. Though the parameters you need are listed under endpoints, this should give you more insight into their nuance and other specifications.
If you want to send push to a set of device tokens (instead of users), you need to indicate on behalf of which specific app you are messaging. In that case, you will provide the appropriate App Identifier in a Tokens Object. It can be found in the Developer Console section of the Braze dashboard.
When sending a message to a segment or campaign audience using an API endpoint, Braze requires you to explicitly define whether or not your message is a "broadcast" to a large group of users by including a broadcast
boolean in the API call. That is, if you intend to send an API message to the entire segment that a campaign or Canvas targets, you must include broadcast: true
in your API call.
Broadcast is a required field and the default value set by Braze when a campaign or Canvas is made is broadcast: false
. You can't have both broadcast: true
and a recipients
list specified. If the broadcast
flag is set to true and an explicit list of recipients is provided, the API endpoint will return an error. Similarly, including broadcast: false
and not providing a recipient list will return an error.
Use caution when setting broadcast: true
, as unintentionally setting this flag may cause you to send your campaign or Canvas to a larger than expected audience. The broadcast
flag is required to protect against accidental sends to large groups of users.
For messaging endpoints, the campaign_id
indicates the API Campaign under which the analytics for a message should be tracked. A Campaign Identifier for each of the campaigns you have created can be found in the Developer Console section of the Braze dashboard. If you provide a Campaign Identifier in the request body, you must provide a message_variation_id
in each of the message objects indicating the represented variant of your campaign.
For campaign trigger endpoints, the campaign_id
indicates the API ID of the campaign to be triggered. This field is required for all trigger endpoint requests.
When using one of the endpoints for triggering or scheduling a Canvas via the API, you may provide a map of keys and values to customize messages sent by the first steps of your Canvas, in the "canvas_entry_properties"
namespace.
For example, a request with "canvas_entry_properties" : {"product_name" : "shoes", "product_price" : 79.99}
could add the word "shoes" to a message by adding {{canvas_entry_properties.${product_name}}}
.
A unique identifier for sending a message to specific users. This identifier should be the same as the one you set in the Braze SDK. You can only target users for messaging who have already been identified through the SDK or the User API. A maximum of 50 External User IDs are allowed in a request.
For campaign trigger endpoints, if you provide this field, the criteria will be layered with the campaign's segments and only users who are in the list of External User IDs and the campaign's segment will receive the message.
The segment_id
indicates the segment to which the message should be sent. A Segment Identifier for each of the segments you have created can be found in the Developer Console section of the Braze dashboard.
For message endpoints, if you provide both a Segment Identifier and a list of External User IDs in a single messaging request, the criteria will be layered and only users who are in both the list of External User IDs and the provided segment will receive the message.
For messaging endpoints, the send_id
indicates the send under which the analytics for a message should be tracked. The send_id
allows you to pull back analytics for a specific instance of a campaign send via the sends/data_series
endpoint. API and API trigger campaigns that are sent as a broadcast will automatically generate a send identifier if a send identifier is not provided.
If you want to specify your own send_id
, you'd have to first create one via the sends/id/create
endpoint. The send_id
must be all ASCII characters and at most 64 characters long. You can reuse a send identifier across multiple sends of the same campaign if you want to group analytics of those sends together.
Note that send_id
tracking is not available for emails sent via Mailjet.
Campaign conversions are attributed to the last tracked send_id
that the user received from that campaign, unless the last send the user received was untracked.
When using one of the endpoints for sending a campaign with API-Triggered Delivery, you may provide a map of keys and values to customize your message. If you make an API request that contains an object in "trigger_properties"
, the values in that object can then be referenced in your message template under the api_trigger_properties
namespace.
For example, a request with "trigger_properties" : {"product_name" : "shoes", "product_price" : 79.99}
could add the word "shoes" to the message by adding {{api_trigger_properties.${product_name}}}
.