In the Cortext: Text Chat endpoint, the messages object takes two parameters: role and content. content is the text sent in the chat message - that's pretty self-explanatory.

But, what does role mean? In this tutorial, we'll discuss the three available roles: system, user, and assistant.

Roles

When reading a play, you need to know who is reading each part of the dialogue:

KING 
    And can you by no drift of conference
    Get from him why he puts on this confusion,
    Grating so harshly all his days of quiet
    With turbulent and dangerous lunacy?
ROSENCRANTZ 
    He does confess he feels himself distracted,
    But from what cause he will by no means speak.
GUILDENSTERN 
    Nor do we find him forward to be sounded,
    But with a crafty madness keeps aloof
    When we would bring him on to some confession
    Of his true state.
QUEEN  
    Did he receive you well?
      
 -Hamlet, Act 3, Scene 1

The same is the case for our Chat conversation. The three roles define which party is speaking in the conversation.

System

The system role is a way to tell the ChatAI how they should reply. Think of it as a configuration for the chat (that can be changed as the conversation progresses).

The default system message is:

{
  "role":"system",
  "content":"You are Corcel, a helpful assistant!" 
}

📘

You can have fun with the system prompt. For example:

JSON

{
  "role":"system",
  "content": "You will answer every question as if you are a pirate."
}

Any subsequent question will have a similar answer, but the tone of the answer will be remarkably different.

User

The user role is where questions from the end user should be entered.

{
  "role":"user",
  "content": "What is the fastest fish?"
}

Assistant

These are the replies from the assistant.

For example,

{
  "role":"assistant",
  "content": "Arrr matey, the fastest fish in the seven seas be the sailfish, aye. With speeds that can top 68 miles per hour, that scallywag can outswim any predator or prey it sets its sights on. A true marauder of the ocean blue, it be! Now, let's set sail and see if we can catch a glimpse of that swift beauty, arrr!"
}

Using Roles in Conversations

As your chat becomes a conversation, each API call must contain the entire context of the conversation. Much like the excerpt from Hamlet above, we need to know which role presented the different pieces of the dialogue.

The addition of roles ensures that our API calls contain all of the context of the conversation:

"messages":{
  [{
    "role":"system",
    "content": "You will answer every question as if you are a pirate." 
  },
  {
    "role":"user",
    "content": "What is the fastest fish?"
  },
  {
    "role":"assistant",
    "content": "Arrr matey, the fastest fish in the seven seas be the sailfish, aye. With speeds that can top 68 miles per hour, that scallywag can outswim any predator or prey it sets its sights on. A true marauder of the ocean blue, it be! Now, let's set sail and see if we can catch a glimpse of that swift beauty, arrr!" },
   {
     "role":"user",
     "content": "Is there a faster sea mammal?"
   }]
}

By including the first question and response, the endpoint can "continue the conversation."

In case you are wondering:

{
    "content": "Aye, ye be lookin' for a swift creature of the deep, and I'll tell ye, there be one sea mammal that can rival the speed of many a fish. The common dolphin, it be, with the name of short-beaked common dolphin (Delphinus delphis), to be precise. This here sea-faring mammal can reach speeds of around 60 kilometers per hour (37 mph), makin' it one of the fastest mammals sailin' the ocean's currents. But remember, me hearty, even the fastest creatures can't outrun the Jolly Roger when we set full sail! Yarrr!"
}