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: { // Intention corresponding to the user's request
    name: string;
    confidence: number; // Match index
    inputs: {}; // Value of intention 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.