Overview:

This Koopid How To covers the steps needed to integrate an API call in a Koopid workflow.

This Tech Note is intended for users with familiarity with a workflow-based customer experience builder, and an understanding of API integration for rich customer experience for their existing services.

*Note:  Koopid Supports Rest APIs Get and Post with a JSON body and a JSON response. The API called has to be a rest API with JSON payload. The Koopid platform doesn’t currently support form data, multi-part requests, or additional headers through an API call at this time.

An implied understanding is needed about the API being called, the response that will be received, and how to parse the data in the response.

Koopid allows customers to pass the response from an API through our workflows, to display the response as part of the JSON, this is just a passthrough, no handling involved.

Please verify that the API being called and the data received is working as expected, and have an understanding of what the expected output is, before attempting to add the API to a Koopid workflow.

Types of REST API Calls Supported on the Koopid Platform

There are 2 types of API Calls supported on the Koopid platform: Server-Side API Calls and Client-Side API calls, each having a different component you can use in your workflow. There’s the “External Service (Server)” component and the “External Service (Client)” component, both found in the middle of the right sub-menu of a workflow, when in Expert Mode.

With the Server-Side API component, the server makes the API calls, parses the response and assigns them to workflow variables.

With the Client-Side API component, the node is a JavaScript based plugin which calls the API directly from the client, without the server being involved.

When to use which type of API call

A Server-Side API call is useful in the following cases:

• For Social channels (because we cannot run client plugins in that environment.)
• If the remote server does not allow Cross-Origin Resource Sharing (CORS)

A Client-Side API call is useful in the following cases:

• If the API calls are not accessible outside of the enterprise, and all clients using the chat are within the enterprise (this is for use cases when the chat is deployed within an enterprise.)

If complex processing of a response is needed, it is more convenient to modify the client-side plugin to process the response to your specs.

Adding an API call to a Koopid workflow

Once you’re logged into the Koopid platform for your provider, toggle into Expert Mode, and expand the Services menu.

1. Click on Expert Flows, and locate the workflow where you’d like to add an API call and response.
2. Open the workflow you want to edit in the Design view. If this workflow was originally created through the Essentials mode through steps, make a copy of the workflow and rename it by removing the “ca_” found in the beginning of the workflow name.
   1. Anytime you need to modify this workflow you will need to go through Expert Flows, instead of accessing and modifying through the Services > Manage steps.
3. With your copied workflow in front of you in Design mode, locate the area of your workflow where you want to add an API call and response.
4. Drag an External Service (Server) component to the workflow from the middle of the right-side menu. With the component selected, click on the wrench in the right-side menu, next to the Select Plugin field, to configure the component.
5. Once the configuration parameters options are available, add the URL for the API in the URL field at the top.
6. On the second line, add the method you want to call the API with (in all capital letters) you can add the word: GET, POST, PUT or Delete.
   
   
7. Next, you can add JSON POST data to push data to your system via the API from the inputs in the workflow by adding the variables called in your API to line 3 (Optional body or JSON Post data).*Note: For this section, after the data is collected in the workflow, it’s important to understand what API URL you need to push the data to, and to which variables in your system.

Sample Workflow and Server-Side API Example

Below is an example of a workflow and API being called to show how the workflow and the API need to be setup within the Koopid platform to work.

Open the link below, copy the code and save to a JSON file on your desktop to review and modify as needed.

server-side-api example

• API Specification:
• URL: not exceeding more than 1024 characters, can contain query parameters
• Method: GET, POST, PUT
• Headers:
• – Content-Type: application/json
• – Accept: application/json

How to assign JSON response to workflow variable

JSON Response	Assigning JSON response to workflow variable
{ "name":"John", "age":40, "email":{      "primary":"john@domain1.com",      "secondary":"john@domain2.com" }, "address":{      "line1":"23, New Park",      "line2":"Newark",      "zip":"12345" }, "phone":[      "9999999999",      "8888888888" ] }	How to assign JSON field (name) into workflow variable (wfName)? wfName:name Result: {{wfNam}} => John
	How to assign JSON object (email) into workflow variable (wfEmail)? wfEmail:email Result: {{wfEmail}} => {"primary":"john@domain1.com","secondary":"john@domain2.com"}
	How to assign JSON field (zip) from nested JSON into workflow variable (wfZip)? wfZip:address.zip Result: {{wfZip}} => 12345
	How to assign JSON array (phone) into workflow variable (wfPhone)? wfPhone:phone Result: {{wfPhone}} => ["9999999999","8888888888"]
	How to assign specific index of JSON array (0) into workflow variable (wfPhone0)? wfPhone1:phone[0] Result: {{wfPhone0}} => 9999999999