Add or import APIs
In addition to the various integrations supported by Yellow.ai, you can seamlessly integrate any third-party APIs with your chatbot. This comprehensive guide provides step-by-step instructions on connecting your chatbot to external APIs, enabling real-time data storage and retrieval for creating a personalized user experience.
Add a new API
There are two ways by which you can add API:
Add API manually
Go to Studio > API > + Add new API.
In the pop-up screen, specify the API name, HTTP Method, and the request URL along with the query parameters.
Click Add new API to save the details.
Add request components for APIs
To use an API, you need to include parameters for requesting information, incorporate headers to notify the third party about the data being sent, and add a body when transmitting data to the API. Our platform also provides the option to modify settings related to an API.
Add query params
API parameters are essential components used when making requests to an API. They serve as specific instructions or information that you include with your request, helping the API understand and fulfill your requirements accurately.
To add params:
On the API details page, under PARAMS, click + Add Params
Enter params in key-value pairs and click Add.
Below are examples of key-value pairs for static and dynamic parameters: Static parameter:
- Key: botId
- Value: x766543323dwe_34
Dynamic parameter:
- Key: city
- Value: {{{city}}} In these examples: The botId key has a static value (it remains constant). The "city" key has a dynamic value represented as {{{city}}}, indicating that the value will be dynamically replaced with the actual value of the "city" parameter during runtime.
Add request headers
Headers in API requests are additional pieces of information sent alongside the main request.
To add headers:
On the API details page, under HEADERS click + Add headers
Enter headers in key-value pairs and click Add. For example, if you have are authenticating an API, set the Key as Authorization and the Value as the API key.
Add body
The body in an API is the main content of the request containing data or information that should be sent to the third-party server. For POST, PUT, or DELETE methods, you can add request body under the Body section.
Multipart/form-data is not supported.
To add a body:
On the API details page, under BODY, choose the format of the request body. The supported formats are x-www-form-urlencoded, JSON, XML, GRAPHQL, form-data and raw.
For JSON, XML, GRAPHQLform-data or raw body, type or paste the request body the available box.
For other formats, click + Add body and provide body params in key-value pairs.
To send dynamic data over body use "{{{value}}}".
- You can pass the access key or auth token in the way that the API is designed. You could pass it in the request URL, body, or headers. You can ignore this for APIs where no authentication is required.
Configuration
You can modify the API settings for optimal performance and security. This lets you manage timeout, retry strategies, and SSL enforcement, enhancing your control over communication for a more resilient and secure API integration.
Configuration | Description |
---|---|
Timeout | Maximum time allowed for API response |
Retry on failure (5xx) | Number of attempts to retry in case of server errors |
Follow redirect(s) | Determines if API should automatically follow redirects |
Encoding | Method used to encode data (e.g., JSON, XML) |
Use strictSSL | Enforces strict SSL certificate validation. You might not get response if this is enabled and there is some problem with SSL certificate. |
API alerts on | Events triggering alerts (e.g., errors, high traffic) |
Default message on invoking API | Default response or action when API is invoked |
API failure message (4/5xx code) | Message displayed upon API failure with specific codes |
enableMutualTLS | Enables mutual TLS authentication for enhanced security |
The Configure environment option is disabled in the Live/Production environment.
Import APIs (CURL/JSON)
If you have a CURL script, JSON file, or collection URL, you can conveniently import it to yellow.ai.
Go to Studio > API.
Click the arrow icon next to API management and select Import .
Import API from CURL
In Type, choose Curl .
In API name enter a unique name for the API. Use alpha-numeric characters without space.
In Import curl, copy past the CURL script and click Import.
The imported API will be available under API Management.
Import API(s) from a JSON file
If you have one or more APIs, save your collection in a JSON file and import them as mentioned in the following steps:
Choose Type as Collection or JSON depending on the file you want to import
Drag & drop the file in Import JSON or use the Upload file button to upload the file.
Click Import.
The imported API will be available under API Management.
Configure environment variables
Streamline API configuration across environments by using the Configure Environment Variable option. Instead of manually inputting endpoint or parameter values for each environment, this option allows you to define and manage values uniquely for each environment.
To add environment variables:
Go to Studio > API > Configure environment.
Enter the key, for example endpoint and enter the respective values for each environment. Click Save.
Include the key in API URL in the following format: {{{env.variablename}}} for example, {{{env.endpoint}}}
Choose the environment and click Send to test the API. A 2xx response indicates that the API works successfully.
Test the API
To verify the proper functioning of the added API, input all API details and select the SEND button adjacent to the API. A sample response will be visible if the API works properly.
Confirm the expected functionality of the API and click Save to save the API settings.
API response has a size limit of 250kb. You will get an error if the response exceeds the limit.
Before testing the API, choose the respective environment from the drop-down.
Configure MTLS authentication
MTLS(Mutual Transport Layer Security) authentication is a method used for securing APIs by ensuring the integrity and authenticity of messages exchanged between the client and the server. It provides a secure communication channel and verifies that the messages have not been tampered with during transmission.
Retrieve the following information from the system where you are integrating APIs:
Domain
Certificate
Key
Certificate Authority
Click the lock button at the right end.
Fill in the fields and click Upload to upload the required documents.
Click Save when you're done.
Developer, Admin and Super admin roles can view this feature but only the Super Admin can make changes such as add a new certificate, delete the existing certificate, etc. Only the Super Admin can view the key.
Export APIs
Exporting APIs involves capturing their configuration settings, allowing for seamless sharing, backup, or replication. Follow these steps to export APIs:
Go to Studio > API.
Click the arrow icon next to API management and select Export .
Select the APIs to be exported, you can also select Select all APIs at the left bottom to select all the APIs in one go
Click Export.
Troubleshooting
API is not working, or the module is not showing any response
- Disabling Use Strict SSL can sometimes resolve connectivity issues, especially if there are problems with SSL certificates. Ensure that you're aware of the security implications before making changes to SSL settings.
API works in Postman and API management but gives a blank response when tested in Node.
Check your dynamic environment variables. Ensure you pass the variables in triple braces -
{{{env.variable}}}
.In Postman, it would be in double braces -
{{env.name}}
.For cRUL requests, instead of creating the API separately, import the cURL request to prevent errors in the cloud.