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"
        }
    ],
  "languages": [
        {
            "value": "eng",
            "confidence": 0.90
        },
        {
            "value": "deu",
            "confidence": 0.000709668509662151
        }
  ]
}

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
languages	array [`Entity`]	Array of languages detected from the visitor message given in the request. Each object of type `DetectedLanguage` will have the following fields: value `string` - ISO code of the detected language confidence `string` - condifidence percentage from 100% on a scale from 0 ->1

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);
    });

Delete User Data

Delete a user's conversation and message data based on conversationIds.

HTTP Request

Method: POST

Endpoint: /api/gdpr/delete-user-data

Authorization

curl 'https://chat.ultimate.ai/api/gdpr/delete-user-data' \
  -H 'authorization: {basicAuthToken}'

fetch(
    'https://chat.ultimate.ai/api/gdpr/delete-user-data', 
    {
        headers: {
            'authorization': '{basicAuthToken}'
        },
    }
);

To use the delete user data API endpoint, a header named authorization needs to be set.

Request

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

Example Request:

{
   "conversationIds":["12345678987654321","567456789876543255" ]
}

Field	Type	Required	Description
conversationIds	array	true	An array of IDs used to fetch the user's messages and conversations to be deleted

Response

Example Response: The endpoint will respond with a status code depending on the deletion process results:

Status Code	Type	Description
200	Success	deletion process was successfully completed.
400	Bad Request Error	request data passed was not valid.
401	Auth Error	user does not have the right permissions, auth token is invalid or expired.
500	Internal Server Error	an unknown server error occurred.

Usage

curl 'https://chat.ultimate.ai/api/gdpr/delete-user-data' \
  -H 'Authorization: Basic {basicAuthToken}' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-raw '"conversationIds":"[{conversationId}]"' \
  --compressed

const deleteUserData = fetch(
        'https://chat.ultimate.ai/api/gdpr/delete-user-data',
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic {basicAuthToken}'
            },
            body: JSON.stringify({
                conversationId: '[{conversationId}, {conversationId}]'
            })
        }
    );

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