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.
API
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.
The body of any POST, PUT, or PATCH request will abide by the following interface, with data being present whenever available:
[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.
user.internal_id
field in the payload.
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;
}
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. |
[
{
"key": "Header-Name",
"value": "Header-Value"
}
]
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..
}
}