API¶
Automation without connection to your Information System, APIs, databases ... will certainly be of little interest.
API resources allow you to call any external HTTP API.
These API might return either directly executable Prisme.ai workflows or raw data that would be displayed / processed later on.
The configuration of this resource is designed to allow calling the widest posible range of APIs. If you are missing a particular option to properly format your request, please contact us or use the function resource to write the HTTP call in plain Javascript.
The call of your described API will then be a simple action step inside your workflow.
Example of use :
- You create a "Weather" webhook which gives you the temperature, wind and humidity for a city.
- Then as soon as you need the weather forecast in your workflows, you would add a step "Call a Webhook" and select "Weather".
1. Creation¶
Upon creation of your API resource, only its URL is required. More parameters show up on the next screen :
- Parameters to inject as GET parameters and inside your request body (unless any custom request body is defined)
- HTTP method GET, POST, PUT, ou DELETE. Defaults to POST
- Custom request body
- HTTP headers
- Basic authentification: to secure your API using some credentials
- JSON Filter : JSON path to extract from the API response
The same options will be available when calling your resource, allowing you to inject user values in your request at runtime.
2. Request body default content¶
If you do not customize your request body and the HTTP method is not GET, your API will receive the following object :
interface request {
timestamp: string; // DateTime of the call
sessionId: string; // Session identifier
bot: {
id: string; // Wizard identifier
};
user: { // Current user
id: string; // User ID
location: string; // Location of the user if authorized by the user
platform: string; // User agent platform
conversationSize: number; // Number of messages in the conversation
conversationId: string; // ConversationId: string; // ConversationId identifier
};
userMessage: { // User message
event: string; // If the user's message is an event, its name
text: string; // If it's text, its content
payload: {}; // If the message contains an arbitrary object, this one
}
originalRequest: {}; // Object of arbitrary parameters passed to the injection script
lang: string; // User's browser language
query: string; // Request sent by the user
event: string; // Event sent by the user
fulfillment: { // Responses generated by the workflow before arriving at the function
stream: {
type: string;
resourceId: string;
}[];
intent: { // Intent corresponding to the user's request
name: string;
confidence: number; // Match index
inputs: {}; // Value of intent parameters
};
contexts: { // Contexts
lifespan: string; // Lifetime
required: boolean; // If required
name: string; // Name
parameters: {}; // Associated parameters
scope: string; // Perimeter
}[];
endConversation: boolean; // If the convesation is over
}
Example :
body: { "id": "",
"timestamp": "2018-09-21T12:02:39+00:00",
"sessionId": "BxopMtpjDl5Pfrc4",
"user": { "platform": "web", "conversationSize": 1 },
"lang": "fr",
"query": "Je souhaite réserver trois chambres pour 4 personnes avec petit déjeuner",
"endConversation": false,
...
"status": { "code": 200, "errorType": "success" }
}
3. Response¶
The API can either return raw data or a ready-to-execute Prisme.ai workflow :
// Returns raw data to display / process later on
return [{"title": "Hello World"}];
// Return a workflow with 1 text response followed by one button
return [
{
type: "text",
text: "Hello World",
},
{
type: "button",
text: "Click me",
},
];
More information on workflows here.