NAV
shell javascript

Introduction

Build your customer service solution your way with our Public APIs.

Whether you want to build a chat bot for your own website, integrate our solution into different systems to support your agents, or use our named entity recognition to extract pieces of information from any text data, our REST API gives you access our services, so you can build the solution that suits your needs.

To get started, request your Access Token from here.

Chat Automation

This endpoint can be used to automate chat conversations. It accepts a visitor message and responds with a bot reply and attached actions. A response could be a simple text reply or a dialog which includes multiple messages.

In the current API version, the only action supported is the forwardToHuman parameter, that flags whether the conversation should be escalated to a human agent. The agent owning the conversation should then be changed from bot to a human agent / human department.

HTTP Request

Method: POST

Endpoint /api/v2/automation

Authentication

curl 'https://chat.ultimate.ai/api/v2/automation' \
  -H 'Authorization: Basic {basicAuthToken}'
fetch(
    'https://chat.ultimate.ai/api/v2/automation', 
    {
        headers: {
            'Authorization': 'Basic {basicAuthToken}'
        },
    }
);

This endpoint is protected by Basic Access Athentication.

If you are a client already, you can create your basic access token by generating a Base64 encoded string using your email and password joined by a colon: jane.doe@email.com:janesPassword

If you are not a client yet, you can request access to try out the API from here.

Once you have your Basic Auth Token, you can authorize to the API by setting a header named Authorization containing your token in the form of Basic {basicAuthToken}.

Request

Send your request as a JSON with MIME-type of application/json.

Example Request:

{
   "botId":"1a2b3c4d5e6f7g8h9i0j1k2l",
   "conversationId":"12345678987654321",
   "eventType":"message",
   "text":"Hello! My email is jane.doe@email.com",
   "metaData":[
      {
         "key":"name",
         "value":"Jane Doe"
      }
   ]
}
Field Type Required Description
botId string true ID of the bot that will sends the reply.
You can find the ID of your bot in our dashboard, or talk to your Customer Success Manger.
conversationId string true An ID used by the chat provider to identify the conversation.
The chat provider can decide the format.
text string true
if eventType is message
The text message that the visitor typed into the chat.
The text is optional if the eventType is startSession or endSession.
If a button was pressed, send the value of the button as text (unless it’s a link button).
eventType enum [startSession, message, endSession] true Use startSession when the conversation is created. The welcomeMessage will be given as a response in case there is one for the given bot.
Use message if sending a visitor message.
Use endSession to end the session. Otherwise the Session will end automatically after 2 hours.
metaData array[MetaData] false Sending metaData gives you the ability to send metadata on the user or the session of the conversation. These params will be saved on the session and can be used by the bot to personalize the conversation flows.

Each object of type MetaData in the array needs to contain the following fields:
key string - name the session parameter can be referenced by to personalize a conversation
value string - value of the session parameter, note that we only support values of type string at this moment
sanitize bool - optional field, should be set as true for PII data

Response

Example Response:

{
    "messages": [
        {
            "text": "Hello Jane Doe, How can i help you today?",
            "buttons": []
        },
        {
            "text": "Type your question or select one of the options below:",
            "buttons": [
                {
                    "text": "Support"
                },
                {
                    "text": "Payments"
                },
                {
                    "text": "External link",
                    "link": "https://ultimate.ai"
                }
            ]
        }
    ],
    "confidenceThreshold": 0.7,
    "predictedIntents": [
        {
            "value": "5ee3593d2e4a8a47573252e8",
            "confidence": 0.7038699984550476,
            "name": "Intent Name 1 "
        },
        {
            "value": "5f68bc4f140e681cbe8ad6ce",
            "confidence": 0.14397311210632324,
            "name": "Intent Name 2 "
        },
        {
            "value": "5eaaa247d377f1001d2628ad",
            "confidence": 0.03942745178937912,
            "name": "Intent Name 3"
        },
        {
            "value": "5fcdf52b618b6b0015da984f",
            "confidence": 0.03256703168153763,
            "name": "Intent Name 4"
        },
        {
            "value": "5d84f76a957e151f61ed5f17",
            "confidence": 0.010709668509662151,
            "name": "Intent Name 5"
        }
    ],
    "entities": [
        {
            "name": "email",
            "value": "jane.doe@email.com"
        }
    ]
}

The endpoint will respond with a JSON with the following format:

Field Type Description
messages array[Message] Array containing one or several messages to show to the visitor.

Each object of type Message contains the following fields:
text string - Message string
forwardToHuman bool - When true this conversation needs to be forwarded to a human agent.
buttons array[Button] - Array of buttons to display to the visitor.

Each object of type Button contains the following fields:
text string - value of the button, that is shown to the visitor. When the visitor presses the button, send the text as a message to the chat.
link string nullable - URL to go to, when the button is pressed. If the button has a link, don't send its value to the chat when pressed.
confidenceThreshold float Float value between 0 and 1 - this is the bot's confidence threshold to answer to a visitor message. If there is no intent predicted (see predictedIntens) above this threshold, the bolt will return the default reply.
predictedIntents array[Intent] Array containing intents that were predicted for the text sent in the request.

Each object of type Intent contains the following fields:
value string - Unique ID identifying this intent.
name string - the intent's name
confidence float - Float value between 0 and 1 - giving the confidence with which this intent was predicted for the given text.
entities array [Entity] Array of entities that were extracted from the visitor message given in the request.

Each object of type Entity will have the following fields:
name string - Name of the recognized entity
value string - the value that was extracted from the visitor message

Usage

Start a conversation

curl 'https://chat.ultimate.ai/api/v2/automation' \
  -H 'Authorization: Basic {basicAuthToken}'
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '{"botId":"{botId}","conversationId":"{conversationId}","eventType":"startSession"}' \
  --compressed
const startConversation = fetch(
        'https://chat.ultimate.ai/api/v2/automation',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic {basicAuthToken}'
            },
            body: JSON.stringify({
                botId: '{botId}',
                conversationId: '{conversationId}',
                eventType: 'startSession'
            })
        }
    );

startConversation()
    .then(res => {
        console.log(res);
    });

To start a new conversation (ie: when the chat widget is opened) create a new conversationId of type string. This ID needs to be unique to identify the conversation, but the format of it is up to you. All subsequent visitor messages sent in the conversation, should use the same conversationId as the one used to start the conversation.

Send a POST request with your conversationId, your botId and the eventType: startSession to start the conversation session.

The API will respond with a welcome message if there is a welcome message defined for the given bot. Otherwise the messages array in the response will be empty.

Once you have started a conversation session, you can start sending visitor messages to the conversation. The session will end after 2 hours or when you send the eventType: endSession to the conversation.

Send a visitor message

curl 'https://chat.ultimate.ai/api/v2/automation' \
  -H 'Authorization: Basic {basicAuthToken}'
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '{"botId":"{botId}","conversationId":"${conversationId}","eventType":"message" "text": "Hello! My email is jane.doe@email.com"}, metaData: [{"key": "name", "value": "Jane Doe"}]' \
  --compressed
const sendMessage = fetch(
        'https://chat.ultimate.ai/api/v2/automation',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic {basicAuthToken}'
            },
            body: JSON.stringify({
                botId: '{botId}',
                conversationId: '{conversationId}',
                eventType:'message',
                text: 'Hello! My email is jane.doe@email.com',
                metaData:[
                  {
                    key:'name',
                    value:'Jane Doe'
                  }
               ]
            })
        }
    );

sendMessage()
    .then(res => {
        console.log(res);
    });

Once you have started a conversation session, you can start sending visitor messages with the same conversationId used when starting the conversation.

Use the eventType: message to send a visitor message receive an automated reply.

The response will contain an array with the bot messages for the highest predicted intent as well as a list of predicted intents for the given visitor message.

Bot messages will contain the text of the reply and might also contain an array of buttons and the flag forwardToHuman when conversations should be escalated to a human agent.

When a user presses one of the given buttons, send the value of the button as a message in the conversation to continue the dialogue. If the button has a link, the visitor should be redirected to the link address, the dialogue will not continue in this case.

In case you are escalating the conversation to a human agent, use our Suggestion Engine to support your agents by suggesting replies and sending the agent's messages to the conversation session.

End a conversation

curl 'https://chat.ultimate.ai/api/v2/automation' \
  -H 'Authorization: Basic {basicAuthToken}'
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '{"botId":"{botId}","conversationId":"{conversationId}","eventType":"endSession"}' \
  --compressed
const endConversation = fetch(
        'https://chat.ultimate.ai/api/v2/automation',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic {basicAuthToken}'
            },
            body: JSON.stringify({
                botId: '{botId}',
                conversationId: '{conversationId}',
                eventType: 'endSession'
            })
        }
    );

endConversation()
    .then(res => {
        console.log(res);
    });

To end new conversation (ie: when the visitor closes the chat widget, leaves the page, or any other event that should end the conversation session) send a request with the eventType: endSession.

If the conversation does not end with the endSession event, it will automatically end after 2 hours.

Intent Recognition

Send a visitor message from a chat or any type of text to get a list of matching intents with their confidences as well as a list of entities we extracted from the text. Use this endpoint to classify or label any piece of text.

HTTP Request

Method: POST

Endpoint: /api/intents

Authorization

curl 'https://chat.ultimate.ai/api/intents' \
  -H 'authorization: {accessToken}'
fetch(
    'https://chat.ultimate.ai/api/intents', 
    {
        headers: {
            'authorization': '{accessToken}'
        },
    }
);

To use our Intent Recognition API a header named authorization needs to be set.

You can find your access token in the dashboard in your bots settings under "Tokens".

If you are not a client yet, you request your Access Token to try out the API from here.

Request

Send your request as a JSON with MIME-type of application/json.

Example Request:

{
   "botId":"1a2b3c4d5e6f7g8h9i0j1k2l",
   "message":"this is a message", 
   "conversationId":"12345678987654321"
}
Field Type Required Description
botId string true ID of the bot that will sends the reply.
You can find the ID of your bot in our dashboard, or talk to your Customer Success Manger.
message string true The text message that the visitor typed into the chat.
conversationId string false An ID used by the chat provider to identify the conversation.
The chat provider can decide the format.

Response

Example Response:

{
    "intents": [
        {
            "confidence": 0.64636783599853516,
            "name": "intent A"
        },
        {
            "confidence": 0.54660784006118774,
            "name": "intent B"
        },
        {
            "confidence": 0.34867138862609863,
            "name": "intent C"
        },
        {
            "confidence": 0.1374831646680832,
            "name": "intent D"
        },
        {
            "confidence": 0.1208697184920311,
            "name": "intent E"
        }
    ],
    "entities": [
        {
            "confidence": 0.7,
            "form": "name.surname@mail.com",
            "index": 0,
            "name": "email",
            "id": "610abae77bf221077b4fc51e",
            "sanitize": true
        }
    ]
}

The endpoint will respond with a JSON with the following format:

Field Type Description
intents array[Intent] Array containing intents that were predicted for the message sent in the request.

Each object of type Intent contains the following fields:
name string - the intent's name
confidence float - Float value between 0 and 1 - giving the confidence with which this intent was predicted for the given message.
entities array [Entity] Array of entities that were recognized from the visitor message given in the request.

Each object of type Entity will have the following fields:
name string - Name of the recognized entity
confidence float - Float value between 0 and 1 - giving the confidence with which this entity was recognized for the given message.
form string - Form of the entity recognized in the given message.
index number - TODO Index of the entity recognized.
id number - Identifier of the entity recognized.
sanitize boolean - Boolean marking if entity is sanitized.

Usage

curl 'https://chat.ultimate.ai/api/intents' \
  -H 'Authorization: Basic {basicAuthToken}' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '{"botId":"{botId}","conversationId":"{conversationId}","message":"{message}"}' \
  --compressed
const getIntents = fetch(
        'https://chat.ultimate.ai/api/intents',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic {basicAuthToken}'
            },
            body: JSON.stringify({
                botId: '{botId}',
                message: '{message}',
                conversationId: '{conversationId}'
            })
        }
    );

getIntents()
    .then(res => {
        console.log(res);
    });