Skip to main content

​
Overview

The REST API connector allows you to integrate external services and APIs with Natalia. This includes sending HTTP requests to any endpoint and using the responses within your Natalia scenarios. Everything you configure here becomes part of Natalia’s training sheet (main prompt), allowing her to naturally understand when and how to use these integrations.

​
Important Notes

  • All connector configurations are automatically added to Natalia’s training
  • Write clear descriptions - Natalia understands natural language
  • Link connectors to scenarios where they’ll be used

​
Configuration in Dashboard

​
Request Setup

  1. Name and Description
    • Give your connector a clear name
    • Provide a detailed description of its purpose
    • Example: “Retrieve user’s order status using the order reference number”
  2. API Configuration
    • Select the HTTP method (GET, POST, PUT, PATCH)
    • Enter the API endpoint URL
    • Configure headers and parameters as needed
  3. Parameters Description Describe parameters in natural language: 🇬🇧 English:
    • “The query is the customer’s question or request, like asking about a product or dimensions”
    • “The reference number is the order’s unique identifier”
    • “The customer email is used to look up their account”
    🇫🇷 French:
    • “La requête est la question ou demande du client, comme une question sur un produit ou des dimensions”
    • “Le numéro de référence est l’identifiant unique de la commande”
    • “L’email du client est utilisé pour rechercher son compte”

​
Request Configuration Details

The REST API connector supports various request configurations:
  1. HTTP Methods
    • GET: Retrieve data
    • POST: Create data
    • PUT: Update data
    • PATCH: Partial updates
  2. Headers Add custom headers like authorization tokens or content types.
  3. Parameters Configure URL parameters and query strings.
  4. Body For POST/PUT/PATCH requests, define the request body structure:
    • Support for string, number, object, and array types
    • Nested object structures (including deeply nested objects)
    • Arrays of items

​
Auto-fill and Fixed Values

For each field in the request body and parameters, you can choose between two modes:
  • Auto-fill (default): Natalia will automatically generate the value for this field based on the context and the field’s description.
  • Fixed Value: You can specify a fixed value that will always be used for this field, regardless of the context. This is useful for fields that should always have the same value, such as API keys (in headers), action types, or filter operators.
To configure this, you can use the autoFill and value properties in the JSON schema:
  • autoFill: A boolean value. Set to true to enable auto-fill (default), or false to use a fixed value.
  • value: If autoFill is set to false, this property specifies the fixed value to use.

​
Body Structure Example (JSON)

{
  "user": {
    "type": "object",
    "required": [
      "name",
      "email"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "User's name",
        "x-autoFill": true
      },
      "email": {
        "type": "string",
        "description": "User's email address",
        "x-autoFill": true
      },
       "status": {
        "type": "string",
        "description": "User status",
        "x-autoFill": false,
        "x-value": "active"
      }
    }
  },
  "description": {
    "type": "string",
    "description": "Request description",
     "x-autoFill": true
  },
   "deeplyNestedObject": {
        "type": "object",
        "properties": {
            "level1": {
                "type": "object",
                "properties": {
                    "level2": {
                        "type": "object",
                        "properties": {
                            "fixedValue": {
                                "type": "string",
                                "x-autoFill": false,
                                "x-value": "constant"
                            },
                            "dynamicValue": {
                                 "type": "string",
                                "x-autoFill": true,
                                "description": "A dynamically generated value"
                            }
                        }
                    }
                }
            }
        }
    }
}
This example demonstrates how to use autoFill and value to control whether a field is automatically filled by Natalia or uses a predefined value. It also includes an example of a deeply nested object. You can use this same approach for URL parameters as well. For example: 
/?search={'filter':[{'op':'eq','field':'mobilePhone','value':"06112233442"}]}
Could be configured with ‘op’ and ‘field’ having "x-autoFill": false and their respective fixed value, and ‘value’ within the filter having "x-autoFill": true, allowing Natalia to dynamically populate the phone number.

​
Best Practices

  1. Clear Descriptions
    • Use natural language in descriptions
    • Be specific about when to use the connector
    • Describe expected outcomes
  2. Testing
    • Test with various inputs
    • Verify error handling
    • Validate responses
  3. Security
    • Use environment variables for sensitive data
    • Implement proper authentication
    • Follow least privilege principle
  4. Error Handling
    • Always include error responses in your API documentation
    • Test your connector with invalid inputs
    • Handle rate limits appropriately
  5. Documentation
    • Document the purpose of each field
    • Include example requests and responses
    • Note any dependencies or prerequisites

​
Using in Scenarios

All connector details—names, descriptions, and parameters—are automatically incorporated into Natalia’s training and scenario logic. Because of this, you don’t need to explicitly mention the connector name or its parameters in your scenario’s training sheet. However, it is important to be as detailed as possible when configuring each connector so Natalia knows exactly when and how to use it.

​
Natural Language Usage

You can describe how and when Natalia should use the API in plain language. For example: 🇬🇧 English:
  • “When a customer asks about their order status, retrieve it using their order number”
  • “Create a support ticket when the customer has a technical problem”
  • “Look up the customer’s information when they provide their email address”
🇫🇷 French:
  • “Quand un client demande le statut de sa commande, récupère-le en utilisant son numéro de commande”
  • “Crée un ticket de support quand le client a un problème technique”
  • “Recherche les informations du client quand il fournit son adresse email”

​
Customer Information Lookup

🇬🇧 “Use this connector when:
  • A customer asks about their account
  • We need to verify customer details
  • Looking up purchase history”
🇫🇷 “Utilise ce connecteur quand :
  • Un client pose des questions sur son compte
  • Nous devons vérifier les détails du client
  • Recherche d’historique d’achats”

​
Order Management

🇬🇧 “Retrieve order information when:
  • Customer asks about order status
  • Tracking information is needed
  • Order details are requested”
🇫🇷 “Récupère les informations de commande quand :
  • Le client demande le statut de sa commande
  • Les informations de suivi sont nécessaires
  • Les détails de la commande sont demandés”

​
Handling Connector Responses

You can define how Natalia should respond based on the connector’s returned status codes. For example:
  • HTTP 200 (Success)
    • 🇬🇧 “Your request has been received. We’ll take care of it right away.”
    • 🇫🇷 « Votre demande a bien été reçue. Nous allons nous en occuper immédiatement. »
  • HTTP 500 (Server Error)
    • 🇬🇧 “An unexpected error occurred. [transfer the user to a human agent]”
    • 🇫🇷 « Une erreur inattendue s’est produite. [transfère l’utilisateur à un agent humain] »
Because Natalia automatically understands how to invoke connectors and interpret responses, you only need to specify these outcome instructions (success, error handling, escalation, etc.) within your scenario logic. If you do have scenarios that depend on multiple connectors (e.g., a call-transfer connector to handle escalations), make sure each connector is well documented so Natalia knows when and how to chain them together.”

​
Troubleshooting

Common issues and solutions:
  1. Connection Errors
    • Verify endpoint URL is correct
    • Check network connectivity
    • Validate authentication credentials
  2. Invalid Responses
    • Review request format
    • Check API documentation
    • Validate data types
  3. Performance Issues
    • Monitor response times
    • Implement caching where appropriate
    • Consider rate limiting

​
Remember

  • All connector settings are automatically added to Natalia’s training
  • Link connectors to relevant scenarios
  • Test thoroughly before going live