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.

Use cases

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: Smarty syntax that builds the request payload or adds dynamic headers and query string parameters.
• HTTP endpoint: the API endpoint.
• HTTP request method: the request method the API call uses.
• HTTP request headers: optional request headers to be included in the API call.
• Content type: determines the format of the payload.

Script

The following Smarty utilities are specific to the REST channel.

$utils->setPayload($variable)

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.

• 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)}
  

• 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)

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

• {$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)

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

• {$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.

Cordial has two distinct API addresses, so it's important to check which one is associated with your account: 1.) For accounts located at HTTPS://admin.cordial.io/, the associated API URL is https://api.cordial.io/v2/ 2.) For accounts located at HTTPS://usw2.admin.cordial.io/, the associated API URL is https://api.usw2.cordial.io/v2/.

• 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.

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

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

• 

  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

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.

• 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])}