Skip to main content

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

  1. Go to Studio > API > + Add new API.

  2. In the pop-up screen, specify the API name, HTTP Method, and the request URL along with the query parameters.

    drawing
  3. 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:

  1. On the API details page, under PARAMS, click + Add Params

  2. Enter params in key-value pairs and click Add.

    drawing

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:

  1. On the API details page, under HEADERS click + Add headers

  2. 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.

    drawing

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.

note

Multipart/form-data is not supported.

To add a body:

  1. 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.

  2. 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.

    drawingdrawing

To send dynamic data over body use "{{{value}}}".

note
  • 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.

drawing
ConfigurationDescription
TimeoutMaximum 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
EncodingMethod used to encode data (e.g., JSON, XML)
Use strictSSLEnforces strict SSL certificate validation. You might not get response if this is enabled and there is some problem with SSL certificate.
API alerts onEvents triggering alerts (e.g., errors, high traffic)
Default message on invoking APIDefault response or action when API is invoked
API failure message (4/5xx code)Message displayed upon API failure with specific codes
enableMutualTLSEnables mutual TLS authentication for enhanced security
note

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.

  1. Go to Studio > API.

  2. Click the arrow icon next to API management and select Import .

Import API from CURL

  1. In Type, choose Curl .

    drawing
  2. In API name enter a unique name for the API. Use alpha-numeric characters without space.

    drawing
  3. In Import curl, copy past the CURL script and click Import.

  4. 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:

  1. Choose Type as Collection or JSON depending on the file you want to import

  2. Drag & drop the file in Import JSON or use the Upload file button to upload the file.

    drawing
  3. Click Import.

  4. 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:

  1. Go to Studio > API > Configure environment.

  1. Enter the key, for example endpoint and enter the respective values for each environment. Click Save.

    drawing
  1. Include the key in API URL in the following format: {{{env.variablename}}} for example, {{{env.endpoint}}}

  1. 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.

API Response

Confirm the expected functionality of the API and click Save to save the API settings.

note
  • 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:

  1. Domain

  2. Certificate

  3. Key

  4. Certificate Authority

  5. Click the lock button at the right end.

  6. Fill in the fields and click Upload to upload the required documents.

  7. Click Save when you're done.

note

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:

  1. Go to Studio > API.

  2. Click the arrow icon next to API management and select Export .

  3. 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

    drawing
  4. 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.