API

Learn how to use our product with this module.

Performs an API call to a 3rd party service and adds the resulting data to your dataset.


Module Overview

Key

API

Type

MODULE

Runtime

SERVER_BEFORE_PROMPT, SERVER_AFTER_PROMPT

Data

Accepts: Yes
Forwards: No

Runtime

The API module will always run twice, once before the prompt is sent to AI and once after. When running before, the content of the API's response will be added to the AI prompt as context and used by Bella to better answer the user's prompt.

You can distinguish the two runs by checking the runtime field in the payload, which will be set to either BEFORE or AFTER. The AFTER payload will also contain the response data, which will include the original API call's response as well as the AI model's response.

Body Payload

The body of any POST, PUT, or PATCH request will abide by the following interface, with data being present whenever available:

The supplemental user data represented by the [key: string]: any; line is any data collected about the user, with common keys being NAME, EMAIL, and PHONE, which are often collected using the CONTACT module.
Note that you can synchronize user IDs between Bella and your system by passing your internal user ID for the user into the web component when you add it to your site. This will then be used as the user.internal_id field in the payload.
You can also pass any custom metadata you want to include with the API call when adding the web component, such as customInternalId or someOtherValue. This data will then be included in the payload as well, under the metadata object.
{
    id: string; // A unique ID for this module execution
    chat: {
        id: string;
        ended_at: string;
        user_id: string;
        ai_model: string;
        confirmation_code: string;
        assistance_code: string;
        summary: string;
        raw_data: any;
        data_set_id: string;
        client_id: string;
        client_user_id: string;
    };
    question: {
        id: string;
        client_id: string;
        question: string;
        is_universal: boolean;
        parent_question_id: string;
        data_set_id: string;
    };
    dataset: {
        id: string;
        client_id: string;
        internal_id: string;
        title: string;
        description: string;
        dataset: any;
        definitions: any;
    };
    runtime: "AFTER" | "BEFORE" | "FORWARD";
    prompt: string;
    questionId: string;
    moduleId: string;
    user: {
        id: string | null;
        times_spoken: number;
        locale: 'en_US';
        internal_id: string | null;
        is_active: boolean;
        [key: string]: any;
    };
    response: {
        api: any;
        ai: any;
    };
    // This is any custom metadata you passed in via the web component.
    metadata: { [key: string]: any; };
    // This is the data you added within the module's "body" setting field.
    _appendData: any;
    // This is any data that was forwarded to this module from other modules.
    _forwardedData: any;
}

Settings

Setting Key Type Default Value Description
url string - The URL you are making the call to. Note that we only support JSON-based APIs at this time. Also note that the URL can contain placeholders for dynamic metadata values added to the web component. So for example, if your web component tag includes the _songId input parameter, the URL can contain a placeholder such as https://yourapi.com/song/%songId%.
isAuth boolean false If this call requires some for of authentication, set this to true and provide the key in the "authKey" setting.
authKey string - If isAuth is true, you need to provide the API key or auth token here. All keys are securely encrypted and stored outside of our database in a secure key vault. Note that if you're using a form of authentication like Bearer token, you'll need to provide the preface here as well, ie "Bearer YOURTOKEN" instead of just "YOURTOKEN".
authHeader string - If authKey is true, you need to provide the name of the auth header here.
type GET - POST, GET, PUT,PATCH,DELETE
body strong %data% The body of your API call. If blank, we will forward any data that's been forwarded to this module as the body.
headers array IHeader[] An array of additional headers to include with the request.
addConnectKey boolean - If set to true, we will add your secure connect key to the "User-Agent" header of the request, allowing you to confirm the authenticity of the call. The standard User-Agent header is "BellaAI API", however with this set to true it becomes "BellaAI API (YOUR_CONNECT_KEY)". You can find or change your connect key in your AI agent dashboard.
cacheTimeInSeconds integer 0 If higher than zero, how long to cache to result of the API call for.

IHeader

Headers and not store securely and therefore should not include sensitive data, such as auth tokens or keys. Please use the authHeader for that.

[
    {
        "key": "Header-Name",
        "value": "Header-Value"
    }
]

Data Forwarding

The API module can accept data from other module. In the event that this happens, the forwarded data will be available in the _forwardData object in the payload and the runtime will be set to FORWARD.

{
    id: "RandomUniqueId",
    runtime: "FORWARD",
    _forwardedData: {
        key1: "value1",
        key2: "value2",
        etc..
    }
}