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
:
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)}
}
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
.
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:
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.
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:
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.