Talk

This is the main API call you must make to continue a conversation with Socrates. You will need to supply the conversation token supplied by the conversation/start API call.

Once the conversation has started, you must also supply the answer to the previous question prompted by Socrates.

Note. If the answer you have provided does not meet the specified format, the conversation will be repeated with error information appended to the message.

URL https://www.socratesinsights.com/api/conversation/talk

HTTP Method(s) POST

Example Requests

Your first request for a conversation, or a request from a previous conversation that does not require an answer…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
    <token>XYZ123456</token>
</conversation>

A request for a conversation, including a reply to a previous conversation that requires a single answer…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
    <token>XYZ123456</token>
    <reply>
        <answer>I am an iPhone</answer>
    </reply>
</conversation>

A request for a conversation, including a reply to a previous conversation that requires multiple answers…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
    <token>XYZ123456</token>
    <reply>
        <answer>iPhone</answer>
        <answer>Android</answer>
        <answer>Blackberry</answer>
    </reply>
</conversation>

Parameters

token required. Supplied during conversation/start and relevant to the survey you are about to take.

reply > answer optional. The format of your reply and answer(s) is specified by the conversational responses below…

Example Response (valid request)

Conversation that does not require an answer…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>Thanks for participating in our survey, let's begin!</text>
    </question>
    <answer>
        <prompt>Continue...</prompt>
        <required>NO</required>
    </answer>
</conversation>

Conversation that requires an answer of type TEXT…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>What is your name?</text>
    </question>
    <answer>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>TEXT</type>
    </answer>
</conversation>

Conversation that requires an answer of type NUMBER…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>How much was the last cup of coffee you purchased?</text>
    </question>
    <answer>
        <participant>Jereme</participant>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>NUMBER</type>
    </answer>
</conversation>

Conversation that requires an answer of type CURRENCY…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>How much was the last cup of coffee you purchased?</text>
    </question>
    <answer>
        <participant>Jereme</participant>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>CURRENCY</type>
    </answer>
</conversation>

Conversation that requires you to SELECT ONE answer from a list of options…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>Would you like to continue this conversation?</text>
    </question>
    <answer>
        <participant>Jereme</participant>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>SELECT-ONE</type>
        <select>
            <option>Yes</option>
            <option>No</option>
        </select>
    </answer>
</conversation>

Conversation that requires you to SELECT ONE or MULTIPLE answers from a list of options…

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>What are the colors of your local football team?</text>
    </question>
    <answer>
        <participant>Jereme</participant>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>SELECT-MULTIPLE</type>
        <select>
            <option>Black</option>
            <option>White</option>
            <option>Blue</option>
            <option>Red</option>
            <option>Yellow</option>
            <option>Green</option>
            <option>Orange</option>
        </select>
    </answer>
</conversation>

Example Response (invalid request)

<?xml version="1.0" encoding="UTF-8"?>
<conversation>
<token>XYZ123456</token>
    <question>
        <participant>Socrates</participant>
        <text>Would you like to continue this conversation?</text>
    </question>
    <answer>
        <participant>Jereme</participant>
        <prompt>Continue...</prompt>
        <required>YES</required>
        <type>SELECT-ONE</type>
        <select>
            <option>Yes</option>
            <option>No</option>
        </select>
    </answer>
    <error>
        <message>We asked for YES or NO, but you supplied MAYBE</message>
    </error>
</conversation>

Parameters

token Supplied during conversation/start and relevant to the survey you are about to take.

question This will contain information about the question that Socrates is asking.

question > participant The name of the questioner, the default being Socrates.

question > text The actual question text.

answer This will contain information about the answer that Socrates requires.

answer > participant The name of the respondent, usually asked in the early questions of a conversation.

answer > prompt The text that should be displayed on a prompt to take you through the questions.

answer > required YES | NO. Determines whether or not an answer is required to continue the conversation.

answer > type TEXT | NUMBER | CURRENCY | SELECT-ONE | SELECT-MULTIPLE. Determines what type of answer must be provided.

answer > select When the type is SELECT-ONE or SELECT-MULTIPLE, the available options will listed.

answer > select > option The text that should be displayed as an option to select and the data to be supplied in your reply.

error > message This will appear should you supply an incorrect answer or the token is not recognized.

Talk

Example Requests

Example Response (valid request)

Example Response (invalid request)

Interactive Text Box

Socrates API

Aristotle API

Latest Updates