Skip to main content

API Client Module

Introduction​

Use the module API Client to send a request to an external API. This will allow you to send data from LoyJoy as URL parameters or POST payload and save the data from the response as variables.

Typical Use Cases / Examples​

Typical use cases are exporting data from LoyJoy to your web service or reading data from external resources.

Reading data from an external service​

As an example, we want to read the current price of a product to be shown in the chat flow.

To do this, we set the method to GET and enter the URL with the ID of the product, for example http://example.org/getPrice?product-id=123abc. We could also use a dynamic product ID, for example stored in the LoyJoy variable product_id. Then the URL would be http://example.org/getPrice?product-id=${product_id}.

Let's assume this request will generate a JSON response body of this form:

{
  "price": {
    "amount": 125,
    "currency": "Euro",
    "validUntil": "2022-12-31"
  },
  "productId": "123abc"
}

We can then map the field price.amount of the response body to a variable of our liking, for example product_price: grafik

By going through this process module, the GET request will be executed and the product_price variable will be filled with the value from the request. Afterwards, the product_price variable can be used in any text field.

Sending data to an external service​

This can be useful to transfer customer data to an existing database, for example to subscribe them to a mailing list or register them. Here we use the POST method and enter a URL such as http://example.org/subscribe.

In this case we are using a JSON post body and simply enter the JSON into the payload text field. In the payload we use the ${} notation to access the variables present in the LoyJoy chat:

{
  "email": ${email},
  "firstName": ${firstname},
  "lastName": ${lastname},
  "birthdate": ${birthdate},
  "marketingOptIn": ${toBoolean(consent_single_opt_in_newsletter)},
  "consumption": ${toInteger(consumption)},
  "key": ${stringConcat(lastname, ", ", birthdate)}
}
note

Datatypes will be handled automatically based on the data type in LoyJoy. All variables are stored as Strings in LoyJoy. Because of that, we need to use type conversion functions such as toBoolean and toInteger to send these types. See this page for a full list of type conversion functions. Other datatypes exist in LoyJoy e.g. as the output of functions such as randomInt.

note

You can use expression in the JSON body. These expressions should not be surrounded by quotes:

{
  "key": ${stringConcat(lastname, ", ", birthdate)}
}

The variables in this example are all standard LoyJoy variables. You can look up the standard LoyJoy variable here and here. Additionally, you can also use custom variables defined questionnaires or other modules.

Again, we can interpret the response body as JSON. For example we get a response body such as:

{
  "status": "success",
  "subscriberId": "9cc2d7a1-888f-49bd-a169-5d196c900ced"
}

We can create a mapping that will read the status field of the response and map it to a variable of our liking: grafik

Depending on the status, we can then, for example, tell the customer that they were successfully subscribed or that there was an error.

How to Use the Module​

Send a GET or POST request to any URL. You can add a custom payload to your post requests and use variables in this payload using the ${variable} syntax. If the URL returns a JSON response, you can use mappings to map a JSON field to a LoyJoy variable.

Authentication​

Currently, there are three possible authentication modes available:

  • Basic auth
  • Bearer auth
  • OAuth2 (Password and Client Credentials flows)

HTTP Methods​

Currently three HTTP methods are supported

  • GET
  • POST
  • PUT

POST / PUT Body Types​

Three different POST and PUT body types are supported

  • JSON
  • File (Base64 encoded)
  • x-www-form-urlencoded (key-value pairs)

Cookies​

Cookies received in responses can be set via an allow list. Already saved cookies can be sent in future requests using the allow list as well.

Headers​

Headers can be used in both directions. To add a request header, you can simply enter a valid expression and a header name. grafik

To save response headers, you can create an entry with the header key to save and enter a variable name to save the header entry under: grafik

Response status​

The response status of the request will be saved with the variable name api_client_status_code.

Response body​

When no mappings are defined to map a JSON reponse body, the complete response body is saved under the variable name api_client_response_body.

File Transfer via API Client​

To transfer files you can use the <variable_name>_url variable that is automatically created when a file is uploaded to LoyJoy. See also here.

Timeouts​

The process module waits for a response from the server for around 20 seconds. If the server does not respond within this time, the process module will classify this as a timeout. There are multiple solutions to this problem.