Authentication

All RAVATAR API requests require JWT-based authentication. This page covers how to obtain, use, and refresh tokens, as well as the configuration endpoints you will call immediately after authenticating.

Obtaining JWT Token

Endpoint:

POST /jwt

Request Headers:

Content-Type: application/json

Request Body:

{
  "user_id": "unique-user-identifier",
  "project_id": "your-project-id"
}

Field	Type	Required	Description
user_id	string	Yes	Unique identifier for the user. Generate a UUID or similar unique string.
project_id	string	No	Project identifier provided during setup.

Field Validation:

Field	Constraints
user_id	1-128 characters, alphanumeric, hyphens, and underscores allowed
project_id	1-64 characters, alphanumeric and hyphens allowed

cURL Example:

curl -X POST https://chat.rvtr.ai/jwt \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-12345", "project_id": "proj-abc"}'

Response:

{
  "result": "success",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Field	Type	Description
result	string	"success" or "failure"
jwt	string	JWT token for authentication (valid for 24 hours)

Error Responses:

Status	Error	Description
400	invalid_user_id	Missing or malformed user_id
400	invalid_project_id	Malformed project_id format
401	project_not_found	Project ID does not exist
500	token_generation_failed	Internal server error

Using the Token

Include the JWT token in the Authorization header for all subsequent API requests:

Authorization: Bearer {jwt_token}

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Refresh

When the server responds with HTTP 403 Forbidden, the token has expired. To handle this:

1. Detect the 403 response
2. Call POST /jwt to obtain a new token
3. Retry the failed request with the new token

Recommended Implementation (pseudocode):

FUNCTION makeAuthenticatedRequest(url, options):
    response = HTTP_REQUEST(url, options)

    IF response.status == 403 THEN
        // Token expired - refresh and retry
        newToken = POST /jwt WITH original credentials
        options.headers.Authorization = "Bearer " + newToken
        response = HTTP_REQUEST(url, options)
    END IF

    RETURN response
END FUNCTION

---

Configuration APIs

After obtaining a JWT token, use these endpoints to retrieve avatars, languages, and chat history.

Get Chat Configuration

Retrieve available avatars, languages, and chat settings.

Endpoint:

GET /connection

Request Headers:

Authorization: Bearer {jwt_token}

cURL Example:

curl -X GET https://chat.rvtr.ai/connection \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response:

{
  "status": 200,
  "session": "session-identifier",
  "avatars_info": [
    {
      "_id": "avatar-id-123",
      "name": "Assistant",
      "greetingText": "Hello! How can I help you today?",
      "hasLiveMode": true,
      "previewIcons": {
        "small": "https://example.com/avatar-small.png",
        "medium": "https://example.com/avatar-medium.png",
        "large": "https://example.com/avatar-large.png"
      },
      "startButtonIcon": "https://example.com/start-icon.png",
      "idleVideo": "https://example.com/idle.mp4"
    }
  ],
  "languages": [
    {
      "name": "English",
      "language_code": "en",
      "icon_url": "https://example.com/flags/en.png"
    }
  ],
  "chat_types": ["text", "voice", "video"],
  "messageTimeoutSeconds": 30,
  "stopSpeakingTimeoutSeconds": 10,
  "vadEnabled": true,
  "voiceModeSelector": true
}

Field	Type	Description
status	number	HTTP status code
session	string	Session identifier for subsequent requests
avatars_info	array	Available avatars
languages	array	Supported languages
chat_types	array	Available chat types: text, voice, video
messageTimeoutSeconds	number	Message response timeout (default: 30)
vadEnabled	boolean	Voice Activity Detection enabled (see VAD)
voiceModeSelector	boolean	Show voice mode selector in UI

Get Chat History

Retrieve previous chat messages for a user.

Endpoint:

GET /chat

Query Parameters:

Parameter	Type	Required	Default	Description
user_id	string	Yes	-	User identifier
per_page	number	No	100	Messages per page
page	number	No	1	Page number

cURL Example:

curl -X GET "https://chat.rvtr.ai/chat?user_id=user-123&per_page=50&page=1" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Request Headers:

Authorization: Bearer {jwt_token}

Response:

{
  "payload": [
    {
      "_id": "message-id-123",
      "direction": "outgoing",
      "user_id": "user-123",
      "request": "Hello, how are you?",
      "avatar_id": "avatar-id-123",
      "date": 1737820800000,
      "chat_type": "text",
      "language_code": "en"
    },
    {
      "_id": "message-id-124",
      "direction": "incoming",
      "user_id": "user-123",
      "request": "Hello, how are you?",
      "answer": "I'm doing great! How can I assist you today?",
      "avatar_id": "avatar-id-123",
      "avatar_name": "Assistant",
      "date": 1737820801000,
      "chat_type": "text",
      "language_code": "en",
      "fileUrl": "https://example.com/response.mp4"
    }
  ],
  "has_more_messages": false
}

Field	Type	Description
payload	array	Array of chat messages
has_more_messages	boolean	More messages available for pagination

Message Object:

Field	Type	Description
_id	string	Unique message identifier
direction	string	"incoming" (from avatar) or "outgoing" (from user)
user_id	string	User identifier
request	string	User's message text
answer	string	Avatar's response text (incoming only)
avatar_id	string	Avatar identifier
avatar_name	string	Avatar display name (incoming only)
date	number	Unix timestamp in milliseconds
chat_type	string	"text", "voice", or "video"
language_code	string	Language code (e.g., "en")
fileUrl	string	URL to audio/video response file