Chatlayer Documentation
Get in touchAbout Chatlayer
  • Welcome
  • What's new
  • Send feedback
  • start quickly
    • Leadzy tutorial
      • 0. Introduction
      • 1. New bot, new block
      • 2. Understand your users
      • 3. Collect and display user input
      • 4. Steer the conversation with Conditions
      • 5. Empower your bot with Actions
      • 6. Set up a channel and publish your bot
    • Templates
      • Banking
      • E-Commerce Returns
      • E-Bike Shop
      • E-Scooter Support
      • Feedback
      • Find Nearest Location
      • GPT
      • 🆕Gym
      • Job applications
      • Knowledge base AI template
      • Lead generation
      • 🆕NPS
      • Restaurant
      • Retail
  • navigation
    • Analytics
      • Dashboard
      • Customers
      • Conversations
      • User flow
      • Intents
      • 🆕Funnels [Beta]
    • Bot builder
      • Flows
        • Canvas functionalities
        • Collaborate with team members
        • Manage your flows
        • 🆕[Beta] Export and import flows
      • Bot dialogs view
      • Translations
      • Events
    • NLP
      • Dashboard
      • Intents
      • Expressions
      • Entities
      • Train
      • NLP settings
      • Improve
    • Knowledge base AI
      • Add content to your KBAI
      • Build your KBAI flow
      • Use your KBAI source URL in a button
      • Use tags to limit your KBAI content
      • 🆕Use Tables to store your KBAI questions
      • 🆕Manage handover where KBAI is unsatisfactory
    • History
      • Conversations
      • Execution logs
      • Versions
    • Channels
    • Tables
      • Create a table with records
      • Column types
      • Operate on your records
        • Insert record
        • Update record
        • Retrieve record
        • Delete record
      • API
    • Settings
      • Bot settings
      • Offloading
      • Variables
      • Voice
      • Import/Export
  • build your bot
    • Conversation design
      • Plan your bot
      • Conversation design workflow
    • Flow logic
      • Blocks
        • Message
        • Condition
        • Collect input
        • Action
      • Go-to connections
    • 🆕Emulator
    • Tips & best practices
      • Route your flow depending on the time
      • Improve the Not understood block
        • How to create better not understood messages
        • Not understood counter
        • Not understood Google search
      • Go to previous block
      • Recognizing a returning user
      • Skip introduction message
      • Route your flow depending on the channel
      • Reuse flows
      • Connect two bots to each other
  • understand users
    • Natural language processing (NLP)
      • Basic NLP concepts
      • Detect information with entities
        • Match entities
        • Contextual entities
        • System entities
        • Composite entities
      • NLP best practices
        • Word order and diversity of expressions
      • AI intent booster
      • Train your NLP
      • Context
      • NLP import & export
      • Sentiment analysis
    • Languages
      • Supported languages
      • Make your bot multilingual
      • Change language within the conversation
  • set up channels
    • Add a channel to your bot
    • All channels
      • 🚨Facebook Messenger [Deprecated soon]
        • Facebook Admin Removal
        • Facebook Webview Whitelisting
        • Facebook Messenger API updates for Europe
      • 🚨Google Assistant [Deprecated soon]
      • Webhook
      • Web
        • 🚨Web V1 [Deprecated]
          • Customize web widget
          • Live example web widget
        • 🆕Web V2
          • 🆕From Web V1 to V2
          • 🆕Web V2 methods and options
    • Sinch Conversation API
      • Configure your Sinch Conversation API
      • 🆕 Make the most of RCS with Carousels
      • WhatsApp Business API
  • integrate & code
    • API calls
      • Configure your API integration
      • Advanced API features
      • V1 API Reference
      • Custom integrations 101
    • Code editor
      • [Example] Sending data to Airtable (POST)
      • [Example] Retrieving data from Airtable (GET)
      • [Example] Making SOAP requests
    • App integrations
      • Airtable
      • Freshdesk
      • Freshdesk Messaging
      • 🆕Gmail
      • Intercom
      • Mailgun
      • OpenAI: GPT-3, ChatGPT and GPT-4
      • Salesforce
      • 🆕Slack
      • Topdesk
      • Zendesk Support
      • Zendesk Sunshine (beta)
    • 🆕Expression syntax
    • Human handover & live chat
      • Sinch Contact Pro
      • #Interact
      • Genesys Cloud
      • Offloading Webhook
      • Salesforce Service Cloud
      • Sparkcentral by Hootsuite
      • Zendesk Chat
    • Chatlayer messages specifications
  • Publish
    • Publish your bot
      • Publish a flow
  • Analyze & maintain
    • Analytics definitions
    • Data retention
    • Maintenance
    • Session
    • Track events for analytics
  • VOICE
    • 🆕Send bot response as audio
    • Voicebots
      • Create a voicebot
      • Voicebot-specific actions
      • Test your voicebot
      • From chat to voice
  • access & support
    • Identity & Access
      • Single Sign-On (SAML SSO)
    • Billing & subscription
    • Get in touch
    • Chatlayer glossary
    • SaaS Regions & IP Ranges
    • Status
    • Debug your bot
      • No correct response
      • Collect input not working
      • Video isn't working
Powered by GitBook
On this page
  • Send an API request
  • Listen for an API response
  • Example

Was this helpful?

  1. integrate & code
  2. API calls

Configure your API integration

PreviousAPI callsNextAdvanced API features

Last updated 8 months ago

Was this helpful?

A Chatlayer API step is available in the blocks to enable you to create bot messages based on user-specific information and other external data, and to redirect your users to different flows based on your own business logic.

You can use this solution on any platform that supports receiving and responding to HTTP requests.

The API step sends a request to your backend server.

Send an API request

To configure your API step:

  1. Drop an block to your .

  1. Click on API.

  2. Configure your parameters. See below for more details.

HTTPS methods

The API step supports 5 HTTPS methods:

  • POST

  • GET

  • DELETE

  • PUT

  • PATCH

You can only define a request body when your request method is POST or DELETE.

Under the Query tab, add query parameters and/or a body payload by defining key value combinations. Each key can has 3 possible value types:

  • text: static text.

  • dialogstate: select a dialog state from the dropdown. The dialog state ID will be stored as value for the key. This ID can be used to redirect the user to a certain dialog state based on your business logic when sending back the API response.

The Authorization tab has the following components:

  • Basic auth: will display the fields to fill username and password.

  • Bearer token: will display the Token field to be filled in.

The Headers tab is where you configure your headers.

Body is where you can define a request body request in all HTTPS methods.

Under the Body tab, add query parameters and/or a body payload by defining key value combinations. Each key can has 3 possible value types:

  • text: static text.

  • dialogstate: select a dialog state from the dropdown. The dialog state ID will be stored as value for the key. This ID can be used to redirect the user to a certain dialog state based on your business logic when sending back the API response.

  • The amount key will have the value of user session variable transfer_amount (ex: 500).

  • The destination key will have the value of user session variable transfer_destination (ex: Elon Musk).

  • The accountType key will have the value of user session variable card_type (ex: savings_account).

  • The transactionSuccess key will have the dialog state identifier for the ‘successful transaction’ dialog state. This identifier can be used in the response of this API request to redirect the user to a new dialog state.

  • The transactionNoMoney key will have the dialog state identifier for the ‘unsuccessful transaction’ dialog state. This identifier can be used in the response of this API request to redirect the user to a new dialog state.

  • The test key will have a value of ‘5’.

This will result in the following body payload:

{
    "amount": 500,
    "destination": "Elon Musk",
    "accountType": "savings_account",
    "transactionSuccess": "successful transaction",
    "transactionNoMoney": "unsuccessful transaction",
    "test": 5
}

Listen for an API response

You do not need to configure the API plugin to listen for a response. This is done automatically and the API step will listen for what your API returns.

API return variables

The API step supports 3 types of return variables:

  • session: A session object for saving data in to the user session. The session has 2 mandatory fields:

    • namespace: a key namespace. The data object will be stored in this namespace key in the user session. You can access this object in Chatlayer.ai by using interpolation: {namespace.dataKey}.

    • data: an object which will be saved in the user session data in the namespace key.

  • action: an object defining an action such as redirecting the user to a next dialog state in the conversation.

    • nextDialogstate: a dialog state identifier to redirect the user to a next dialog state in the conversation flow.

The above 3 options are executed in the order shown above: session variables are set first, then messages are sent and then you will jump to the next dialog state.

Example

You can find a JSON example for these 3 cases in the code snippet below:

const result = {
  session: {
    namespace: 'myNamespace',
    data: { variable: 'test123' },
  },
  messages: [{ type: 'text', config: { textMessages: [{ text: 'random message 1' }] } }],
  action: {
    nextDialogstate: 'dialogstate-123-abc',
  },
};

Make sure you include the correct content type in the header: content-type: application/json;

Example

This example demonstrates one API endpoint for transferring an amount of money from an account type (regular or savings) to someone. We will redirected the user to a certain dialog state based on the transaction result.

app.post('/transaction', function (req, res) {
  let nextDialogstate; 
  const { amount, destination, accountType, transactionSuccess, transactionNoMoney = req.body; 

  // get account type (regular - savings account) 
  const account = account_synonyms[accountType];
 
  if( accounts[account].amount + accounts[accounthlimit — amount < ) {
    nextDialogstate = transactionNoMoney 
  } else { 
    // transfer amount 
    accounts[account].amount —= amount;
    nextDialogstate = transactionSuccess; 
  } 

  res.json({
    action: { 
      nextDialogstate,
    }, 
    session: {
      namespace: 'account', 
      data: {
        limit: accounts[account].limit, 
        amount: accounts[account].amount 
      }
    },
  })
});

We receive the body payload object as defined in the Chatlayer API step. If the user doesn’t have a sufficient amount of money on his account we set the next dialog state to ‘transactionNoMoney’. Else we subtract the desired amount and set the next dialog state to ‘transactionSuccess'.

As a response for the request we send the next dialogs state to redirect the user to that state and we save the amount of money and the limit of his account in his session data under the namespace account. This data can be used in that next dialog state.

As an alternative solution you could also send that chat message as a response of the API plugin requests by using the messages key.

variable: a variable. The value of the variable will be stored as value for the key. Dot and array notation are supported, for example: users[0].firstname

variable: a variable. The value of the variable will be stored as value for the key. Dot and array notation are supported, for example: users[0].firstname

In this example, representing a money transfer, we send five keys in the body payload of an HTTPS POST request to our API endpoint .

Configuration is where, if you have an API configuration in , you will see them here.

If , if the API response sends agent messages back to the user and the agent supports multiple languages, don’t forget to send the user language in the request. The user language is available in the variable locale. Your backend service can use this language setting to send back the response in the user's preferredLanguage.

messages: an array of messages to send back to the user interface channel. The structure of different message types (such as text, buttons, quick replies, carousels, lists, media,etc) is available in the .

user session
user session
https://chatlayer-integration-demo.glitch.me/transaction
Settings>API
your bot is multilingua
l
user session
chat message structure
Action
Action
canvas
Add an API Action step.
The Query tab inside your API step.
The Authorization tab inside your API step.
Basic auth Authorization.
Bearer token Authorization.
The Headers tab inside your API step.
The Body tab inside the API step.
Example of body payload.
The Configuration tab inside an API step.