NAV Navbar
json
  • Welcome
  • Conversation
  • Question and Answer
  • Intent Management
  • Greedy Search
  • Errors
  • Welcome

    Welcome, Humley orchestrate best of breed AI technology, together with their own AI IP to deliver natural, flexible machine to human unscripted conversations. Conversations that seamlessly can cover multiple topics, yet are individually tailored to the user: producing useful end user outcomes.

    The following documentation highlights our available APIs for both deployment and management.

    Conversation

    Open Conversation

    {
      "UserParameters": [
        {
          "Key": "First Name",
          "Value": "Samuel"
        },
        {
          "Key": "Position",
          "Value": "Product Manager"
        }
      ],
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36",
      "Language": "en",
      "DateTime": "2018-07-30T13:40:38.250Z"
    }
    

    The above command returns JSON structured like this:

    {
        "UUID": "10615634",
        "ConversationID": "261138",
        "ErrorFound": false,
        "ErrorCode": null
    }
    

    This endpoint should be used to start an initial conversation within the Humley platform.

    HTTP Request

    POST https://rest.humley.com/Conversation/2/openconversation

    Query Parameters

    Parameter Type Description
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UserParameters Object[] An array of objects which can be used to provide additional information relevant to the user or conversation. For example this could be used to pass in the user's first name captured from a login experience, this would be entered by stating "Key": "firstName" as the key and accompanying it with a key value as specified as the following "Value": "Samuel"
    UUID String This is a unique identifier for a user of the Humley platform.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.

    Talk

    
    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36",
      "Language": "en",
      "DateTime": "2018-07-30T13:40:38.250Z"
    }
    
    

    The above command returns JSON structured like this:

    
    {
        "UUID": "10615634",
        "ConversationID": "261154",
        "UserInput": "What is Octavo",
        "Responses": [
            {
                "IntentID": "22266",
                "Category": "",
                "Actions": {
                    "ActionURL": "",
                    "ActionType": "Browser",
                    "MessageTo": "",
                    "MessageText": "",
                    "AppID": "",
                    "AppInstalled": "",
                    "OSFunction": "",
                    "OSFunctionParameters": []
                },
                "Context": {
                    "StartDate": "27/06/2016 00:00:00",
                    "EndDate": "27/06/2116 23:59:59",
                    "StartTime": "",
                    "EndTime": "",
                    "WiFi": "",
                    "Roaming": "",
                    "ToTenure": "",
                    "FromTenure": ""
                },
                "Video": {
                    "VideoTitle": "2",
                    "VideoURL": "pt5SFCFdQR4",
                    "VideoHeader": "Humley's Octavo",
                    "VideoButton": "9"
                },
                "Popup": {
                    "Body": null,
                    "Background": null,
                    "Button": null
                },
                "ResponseMetadata": {
                    "ResponseType": "5",
                    "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology.  These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
                    "Confidence": "100",
                    "ResponseID": "22266",
                    "LogID": 879974,
                    "ButtonID": null,
                    "Buttons": [
                        {
                            "ButtonText": "Okay",
                            "ActionType": "link",
                            "ActionURI": "https://www.youtube.com/watch?v=pt5SFCFdQR4",
                            "ActionText": ""
                        }
                    ],
                    "Triage": "False",
                    "Closedown": "False",
                    "Extras": []
                }
            }
        ],
        "LoggedIn": "true",
        "ErrorFound": false,
        "ErrorCode": ""
    }
    
    

    This endpoint allows you to ask have a conversation using the Humley platform.

    HTTP Request

    POST https://rest.humley.com/Conversation/2/talk

    Query Parameters

    Parameter Type Description
    User Input
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This is a unique identifier for a user of the Humley platform. If this has not already been created for an individual user, this should be set by the response and should be passed back in once the Humley system has generated a UUID based on the IMEI which has been provided in the open conversation response.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.
    ConversationID Int The conversationID of the current conversation, each conversation is given an unique identifier which can be used to provide conversation context. This should be gathered from the open conversation call upon initial start of a conversation. The conversationID from the previous talk response should always be provided in the talk request if available.

    Talk Verbose

    
    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36",
      "Language": "en",
      "DateTime": "2018-07-30T13:40:38.250Z"
    }
    
    

    The above command returns JSON structured like this:

    
    {
        "UUID": "10611703",
        "ConversationID": "276173",
        "ConversationData": {
            "InputKeywords": {
                "StandardKeywords": []
            },
            "InputEntities": {
                "StandardEntities": [
                    "iasi",
                    "Octavo"
                ]
            },
            "ResponseKeywords": {
                "PlatformKeywords": [
                    "dictionary",
                    "graph database technology",
                    "machine",
                    "natural language processing",
                    "platform",
                    "relationships",
                    "sophisticated artificial intelligence",
                    "specific body",
                    "techniques",
                    "terms"
                ]
            },
            "ResponseEntities": {
                "StandardEntities": []
            }
        },
        "UserInput": "what is octavo?",
        "UserInputData": {
            "Keywords": {
                "StandardKeywords": []
            },
            "Entities": {
                "StandardEntities": [
                    "iasi",
                    "Octavo"
                ]
            },
            "LanguageDetected": "en"
        },
        "Responses": [
            {
                "IntentID": "139141",
                "Category": "",
                "Actions": {
                    "ActionURL": "",
                    "ActionType": "Browser",
                    "MessageTo": "",
                    "MessageText": "",
                    "AppID": "",
                    "AppInstalled": "",
                    "OSFunction": "",
                    "OSFunctionParameters": []
                },
                "Context": {
                    "StartDate": "25/07/2018 00:00:00",
                    "EndDate": "25/07/2118 23:59:59",
                    "StartTime": "",
                    "EndTime": "",
                    "WiFi": "",
                    "Roaming": "",
                    "ToTenure": "",
                    "FromTenure": ""
                },
                "Video": {
                    "VideoTitle": null,
                    "VideoURL": null,
                    "VideoHeader": null,
                    "VideoButton": null
                },
                "Popup": {
                    "Body": null,
                    "Background": null,
                    "Button": null
                },
                "ResponseMetadata": {
                    "ResponseType": "5",
                    "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology.  These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
                    "Confidence": "100",
                    "ResponseID": "139141",
                    "LogID": 905097,
                    "ButtonID": null,
                    "Buttons": [],
                    "Triage": "False",
                    "Closedown": "False",
                    "Extras": [],
                    "ResponseKeywords": {
                        "PlatformKeywords": [
                            "dictionary",
                            "graph database technology",
                            "machine",
                            "natural language processing",
                            "platform",
                            "relationships",
                            "sophisticated artificial intelligence",
                            "specific body",
                            "techniques",
                            "terms"
                        ]
                    },
                    "ResponseEntities": {
                        "StandardEntities": []
                    }
                },
                "Integrations": {
                    "IntegrationID": 0,
                    "IntegrationStatusCode": 0,
                    "IntegrationResponseData": null
                },
                "Exchange": {
                    "exchangeID": 0,
                    "exchangeElementID": 0,
                    "exchangeItem": null,
                    "exchangeItemStage": 0,
                    "exchangeCaptureLog": null
                }
            },
            {
                "IntentID": "",
                "Category": "",
                "Actions": {
                    "ActionURL": "",
                    "ActionType": "",
                    "MessageTo": "",
                    "MessageText": "",
                    "AppID": "",
                    "AppInstalled": "",
                    "OSFunction": "",
                    "OSFunctionParameters": []
                },
                "Context": {
                    "StartDate": "",
                    "EndDate": "",
                    "StartTime": "",
                    "EndTime": "",
                    "WiFi": "",
                    "Roaming": "",
                    "ToTenure": "",
                    "FromTenure": ""
                },
                "Video": {
                    "VideoTitle": null,
                    "VideoURL": null,
                    "VideoHeader": null,
                    "VideoButton": null
                },
                "Popup": {
                    "Body": null,
                    "Background": null,
                    "Button": null
                },
                "ResponseMetadata": {
                    "ResponseType": "3",
                    "ResponseBody": "Has this helped you with your query?",
                    "Confidence": null,
                    "ResponseID": null,
                    "LogID": 0,
                    "ButtonID": "-1",
                    "Buttons": [
                        {
                            "ButtonText": "Yes",
                            "ActionType": "publishText",
                            "ActionURI": "",
                            "ActionText": "Yes"
                        },
                        {
                            "ButtonText": "Sort Of",
                            "ActionType": "publishText",
                            "ActionURI": "",
                            "ActionText": "Sort Of"
                        },
                        {
                            "ButtonText": "No",
                            "ActionType": "publishText",
                            "ActionURI": "",
                            "ActionText": "No"
                        }
                    ],
                    "Triage": "False",
                    "Closedown": "False",
                    "Extras": null,
                    "ResponseKeywords": {
                        "PlatformKeywords": null
                    },
                    "ResponseEntities": {
                        "StandardEntities": []
                    }
                },
                "Integrations": {
                    "IntegrationID": 0,
                    "IntegrationStatusCode": 0,
                    "IntegrationResponseData": null
                },
                "Exchange": {
                    "exchangeID": 0,
                    "exchangeElementID": 0,
                    "exchangeItem": null,
                    "exchangeItemStage": 0,
                    "exchangeCaptureLog": null
                }
            }
        ],
        "LoggedIn": "true",
        "ErrorFound": false,
        "ErrorCode": ""
    }
    
    

    This endpoint allows you to ask have a conversation using the Humley platform.

    HTTP Request

    POST https://rest.humley.com/Conversation/2/talkverbose

    Query Parameters

    Parameter Type Description
    User Input
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This is a unique identifier for a user of the Humley platform. If this has not already been created for an individual user, this should be set by the response and should be passed back in once the Humley system has generated a UUID based on the IMEI which has been provided in the open conversation response.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.
    ConversationID Int The conversationID of the current conversation, each conversation is given an unique identifier which can be used to provide conversation context. This should be gathered from the open conversation call upon initial start of a conversation. The conversationID from the previous talk response should always be provided in the talk request if available.

    Release Notes

    Version 2.0.0

    Initial version using Humley Studio.

    Known issues include:

    1. Unable to filter by version number settings passed into the API. Introduced version 1.0.0
    2. Unable to filter intents by time settings passed into the API. Introduced version 1.0.0
    3. Entities populated within ConversationData.ResponseKeywords.PlatformKeywords have intermittent issues with population. Introduced version 1.1.0
    4. Entities populated within Responses.ResponseEntities.StandardEntities have intermittent issues with population. Introduced version 1.1.0
    5. Integrations from exchanges are not being populated in Integrations data. Introduced version 1.1.0

    Question and Answer

    Ask Question

    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UUID": "12345678"
    }
    

    The above command returns JSON structured like this:

    {
      "UUID": "1234567891",
      "UserInput": "What is Octavo?",
      "Responses": [
        {
          "IntentID": "22266",
          "Category": null,
          "Actions": {
            "ActionURL": "",
            "ActionType": "Browser",
            "MessageTo": "",
            "MessageText": "",
            "AppID": "",
            "AppInstalled": "",
            "OSFunction": "",
            "OSFunctionParameters": []
          },
          "Context": {
            "StartDate": "27/06/2016 00:00:00",
            "EndDate": "27/06/2116 23:59:59",
            "StartTime": "",
            "EndTime": "",
            "WiFi": "",
            "Roaming": "",
            "ToTenure": "",
            "FromTenure": ""
          },
          "Video": {
            "VideoTitle": "2",
            "VideoURL": "pt5SFCFdQR4",
            "VideoHeader": "Humley's Octavo",
            "VideoButton": "9"
          },
          "Popup": {
            "Body": null,
            "Background": null,
            "Button": null
          },
          "ResponseMetadata": {
            "ResponseType": "5",
            "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology.  These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
            "Confidence": "100",
            "ResponseID": "22266",
            "LogID": 876083,
            "ButtonID": null,
            "Buttons": [
              {
                "ButtonText": "Okay",
                "ActionType": "link",
                "ActionURI": "https://www.youtube.com/watch?v=pt5SFCFdQR4",
                "ActionText": ""
              }
            ],
            "Triage": "False",
            "Closedown": "False",
            "Extras": []
          }
        }
      ],
      "ErrorFound": false,
      "ErrorCode": ""
    }
    
    

    This endpoint allows you to query the question and answer API and return a set of intents in relation to a user input.

    HTTP Request

    POST https://rest.humley.com/QandA/2/AskQuestion

    Query Parameters

    Parameter Type Description
    UserInput
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This should be set by the response and should be passed back in once the Humley system has generated a UUID for that user.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.

    Ask Question Verbose

    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UUID": "12345678"
    }
    

    The above command returns JSON structured like this:

    {
        "UUID": "10620519",
        "UserInput": "What is octavo",
        "UserInputData": {
            "Keywords": {
                "StandardKeywords": []
            },
            "Entities": {
                "StandardEntities": []
            },
            "LanguageDetected": "en"
        },
        "Responses": [
            {
                "IntentID": "139141",
                "Category": null,
                "Actions": {
                    "ActionURL": "",
                    "ActionType": "Browser",
                    "MessageTo": "",
                    "MessageText": "",
                    "AppID": "",
                    "AppInstalled": "",
                    "OSFunction": "",
                    "OSFunctionParameters": []
                },
                "Context": {
                    "StartDate": "25/07/2018 00:00:00",
                    "EndDate": "25/07/2118 23:59:59",
                    "StartTime": "",
                    "EndTime": "",
                    "WiFi": "",
                    "Roaming": "",
                    "ToTenure": "",
                    "FromTenure": ""
                },
                "Video": {
                    "VideoTitle": null,
                    "VideoURL": null,
                    "VideoHeader": null,
                    "VideoButton": null
                },
                "Popup": {
                    "Body": null,
                    "Background": null,
                    "Button": null
                },
                "ResponseMetadata": {
                    "ResponseType": "5",
                    "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology.  These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
                    "Confidence": "100",
                    "ResponseID": "139141",
                    "LogID": 905160,
                    "ButtonID": null,
                    "Buttons": [],
                    "Triage": "False",
                    "Closedown": "False",
                    "Extras": [],
                    "ResponseKeywords": {
                        "PlatformKeywords": [
                            "dictionary",
                            "graph database technology",
                            "machine",
                            "natural language processing",
                            "platform",
                            "relationships",
                            "sophisticated artificial intelligence",
                            "specific body",
                            "techniques",
                            "terms"
                        ]
                    }
                }
            }
        ],
        "ErrorFound": false,
        "ErrorCode": ""
    }
    
    

    This endpoint allows you to query the question and answer API and return a set of intents in relation to a user input.

    HTTP Request

    POST https://rest.humley.com/QandA/2/AskQuestionVerbose

    Query Parameters

    Parameter Type Description
    UserInput
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This should be set by the response and should be passed back in once the Humley system has generated a UUID for that user.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.

    Ask Question with Articles

    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UUID": "12345678",
      "ArticleCount": 100,
      "SegmentCount": 100,
      "RankingSetCount": 1000
    }
    

    The above command returns JSON structured like this:

    {
        "UUID": "12345",
        "UserInput": "Octavo",
        "Responses": [
            {
                "ArticleName": "Octavo 101",
                "Segments": [
                    {
                        "IntentID": "254395",
                        "Category": null,
                        "Actions": {
                            "ActionURL": "",
                            "ActionType": "Browser",
                            "MessageTo": "",
                            "MessageText": "",
                            "AppID": "",
                            "AppInstalled": "",
                            "OSFunction": "",
                            "OSFunctionParameters": []
                        },
                        "Context": {
                            "StartDate": "07/08/2018 15:15:24",
                            "EndDate": "07/08/2118 15:15:24",
                            "StartTime": "",
                            "EndTime": "",
                            "WiFi": "",
                            "Roaming": "",
                            "ToTenure": "",
                            "FromTenure": ""
                        },
                        "Video": {
                            "VideoTitle": null,
                            "VideoURL": null,
                            "VideoHeader": null,
                            "VideoButton": null
                        },
                        "Popup": {
                            "Body": null,
                            "Background": null,
                            "Button": null
                        },
                        "ResponseMetadata": {
                            "ResponseType": "5",
                            "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology. These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
                            "Confidence": "14.57529700673267400",
                            "ResponseID": "254395",
                            "LogID": 894338,
                            "ButtonID": null,
                            "Buttons": [],
                            "Triage": "False",
                            "Closedown": "False",
                            "Extras": []
                        },
                        "Keywords": null
                    }
            {
                "ArticleName": "The Octavo Handbook",
                "Segments": [
                    {
                        "IntentID": "95303",
                        "Category": null,
                        "Actions": {
                            "ActionURL": "",
                            "ActionType": "Browser",
                            "MessageTo": "",
                            "MessageText": "",
                            "AppID": "",
                            "AppInstalled": "",
                            "OSFunction": "",
                            "OSFunctionParameters": []
                        },
                        "Context": {
                            "StartDate": "01/01/2018 00:00:00",
                            "EndDate": "11/11/2222 23:59:59",
                            "StartTime": "",
                            "EndTime": "",
                            "WiFi": "",
                            "Roaming": "",
                            "ToTenure": "",
                            "FromTenure": ""
                        },
                        "Video": {
                            "VideoTitle": null,
                            "VideoURL": null,
                            "VideoHeader": null,
                            "VideoButton": null
                        },
                        "Popup": {
                            "Body": null,
                            "Background": null,
                            "Button": null
                        },
                        "ResponseMetadata": {
                            "ResponseType": "5",
                            "ResponseBody": "Octavo uses statistical techniques such as Vector Space Models to create a basic model of the language used in a knowledge-base. Using this model, various artificial intelligence techniques can be used to classify semantic relationships, parse sentence structures, and dynamically generate language.",
                            "Confidence": "10.8627696315075600",
                            "ResponseID": "95303",
                            "LogID": 894338,
                            "ButtonID": null,
                            "Buttons": [],
                            "Triage": "False",
                            "Closedown": "False",
                            "Extras": []
                        },
                        "Keywords": null
                    }
                ]
            }
        ],
        "ErrorFound": false,
        "ErrorCode": ""
    }
    

    This endpoint allows you to query the question and answer API and return a set of intents in relation to a user input.

    HTTP Request

    POST https://rest.humley.com/QandA/2/AskArrayQuestionVerbose

    Query Parameters

    Parameter Type Description
    UserInput
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This should be set by the response and should be passed back in once the Humley system has generated a UUID for that user.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.
    ArticleCount Int The total number of articles which should be returned from a given request. If unset this will default to 10.
    SegmentCount Int The total number of segments which should be returned within each article (if available within ranking set). Segments are usually ingested as intents, therefore this is the total number of intents which should be provided underneath each article grouping. If unset this will default to 10.
    RankingSetCount Int The total number of segments which should be taken into account within the ranking. It's recommended that this is set to a minimum of 1000. If unset this will default to 1000.

    Ask Question with Articles Verbose

    {
      "UserInput": "What is Octavo?",
      "ProjectID": 141,
      "IMEI": "1234567890174",
      "UUID": "12345678",
      "ArticleCount": 100,
      "SegmentCount": 100,
      "RankingSetCount": 1000
    }
    

    The above command returns JSON structured like this:

    {
        "UUID": "10623987",
        "UserInput": "What is Octavo?",
        "UserInputData": {
            "Keywords": {
                "StandardKeywords": ["Octavo"]
            },
            "Entities": {
                "StandardEntities": ["Octavo"]
            },
            "LanguageDetected": "en"
        },
        "Responses": [
            {
                "ArticleName": "Octavo 101",
                "Segments": [
                    {
                        "IntentID": "448883",
                        "Category": null,
                        "Actions": {
                            "ActionURL": "",
                            "ActionType": "Browser",
                            "MessageTo": "",
                            "MessageText": "",
                            "AppID": "",
                            "AppInstalled": "",
                            "OSFunction": "",
                            "OSFunctionParameters": []
                        },
                        "Context": {
                            "StartDate": "15/08/2018 13:42:59",
                            "EndDate": "15/08/2118 13:42:59",
                            "StartTime": "",
                            "EndTime": "",
                            "WiFi": "",
                            "Roaming": "",
                            "ToTenure": "",
                            "FromTenure": ""
                        },
                        "Video": {
                            "VideoTitle": null,
                            "VideoURL": null,
                            "VideoHeader": null,
                            "VideoButton": null
                        },
                        "Popup": {
                            "Body": null,
                            "Background": null,
                            "Button": null
                        },
                        "ResponseMetadata": {
                            "ResponseType": "2",
                           "ResponseBody": "Octavo is an machine learning platform that uses sophisticated artificial intelligence, natural language processing techniques, and graph database technology. These allow Octavo to learn and store a dictionary of terms and their relationships to each other. This provides an intelligent, efficient and scalable approach to a specific body of data.",
                            "Confidence": "94.57529700673267400",
                            "Confidence": null,
                            "ResponseID": "448883",
                            "LogID": 909033,
                            "ButtonID": null,
                            "Buttons": [],
                            "Triage": "False",
                            "Closedown": "False",
                            "Extras": [ ],
                            "ResponseKeywords": {
                                "PlatformKeywords": [
                                    "Octavo",
                                    "Machine Learning",
                                    "Natural Language",
                                    "Intelligent"
                                ]
                            }
                        }
                    }
                ]
            }
    
        ],
        "ErrorFound": false,
        "ErrorCode": ""
    }
    

    This endpoint allows you to query the question and answer API and return a set of intents in relation to a user input.

    HTTP Request

    POST https://rest.humley.com/QandA/2/AskArrayQuestion

    Query Parameters

    Parameter Type Description
    UserInput
    Mandatory
    String The query that you would like surfaced intents againsts, for example "What do Humley do?", "How do I top up my mobile?", "How much does it cost for flights to Rome?"
    ProjectID
    Mandatory
    Int The id of the project which holds the intents you wish to query against.
    UUID String This should be set by the response and should be passed back in once the Humley system has generated a UUID for that user.
    ClientVersion Int The version of the client being used within your experience. This can be used to filter responses based on the version of client (front-end) a user may be using.
    IMEI String International Mobile Equipment Identity and is a unique number given to every single mobile phone. This should be used as a unique identifier for a particular user. This could be both the actual IMEI if using mobile or alternatively a GUID to keep a consistent user within the platform.
    UserAgent String The user agent of the device being used within the experience.
    Language String The language of the user, this would usually be detected by the device being used and then passed into the request.
    DateTime DateTime The current date and time of the client.
    ArticleCount Int The total number of articles which should be returned from a given request. If unset this will default to 10.
    SegmentCount Int The total number of segments which should be returned within each article (if available within ranking set). Segments are usually ingested as intents, therefore this is the total number of intents which should be provided underneath each article grouping. If unset this will default to 10.
    RankingSetCount Int The total number of segments which should be taken into account within the ranking. It's recommended that this is set to a minimum of 1000. If unset this will default to 1000.

    Release Notes

    Version 2.0

    Initial version of the question and answer API with Basic Authentication using Humley Studio.

    Known issues include:

    1. Unable to filter by version number settings passed into the API.
    2. Unable to filter intents by time settings passed into the API.

    Intent Management

    Import Intent

    {
      "ProjectID": 0,
      "Intent": [
        {
          "IntentID": 0,
          "FolderName": "string",
          "SubFolderName": "string",
          "Category": "string",
          "Active": true,
          "TrainingData": {
            "UserInput": "string",
            "AlternativeUserInput": [
              "string"
            ],
            "Response": "string",
            "Keywords": [
              "string"
            ]
          },
          "Context": {
            "StartDate": "2019-08-29T09:21:50.317Z",
            "EndDate": "2019-08-29T09:21:50.317Z",
            "StartTime": "string",
            "EndTime": "string",
            "Days": {
              "Monday": true,
              "Tuesday": true,
              "Wednesday": true,
              "Thursday": true,
              "Friday": true,
              "Saturday": true,
              "Sunday": true
            }
          },
          "Video": {
            "URL": "string",
            "VideoLicense": true
          },
          "Metadata": [
            {
              "Key": "string",
              "Value": "string"
            }
          ],
          "MessageNotes": "string",
          "DocumentID": "string"
        }
      ]
    }
    

    The above command returns JSON structured like this:

    {
        "ResponseCode": "00",
        "Errors": null
    }
    

    This endpoint allows you to import an intent to the Humley platform.

    HTTP Request

    POST https://rest.humley.com/ImportExport/2/importData

    Query Parameters

    Parameter Type Description
    ProjectID
    Mandatory
    Int The id of the project which the intents should be imported to.
    IntentID Int If set it will update existing intents, if left empty will create a new intent.
    FolderName
    Mandatory
    String The name of the folder. If the folder already exists it will add the intents to the existing folder, if it doesn't exist it will create a new folder.
    SubFolderName
    Mandatory
    String The name of the sub folder. If the sub folder exists within the parent folder it will update the existing intents, if it doesn't exist it will create a new folder of that name.
    Category
    Mandatory
    String The name of the category. If the category exists it will assign the existing category, if the category doesn't exist it will create a new category.
    UserInput
    Mandatory
    String The main user input for the intent.
    Response
    Mandatory
    String The response of the section. There is no limit on the length of this field.
    Status String The status of the intent. This can be set to Live, Stage or Draft. This will default to Live if not set.
    Active Boolean Whether or not the intent should be set to active or deactivate. This can either be true or false. This will default to true if not set.
    AlternativeUserInput String[] List of alternative user inputs.
    Keywords String[] List of keywords.
    ActionType String The type of action you wish to apply to an intent. This can either be Open In Browser, OS Function, Open App,Send SMS
    URL String The URL of the open in browser action if specified.
    ActionButtonText String The button text which should be associated to an action. This can be configured from a pre-defined set of buttons. If ActionType is set, this is required.
    AppInstalled String Whether or not an action should be shown based on a particular application being installed on the device. This should be set as Yes, No or Ignore. If not set, this will default to Ignore.
    OSFunction String If OS function is defined within ActionType, this will be used to specify the type of OS function which should be associated to the action. If OS Function (intent) is set to true then this is mandatory. This can be configured from a pre-defined list of OS functions.
    SMSTo String The number which should be associated to the SMS action, this will be shown as the recipient number on Android devices. If SendSMS is set as the action type then this field is mandatory.
    SMSText String The text of the SMS message which should be sent. If SendSMS is set as the action type then this field is mandatory.
    StartDate DateTime The date that the intent should be available from. If not set this will be defaulted to today's date. Example 2018-07-1314:58:T49.454Z
    EndDate DateTime The date that the intent should no longer be available. If not set, this will be defaulted to 100 years from todays date. Example 2018-07-1314:58:T49.454Z
    StartTime DateTime The time of day this intent is able to be surface from. If not set this it will be available at all times. If either StartTime or EndTime is set both fields become mandatory.
    EndTime DateTime The time of day this intent is able to be surface until. If not set this it will be available at all times. If either StartTime or EndTime is set both fields become mandatory.
    TenureStart Int Whether an intent should be shown based on a users particular tenure. TenureStart must be less than TenureEnd.
    TenureEnd Int Whether an intent should be shown based on a users particular tenure. TenureEnd must be greater than TenureStart.
    URL String The URL of the video. Currently, this only supports YouTube videos.
    Title String The title of the video. If a URL is configured then this field is mandatory.
    Metadata Object[] An array of objects which configures additional data to be sent down with the intent. This should be configured as "Key": "string", "Value": "string". The amount of intent extras configured against a single intent is unlimited.
    AB Array of Ints An array of ints defines which A/B test groups the intent belongs to. If left blank, all users will be able to surface the intent.
    Monday Boolean Whether the intent should be accessible on Mondays. Defaults to true.
    Tuesday Boolean Whether the intent should be accessible on Tuesdays. Defaults to true.
    Wednesday Boolean Whether the intent should be accessible on Wednesdays. Defaults to true.
    Thursday Boolean Whether the intent should be accessible on Thursdays. Defaults to true.
    Friday Boolean Whether the intent should be accessible on Fridays. Defaults to true.
    Saturday Boolean Whether the intent should be accessible on Saturdays. Defaults to true.
    Sunday Boolean Whether the intent should be accessible on Sundays. Defaults to true.
    DocumentLocation String URL or file path of content related to the content.
    MessageNotes String Additional information about the intent for internal use.
    DocumentID String The source location of the intent contents.

    Export Intent

    The above command returns JSON structured like this:

    {
      "RequestID": 0
    }
    

    This endpoint allows you to import an intent to the Humley platform, you can order

    HTTP Request

    POST https://rest.humley.com/ImportExport/2/exportData/<project-id>

    Query Parameters

    Parameter Type Description
    ProjectID
    Mandatory
    Int The id of the project which the intents should be imported to.

    Release Notes

    Version 2.0

    Initial Version of the export API with Basic Authentication.

    Known issues include:

    1. Tenure start and end cannot be set from the Import API, this includes both setting editing existing and creating new.
    2. Dates start and end cannot be set from the Import API, currently dates will be taken from their parent folder and sub folder settings.
    3. Unable to set document location from the Import API
    4. Unable to set message notes from the Import API
    5. Active is always set to True from the API and cannot be changed within the request.

    Greedy Search

    Authentication

    In order to access both the conversation endpoints, you will need to authenticate using your credentials provided by Humley. Authentication to the API is performed via HTTP Basic Auth and be sure to keep them secure! Do not share your username or password in publicly accessible areas such as GitHub, client-side code, and so forth.

    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

    {
        "UserInput" : "what are causes of neurodevelopmental disorders?",
        "projectId" : 141,
        "count" : 1
    }
    

    The above command returns JSON structured like this:

    {
        "userInput": "what are causes of neurodevelopmental disorders?",
        "responses": [
            {
                "documentId": "2106025",
                "title": "The medicinal plants of Myanmar",
                "url": "http://www.ncbi.nlm.nih.gov/pmc/articles/PMC6033956",
                "confidence": 0.98009670428462237
            }
        ]
    }
    

    HTTP Request

    POST https://rest.humley.com/GreedySearch/1/search

    Query Parameters

    Parameter Type Description
    userRequest
    Mandatory
    String The user input that should be used within the query.
    projectId
    Mandatory
    Int The projectId that you wish to query.
    count
    Mandatory
    Int The number of results that should be returned from a request.

    Release Notes

    Version 1.0.1

    Pre-release version of Greedy Search

    Version 2.0

    Added expanded queries which feature the various different variants asked to the third party system. Added Concepts within Responses[], this provides preferred names and synonyms. Added keywords that have been found within the user input.

    Known issues include:

    1. Status mapping discrepancies.
    2. Count parameter not showing as mandatory.
    3. Response times between 20 - 90 seconds.

    Errors

    The Humley platform uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your username and password cannot be authorised.
    403 Forbidden -- The client does not have access rights to the content.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- The server can not find requested resource.
    406 Not Acceptable -- You requested a format that isn't json.
    410 Gone -- The requested content has been permanently deleted from server.
    418 I'm a teapot.
    429 Too Many Requests -- You have made too many requests! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.