Architect Channel: Using Call an API

You can set up the Call an API element by following these step-by-step instructions:

1. Add Call an API element

• Add a new Call an API element to the selected Journey or Canvas.
  

2. Select the method and enter the endpoint

Request method

The request method that you should use will vary based on the endpoint to which you are planning to send information. The majority of the time, you’ll be using POST.

See the other request methods that you can use in your Call an API element below:

• POST - an HTTP method designed to send significant amounts of data to a server from a specified resource.
• GET - a method used to request data from a specified resource and should have no other effect.
• PUT - an idempotent method whose responses are not cacheable.
• DELETE - a method used to remove a resource from the collection of resources. 

URL

When an API interacts with another system, the touchpoints in such a communication are considered endpoint URLs.

To add any dynamic values, click to Add Dynamic Content button.

When you select the attribute, it will be added to the URL.

3. Set headers

Certain endpoints (URLs) may require that you include headers in your request. You can add as many headers as you like. Common use cases for request headers include a content-type specification and authorization headers that contain your credentials along with your vendor or system. Content-type specifications have the key ‘Content-Type’ and the default value as application/json.

The header section includes two settings:

• Enter Key: An API key is a token that a client provides when making API calls.
• Enter a value: Each API Key should have a value. For example, you can add a token as an API key and enter its value.

You can click the Add Header button at the bottom section to add multiple headers.

To add any dynamic content, click the Add Dynamic Content button to select an attribute.

4. Configure the body

Body is the information that the request will send to the URL that you specified. The ‘body’ is also known as payload. It should be in JSON format. 

You can click the Add Dynamic Content button to add default and custom user attributes, and event parameters as well as cart, browsed, and purchased items. You can also add Journey ID and Campaign ID as dynamic content. The attribute will be added to the body where your cursor is. Read more on dynamic content.

You can also add a fallback value for your dynamic content so that the corresponding value will be filled with it when there is no value to be shown. You can know that the dynamic content has a fallback value if it has the dark blue coloring on it.

5. Call an API Response (Optional)

Call an API Response Management enables you to get data from your internal or external systems through the Call an API element. You can send information or requests to your endpoints, and retrieve information from them. To enable this option, refer to Call an API Response.

6. Bypass API Throttling

To bypass the Call an API Throttling you configured, check the Bypass API Requests Throttling box.

7. Test your API request

Before launching your journey, you may want to test the Call an API element to make sure that the request is formatted properly. You can click the Test API button on the bottom-right corner. Your test might give one the following responses: 

• 2XX - Success
• 4XX - Fail

You can also see the reason for the status below the results.

8. Save as template

You can save your Call an API settings, including Method, Headers, and Body as a template.

After saving Call an API settings as a template, you can reach your templates via the Select Template button. You can re-use, edit and delete your templates from the template store. 

9. Rename channel name

Channel Name is generated by default based on journey name and channel type. You can rename it at the top right corner if you want to give it a different name.

10. Save Call an API element

After configuring Call an API settings, you can save the page. Make sure to click the Save button as there is no autosaving on this page. Autosaving functions only on the canvas page.

Example Payloads

Here are some examples of Call an API Elements for various third-party integrations.

Line

You can use Call an API for any current API you have, provided that you fulfill the conditions of a JSON POST request as specified in the Call an API steps above.

Below you can see an example for LINE which is one of the existing payloads in Call an API along with other payload examples.

{
  "to": [
	"{{d_phone_number}}"
  ],
  "messages": [
	{
  	"type": "text",
  	"text": "Hello, user"
	},
	{
  	"type": "text",
  	"text": "May I help you?"
	}
 ]
}

See Line for further details.

Zendesk

{
  "ticket": {
	"subject": "<user.company_name> has cancelled their account",
	"comment": {
  	"body": "<event.feedback>"
	},
	"requester": {
  	"name": "{{user.firstname}} {{user.lastname}}",
  	"email": "{{user.email}}"
	}
  }
}

See Zendesk for further details.

Viber

{ 
   "receiver":"01234567890A=",
   "min_api_version":1,
   "sender":{ 
      "name":"Jane Doe",
  	"avatar":"http://avatar.example.com"
   },
   "tracking_data":"tracking data",
   "type":"video",
   "media":"http://www.images.com/video.mp4",
   "thumbnail":"http://www.images.com/thumb.jpg",
   "size":10000,
   "duration":10
}

See Viber for further details.