How can we help?

REST Channel Overview

Overview

The REST channel utilizes Cordial's message automation functionality to make RESTful API calls to a specified endpoint. REST channel automations can be triggered by an event or set up to run on a recurring schedule.

There are a number of ways to take advantage of the REST channel. You can use the REST channel to trigger an API call that posts Cordial contact data to your CRM platform when a contact is added to a list; or you could implement a REST channel configuration that runs on a nightly basis in order to post contact order data to your CRM platform. This is only the beginning of what you can do with this powerful channel.

Just like batch and transactional messages within the Cordial platform, REST channel API calls are unique to each contact, allowing you to send a contact's attribute data, order data, event data, and more to an external database.

REST parameters

1. To create a new message using the REST channel, navigate to Messages > Create New Message and select Rest from the channel dropdown.

2. Click Edit in the REST Parameters pane and fill in the required fields:

Script

The following Smarty utilities are specific to the REST channel.

Utility Description Supported Methods Required
$utils->setPayload($array) Dynamically sets the request body. POST, PUT Required
$utils->setQueryStringParams($array) Optionally appends a dynamic query string to the request URL. GET Optional
$utils->setHeaders($array) Optionally adds dynamic key value pairs to your otherwise static headers. POST, PUT, GET Optional

$utils->setPayload($variable)

Parameters Description Required Expected Default
params Dynamically sets the request body. Required Array []

The Smarty utility $utils->setPayload($array) accepts an array of key value pairs that will generate the request body in the format selected by the content type input. JSON is currently the only format available, with additional formats to follow.

Example script

The following script will build the request body in JSON format for the values of email address and loyalty.

  {$utils->setPayload(['email' => $contact.channels.email.address, 'loyalty' => 'Gold'])}

Alternatively, you can set variables for email address and loyalty and reference them in the setPayload utility.

  {$payload.email = $contact.channels.email.address}
  {$payload.loyalty = 'Gold'}
  {$utils->setPayload($payload)}

Rendered payload

The following is the rendered payload in JSON format where email address is "john@example.com" for the previewed contact.

{
  "email": "john@example.com",
  "loyalty": "Gold"
}

You can preview how the payload will be rendered in the request body by clicking the Preview button in the REST Parameters pane and selecting a desired contact.

$utils->setQueryStringParams($array)

Parameters Description Required Expected Default
params Optionally appends a dynamic query string to the request URL. Required Array []

When using the GET method, you have the option to append a dynamic query string to the HTTP endpoint URL.

Example script

{$utils->setQueryStringParams(['email' => $contact.channels.email.address])}

Rendered HTTP endpoint URL where email address is "john@example.com" for the previewed contact:

https://api.cordial.io/v2/contacts?email=john@example.com

$utils->setHeaders($array)

Parameters Description Required Expected Default
params Optionally adds dynamic key value pairs to your otherwise static headers. Required Array []

You can add dynamic key value pairs to the headers using the setHeaders utility.

Example script

{$utils->setHeaders([key => $contact.key])}

Rendered header where the value for key is "123456" for the previewed contact:

key: 123456

HTTP endpoint

Enter the HTTP endpoint for the API you're accessing.

Note: Cordial has two distinct API addresses, so it's important to check which one is associated with your account:

Example HTTP endpoint

https://api.cordial.io/v2/contacts

If you need a dynamic query string appended to the HTTP endpoint URL, use the setQueryStringParams utility within the script input as described above.

HTTP request method

Choose one of the following HTTP request methods for the API call: 

  • GET
  • POST
  • DELETE
  • PUT

HTTP request headers

Add any necessary headers to authorize the API call by clicking the Add Header button and adding the key value pairs.

Basic authentication

The REST channel currently supports HTTP basic authentication. Additional authentication methods will be made available in future iterations of the REST Channel.

Note: When using the basic authentication method, you must encode the API key using base64.

Example authentication header

If you need to create dynamic header values you may use the setHeaders utility within the script input as described above.

Content type

Using the content type input, choose which format to use for the API request body. Currently supported content types include:

  • application/json
  • application/JavaScript
  • application/XML
  • x-www-form-urlencoded
  • text
  • text/plain
  • text/HTML

REST post-processing

Post-processing script

You can perform post-processing on data that gets returned by the API response. With this option, it's useful to utilize the GET method to retrieve data values in the response object that can then be used to update contact profile data in your Cordial account.

To access values in the response object, prepend any keys with $response.body.

Other available objects include: $response.error, $response.httpCode and $response.transactionTime.

Example script

The following example script will update the contact attribute 'loyalty' with the loyalty value provided in the response body.

{$utils->updateContact(['loyalty' => $response.body.loyalty])}

 

Comments

0 comments

Please sign in to leave a comment.