Object Definitions

This page shows the objects the SDK sends and receives through postMessage — the JSON you pass in, and the payloads that come back to your subscriber. Use it when you need a field’s exact name or shape. Two naming notes: institution in any payload is the API’s word for a Digital Twin, and course_id / course_name on a conversation are simply that conversation’s id and name (the field names are historical).

Post Request Object

const request = {
	command: 'message.post',
	inputs: [<string>],
	assistantId: <string>,
	selectedCourse: {
		course_id: <number>,
		course_name: <string>
	}
}

post is accepted as a legacy alias for message.post.

Post Response Object

{
   "type": "pria-response",
   "response": {
      "command": "message.post",
      "content": {
         "success": true,
         "outputs": [
            "I am doing great ! Happy birthday by the way, doing anything special?"
         ],
         "usage": 12048,
         "institutioncredits": 991,
         "credits": 991,
         "creditsUsed": 59,
         "totalLength": 12048,
         "totalCredits": 2,
         "query_duration_ms": 9404,
         "requestArgs": {
            "userISODate": "2024-12-23T14:25:48.245Z",
            "userTimezone": "Indian/Mauritius",
            "socketId": "kdzUm6yzkFd9YDcWAAAP",
            "assistantId": "67568474f66f51c8dc860c1f",
            "selectedCourse": {
               "course_id": 123456,
               "course_name": "Pre-assessment (AI for Analysts)"
            }
         },
         "model": "us.anthropic.claude-3-5-sonnet-20240620-v1:0"
      },
      "type": "object",
      "isError": false
   },
   "version": 1
}

Assistants List Request

const request = {
	command: 'assistants.list'
}

Assistants List Response Object

{
  "type": "pria-response",
  "response": {
    "content": [
      {
        "_id": "68c6f230d9c782aee842fc04",
        "name": " New Conversation",
        "description": "Start a new conversation! This assistant is designed to initiate and facilitate fresh, engaging dialogues on a wide range of topics, adapting to the user's interests and needs.✏️📝 It employs a dynamic approach, utilizing available tools and user memory to personalize interactions, while maintaining a focus on the current conversation's context and goals. The primary benefit of this assistant is its ability to provide tailored, informative, and thought-provoking exchanges that encourage learning, exploration, and meaningful interaction, all while adhering to strict guidelines for accuracy, citation, and ethical communication.",
        "picture_url": "/assistant_new_conversation.webp",
        "status": "active",
        "liked_count": 0,
        "admin_only": false,
        "institution_shared": false,
        "editable_others": false,
        "remember_history": 3,
        "created": "2025-09-14T16:49:52.983Z"
      },
      {
        "_id": "68c6f231d9c782aee842fc16",
        "name": "Code Analyzer",
        "description": "The Code Analyzer systematically examines your code through a comprehensive three-phase approach to identify critical bugs, security vulnerabilities, and performance bottlenecks before they impact your production systems, transforming potentially costly runtime failures into proactive development wins. 🔍 🛡️ Experience the confidence that comes from receiving severity-ranked findings with targeted code fixes and actionable remediation examples, allowing you to strengthen your codebase methodically while learning best practices that elevate your programming skills with every analysis session.",
        "picture_url": "/assistant_code_analyzer.png",
        "status": "active",
        "liked_count": 0,
        "admin_only": false,
        "institution_shared": false,
        "editable_others": false,
        "remember_history": 3,
        "created": "2025-09-14T16:49:53.079Z"
      },
     ...
    ],
    "command": "assistants.list",
    "type": "object",
    "isError": false
  },
  "version": 1
}

Conversations List Request

const request = {
	command: 'conversations.list'
}

Conversations List Response Object

{
  "type": "pria-response",
  "response": {
    "content": [
      {
        "course_name": " New Conversation Wednesday, Oct 1, 2025",
        "assistant": {
          "_id": "68c6f230d9c782aee842fc04",
          "name": " New Conversation",
          "picture_url": "/assistant_new_conversation.webp",
          "liked_count": 0
        },
        "history_count": 1,
        "last_dialogue_date": "2025-10-01T04:50:28.099Z",
        "course_id": 1759294218187
      },
      {
        "course_name": "",
        "assistant": null,
        "history_count": 1,
        "last_dialogue_date": "2025-09-25T07:46:05.719Z",
        "course_id": 0
      }
    ],
    "command": "conversations.list",
    "type": "object",
    "isError": false
  },
  "version": 1
}

Favorites List Request

const request = {
	command: 'favorites.list'
}

Favorites List Response Object

{
  "type": "pria-response",
  "response": {
    "content": [
      {
        "id": "68dcb3bfdaaf57e9576ea6b6",
        "created": "2025-10-01T04:53:19.729Z",
        "credits": 2,
        "usage": 11455,
        "cached": 0,
        "completion": 0,
        "latencyMs": 0,
        "institution": "68c6f230d9c782aee842fb12",
        "favorite": true,
        "forgotten": false,
        "course_id": 22345,
        "course_name": "Conversational Assist",
        "role_id": 123,
        "role_name": "Course ABC",
        "query_duration_ms": 47224,
        "conversation_model": "gpt-realtime",
        "success": true,
        "in": {
          "input": "Transcripts for conversation conv_CLj7EQXPBb6sAUTAotBRD"
        },
        "out": {
          "outputs": [
            "Hey there! Great to have you here – let’s dive right in! What’s on your mind today?"
          ]
        }
      }
    ],
    "command": "favorites.list",
    "type": "object",
    "isError": false
  },
  "version": 1
}

Convo Ready Event

The convo.ready event is sent proactively by the Digital Twin after the user logs in. It notifies the embedding application whether real-time voice (speech-to-speech) mode is authorized for the current user. This event is not a response to a command — it is sent automatically.

{
  "type": "pria-response",
  "response": {
    "command": "convo.ready",
    "content": {
      "authorized": true
    },
    "type": "object",
    "isError": false
  },
  "version": 1
}

Field	Type	Description
`content.authorized`	Boolean	`true` if real-time voice mode is available for this user, `false` otherwise
`content.reason`	String	Present only when something must happen first: `consent_required` means the user has not yet accepted the account’s privacy policy (the SDK opens the panel so they can)

Authorization depends on the Digital Twin’s real-time voice settings and whether the user has the required role. The event can arrive more than once — after sign-in, when the user’s permissions reload, and once the privacy policy is accepted — so act on the latest one.

This event is also intercepted by the SDK itself to set the pria.isConvoReady() flag and optionally trigger convoMode auto-start. Subscribers receive it after the SDK processes it.

Convo Live Event

The convo.live event is sent once per conversation, when that conversation can actually accept text through convo.post. It is not a response to a command. convo.ready and convo.live answer different questions: the first says the user is allowed to start a voice conversation, the second says a conversation is running and ready to be spoken into. A page that starts a conversation and immediately posts into it should wait for this one.

{
  "type": "pria-response",
  "response": {
    "command": "convo.live",
    "content": {
      "provider": "anam_pria_custom_llm"
    },
    "type": "object",
    "isError": false
  },
  "version": 1
}

Convo Ended Event

The convo.ended event is sent once when a voice conversation ends — the user hung up inside the panel, or the connection closed. It is not sent when the provider reconnects on its own, and it is not a response to a command.

{
  "type": "pria-response",
  "response": {
    "command": "convo.ended",
    "content": {
      "provider": "anam_pria_custom_llm"
    },
    "type": "object",
    "isError": false
  },
  "version": 1
}

Start Convo Request

const request = {
	command: 'convo.start',
	assistantId: '<assistant _id>',        // optional
	contextMode: 'fresh',                  // optional: 'fresh' | 'continue'
	intro: 'Welcome back to lesson three.' // optional: a string, or false to skip the greeting
}

Start Convo Response

{
  "type": "pria-response",
  "response": {
    "content": "Convo started (STS)",
    "command": "convo.start",
    "type": "string",
    "isError": false
  },
  "version": 1
}

Convo Post Request

Sends text into a conversation that is already running. role defaults to user (the learner speaking) and respond defaults to true.

const request = {
	command: 'convo.post',
	inputs: ['The learner just opened the Try It panel — coach them into it.'],
	role: 'system',
	respond: true
}

Convo Post Response

delivered confirms the twin accepted the text. replied says whether it answered — some providers cannot take context without answering, and ElevenLabs cannot answer a system message on demand, so the two are reported separately. On Anam and Cartesia twins, a role: "system" post with respond: true is acknowledged when the twin’s turn ends. replied is true when the twin produced a spoken reply, and false when the model produced nothing for that instruction; the final convo.transcript message for that turn then carries reason: "empty" and an empty text. A turn that fails also reports replied: false, with reason: "error" on its transcript.

{
  "type": "pria-response",
  "response": {
    "content": {
      "delivered": true,
      "role": "system",
      "respond": true,
      "provider": "anam_pria_custom_llm",
      "replied": true
    },
    "command": "convo.post",
    "type": "object",
    "isError": false
  },
  "version": 1
}

A refusal arrives as a pria-error with the reason in content — no conversation running (Convo is not started (STS)), the twin not allowing page instructions or the sender not being the embedding page (Access Unauthorized (401)), an empty or over-long message (Invalid Request (400)), or a provider that cannot honour the request.

Stop Convo Request

const request = {
	command: 'convo.stop'
}

Stop Convo Response

{
  "type": "pria-response",
  "response": {
    "content": "Convo stopped (STS)",
    "command": "convo.stop",
    "type": "string",
    "isError": false
  },
  "version": 1
}

Overview

Getting Started

LMS Integrations

Voice & Avatars

Web & Chat Integrations

MCP Server

JavaScript SDK

Authentication

REST API

Runtime API

Administrator API

Object Definitions

Post Request Object

Post Response Object

Assistants List Request

Assistants List Response Object

Conversations List Request

Conversations List Response Object

Favorites List Request

Favorites List Response Object

Convo Ready Event

Convo Live Event

Convo Ended Event

Start Convo Request

Start Convo Response

Convo Post Request

Convo Post Response

Stop Convo Request

Stop Convo Response

​Post Request Object

​Post Response Object

​Assistants List Request

​Assistants List Response Object

​Conversations List Request

​Conversations List Response Object

​Favorites List Request

​Favorites List Response Object

​Convo Ready Event

​Convo Live Event

​Convo Ended Event

​Start Convo Request

​Start Convo Response

​Convo Post Request

​Convo Post Response

​Stop Convo Request

​Stop Convo Response

Post Request Object

Post Response Object

Assistants List Request

Assistants List Response Object

Conversations List Request

Conversations List Response Object

Favorites List Request

Favorites List Response Object

Convo Ready Event

Convo Live Event

Convo Ended Event

Start Convo Request

Start Convo Response

Convo Post Request

Convo Post Response

Stop Convo Request

Stop Convo Response