SmallTalk API

Make your chatbot users laugh. With over 100 million chatbot-dedicated expressions created by tens of millions of people around the world and a conversation engine(AICR) that has supported the world's best chatbot for over 15 years, you'll have brilliant chatting skills in your chatbot. You can take advantage of most of the expressions in 'SimSimi', the best chatbot for small talk.

Concept

A ‘talkset’ consists of a pair of question-answer sentences(qtext-atext). SWS has more than 100 million talkset repository.

When a request is received through the SmallTalk API, SWS’s conversation engine(AICR) finds the relevant question sentences(qtext) in the talkset repository considering the similarities with a user’s request sentence(utext) and some other factors, creates a candidate talksets, and selects the most appropriate talkset filtering/weighing the parameters included in the request and other conditions.

The answer sentence provided by the SmallTalk API is the atext of the talkset selected through this process. If a requested utext is “Have you eaten lunch?”, the SmallTalk API returns an atext through the process like below.

Basic Request

You can receive a response by requesting to the SmallTalk API endpoint(https://wsapi.simsimi.com/{VERSION}/talk) with the appropriate method(POST), project key, and required parameters(utext, lang).

Example Request
Node.js Python PHP R Restlet Client C#
curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext": "hello", 
            "lang": "en" 
     }'                     

Sentence that a user entered in your chatbot(100 characters max.)

Language code (language-language code table)

Basic Response

The body of the basic response consists of status codes(status), status messages(statusMessage), request sentence(utext), and language codes(lang), as well as answer sentence(atext). Here is the corresponding response to the example request above. (The atext may differ each time you request because it takes into account various conditions.):

Example Response
{
    "status" : 200, 
    "statusMessage" : "OK", 
    "utext" : "hello",
    "lang" : "en",
    "atext" : "Hello it is a pleasure to meet you!"
}                           

Status code (status code list)

Status Message

Status Code and Status Messages

Code Description
200 OK : Normal
227 Parameter Required : You have not entered required parameters
228 Do Not Understand : There is no proper answer to the question you asked
403 Unauthorized : Invalid API Key
429 Limit Exceeded
500 Server error

Response Control

SmallTalk API provides options for controlling response. For example, if you want your bot to answer sentences(atext) with a Badword Probability of 70% or less among the talksets generated in the United States, you can request by adding the following two options.

Example Request
curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext":"hello",
            "lang": "en",
            "country" : ["US"],
            "atext_bad_prob_max": 0.7
     }'                     

Badword Probability

The Badword Probability is an index developed by the SimSimi team to identify how unhealthy/malicious a sentence is, and there are some distinguishing techniques for index calculation including advanced deep learning with superior performance. For more information, please see the blog post, Malcious Sentence Classification Techniques in the SimSimi Service (Korean).

Response Control Options

The options for controlling the response in the current version of the SmallTalk API are:

  • country
    • Specifies the countries of the talkset. You can specify this value when you are requesting SmallTalk API with a language that is used in multiple countries to filter the talksets created in the desired countries.
    • The format is an array of country codes (up to 10).
  • atext_bad_prob_max
    • Limits the maximum of Badword Probability in the answer sentence(atext).
    • Most of SWS's talksets have Badword Probabilities tagged in many ways. (See the system of distinguishment.)
    • Specifies one of the values from 0.0 to 1.0 with the first decimal place. Defaults to 1.0.
    • SimSimi application deployed on Google Play and the Apple App Store sets this value to a sufficiently small value for compliance with each platform content policy.
  • atext_bad_prob_min
    • Limits the minimum of Badword Probability in the answer sentence(atext).
    • The default value is 0.0. It must be equal to or less than the atext_bad_prob_max.
    • If you do not set both atext_bad_prob_max and atext_bad_prob_min, the default values are 1.0 and 0.0, so there is no restriction on malicious contents.
    • We recommend that you do not set this value greater than 0.0 for chatbots that are oriented towards a healthy conversation.
  • atext_length_min
    • Limits the minimum length of the answer sentence(atext). The atext length is from 1 to 256 characters. Defaults to <1.
  • atext_length_max
    • Limits the maximum length of the answer sentence(atext). Defaults to 256.
  • regist_date_max
    • Specifies the maximum date on which the talkset was created. The default format is yyyy-MM-dd HH:mm:ss
    • Example
    • "regist_date_max": "2019-01-01 00:00:00"
  • regist_date_min
    • Specifies the minimum date on which the talkset was created.

Request Additional Information

The SmallTalk API provides a way to get more detailed information about responses. Define cf_info in the request body for the additional information you want to receive.

Example Request
curl -X POST https://wsapi.simsimi.com/190410/talk \
     -H "Content-Type: application/json" \
     -H "x-api-key: PASTE_YOUR_PROJECT_KEY_HERE" \
     -d '{
            "utext":"hello",
            "lang": "en",
            "cf_info" : [
                  "qtext",
                  "country",
                  "atext_bad_prob",
                  "atext_bad_type",
                  "regist_date"
            ],
     }'                     
Example Response
{
    "status" : 200,
    "statusMessage" : "OK",
    "atext" : "Hello it is a pleasure to meet you!"
    "lang" : "en",
    "utext" : "hello",
    "qtext" : "hello~~",
    "country" : "US",
    "atext_bad_prob" : 0.0,
    "atext_bad_type" : "dpd",
    "regist_date" : "2017-07-08 08:24:37"
}                           

Additional Information Details

  • qtext
    • The question sentence(qtext) that is a pair of the answer sentence(atext) in the talkset.
  • country
    • ISO-3166-1 alpha-2 country code for the talkset. (See the country code.)
  • atext_bad_prob
    • The Badword Probability of the answer sentence(atext).
  • atext_bad_type
  • regist_date
    • The creation time of the talkset.

List of supported languages and language codes

Most language codes are the same as ISO-639-1, but note that there are other cases(*).

Language Name Name Language Code
Afrikaans Afrikaans af
Albanian Shqip al*
Arabic العربية ar
Armenian հայերեն hy
Azerbaijani Azərbaycanca az
Basque euskara eu
Belarusian беларуская be
Bengali বাংলা bn
Bosnian bosanski bs
Bulgarian български bg
Catalan català ca
Cebuano Cebuano cx*
Chinese 中文 ch*
Croatian hrvatski hr
Czech čeština cs
Danish Dansk da
Dutch Nederlands nl
English English en
Estonian eesti et
Filipino Filipino ph*
Finnish suomi fi
French Français fr
Frisian Frysk fy
Galician galego gl
Georgian ქართული ka
German Deutsch de
Greek Ελληνικά el
Gujarati ગુજરાતી gu
Hebrew עברית he
Hindi हिन्दी hi
Hungarian magyar hu
Icelandic íslenska is
Indonesian Bahasa Indonesia id
Italian Italiano it
Japanese 日本語 ja
Kannada ಕನ್ನಡ kn
Kazakh қазақ kk
Khmer ភាសាខ្មែរ kh*
Korean 한국어 ko
Kurdish (Kurmanji) Kurdî (Kurmancî) ku
Latvian latviešu lv
Lithuanian lietuvių lt
Macedonian македонски mk
Malay Melayu ms
Malayalam മലയാളം ml
Marathi मराठी mr
Mongolian Монгол mn
Myanmar (Burmese) မြန်မာဘာသာ my
Nepali नेपाली ne
Norwegian norsk nb
Assamese অসমীয়া as
Breton Brezhoneg br
Guaraní Guarani gn
Javanese Basa Jawa jv
Oriya ଓଡ଼ିଆ or
Kinyarwanda Ikinyarwanda rw
Chinese – Traditional 繁體中文 zh*
Pashto پښتو ps
Persian فارسی fa
Polish polski pl
Portuguese português pt
Punjabi ਪੰਜਾਬੀ pa
Romanian Română ro
Russian русский ru
Serbian српски rs*
Sinhala සිංහල si
Slovak slovenčina sk
Slovenian slovenščina sl
Spanish español es
Swahili Kiswahili sw
Swedish svenska sv
Tajik Тоҷикӣ tg
Tamil தமிழ் ta
Telugu తెలుగు te
Thai ภาษาไทย th
Turkish Türkçe tr
Ukrainian українська uk
Urdu Урду ur
Uzbek O‘zbek uz
Vietnamese Tiếng Việt vn*
Welsh Cymraeg cy