Making an API call

Messages sent by Braze can retrieve content from a web server to be included in a message by using the {% connected_content %} tag. Using this tag, you can assign or declare variables by using :save. Aspects of these variables can be referenced later in the message with Liquid.

For example, the following message body will access the URL http://numbersapi.com/random/trivia and include a fun trivia fact in your message:

1
2
{% connected_content http://numbersapi.com/random/trivia :save result %}
Hi there, here is fun some trivia for you!: {{result.text}}

You can also include user profile attributes as variables in the URL string when making Connected Content requests. For example, you may have a web service that returns content based on a user’s email address and ID. If you’re passing attributes containing special characters, such as the at sign (@), make sure to use the Liquid filter url_param_escape to replace any characters not allowed in URLs with their URL-friendly escaped versions, as shown in the following email address attribute.

1
2
3
Hi, here are some articles that you might find interesting:

{% connected_content http://www.yourwebsite.com/articles?email={{${email_address} | url_param_escape}}&user_id={{${user_id}}} %}

If the URL is unavailable and reaches a 404 page, Braze will render an empty string in its place. If the URL reaches an HTTP 500/502 page, the URL will fail on retry logic. Because Braze delivers messages at a very fast rate, be sure that your server can handle thousands of concurrent connections so the servers do not get overloaded when pulling down content. When using public APIs, ensure your usage will not violate any rate-limiting that the API provider may employ. Braze requires that server response time is less than 2 seconds for performance reasons; if the server takes longer than 2 seconds to respond, the content will not be inserted.

If the endpoint returns JSON, you can detect that by checking if the connected value is null, and then conditionally abort the message. Braze only allows URLs that communicate over port 80 (HTTP) and 443 (HTTPS).

Using basic authentication

If the URL requires basic authentication, Braze can generate a basic authentication credential for you to use in your API call. You can manage existing basic authentication credentials and add new ones in the Connected Content tab of Manage Settings.

To add a new credential, click Add Credential. Give your credential a name and enter the username and password.

You can then use this basic authentication credential in your API calls by referencing the token’s name:

1
Hi there, here is fun some trivia for you!: {% connected_content https://yourwebsite.com/random/trivia :basic_auth credential_name %}

Using token authentication

When using Braze’s Connected Content, you may find that certain APIs require a token instead of a username and password. Included in the following call is a code snippet to reference and model your messages off of.

1
2
3
4
5
6
7
8
9
10
11
12
{% assign campaign_name="New Year Sale" %}
{% connected_content
     https://your_API_link_here/
     :method post
     :headers {
       "X-App-Id": "YOUR-APP-ID",
       "X-App-Token": "YOUR-APP-TOKEN"
  }
     :body campaign={{campaign_name}}&customer={{${user_id}}}&channel=Braze
     :content_type application/json
     :save publication
%}

Using Open Authentication (OAuth)

Some API configurations require retrieval of an access token that can then be used to authenticate the API Endpoint that you want to access.

Retrieve the access token

The following example illustrates retrieving and saving an access token to a local variable which can then be used to authenticate the subsequent API call. A :cache_max_age parameter can be added to match the time that the access token is valid for and reduce the number of outbound Connected Content calls. See Configurable Caching for more information.

1
2
3
4
5
6
7
8
9
10
{% connected_content
     https://your_API_access_token_endpoint_here/
     :method post
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "Bearer YOUR-APP-TOKEN"
  }
     :cache_max_age 900
     :save token_response
%}

Authorize the API using the retrieved access token

Now that the token is saved, it can be dynamically templated into the subsequent Connected Content call to authorize the request:

1
2
3
4
5
6
7
8
9
{% connected_content
     https://your_API_endpoint_here/
     :headers {
       "Content-Type": "YOUR-CONTENT-TYPE",
       "Authorization": "{{token_response}}"
  }
     :body key1=value1&key2=value2
     :save response
%}

Connected Content IP whitelisting

When a message using Connected Content is sent from Braze, the Braze servers automatically make network requests to our customers’ or third parties’ servers to pull back data. With IP whitelisting, you can verify that Connected Content requests are actually coming from Braze, adding an additional layer of security.

Braze will send Connected Content requests from the following IP ranges. The listed ranges are automatically and dynamically added to any API keys that have been opted-in for whitelisting.

Braze has a reserved set of IPs used for all services, not all of which are active at a given time. This ensures that if Braze needs to send from a different data center or do maintenance, Braze can do so without impacting customers. Braze may use one, a subset, or all of the following IPs listed when making Connected Content requests.