Skip to main content
View as Markdown

Keep Alive - Agentic Avatars SDK

Keep Alive​

Keep the current session alive.

Endpoint​

POST /v1/avatar-session/:sessionId/keep-alive

Authentication​

Header: Authorization: Bearer {token}

Path Parameters​

ParameterTypeRequiredDescription
sessionIdstringYesSession ID from create-session

Request Body​

Empty body ({}).

Response​

Success (200)​

{
  "success": true
}

Error Responses​

  • 400 - Bad request
  • 401 - Unauthorized
  • 404 - Not found
  • 410 - Gone (session ended)
  • 500 - Server error

Examples​

cURL​

curl -X POST https://api.avatar.us.kaltura.ai/v1/avatar-session/session-123/keep-alive \
  -H "Authorization: Bearer $TOKEN"

JavaScript (fetch)​

await fetch(`https://api.avatar.us.kaltura.ai/v1/avatar-session/${sessionId}/keep-alive`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Usage Notes​

When to Call​

Send keep-alive requests every 10 seconds to prevent session timeout.

Automatic Keep-Alive​

If using the Client SDK's createSession() method, keep-alive is sent automatically.

Manual Keep-Alive​

If you're not using the Client SDK, implement manual keep-alive:

// Start keep-alive interval
const keepAliveInterval = setInterval(async () => {
  try {
    await fetch(
      `https://api.avatar.us.kaltura.ai/v1/avatar-session/${sessionId}/keep-alive`,
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }
    );
    console.log('Keep-alive sent');
  } catch (error) {
    console.error('Keep-alive failed:', error);
    clearInterval(keepAliveInterval);
  }
}, 10000); // Every 10 seconds

// Stop when session ends
function cleanup() {
  clearInterval(keepAliveInterval);
}

Complete Example​

class SessionManager {
  constructor(sessionId, token, baseUrl) {
    this.sessionId = sessionId;
    this.token = token;
    this.baseUrl = baseUrl;
    this.keepAliveInterval = null;
  }

  startKeepAlive() {
    this.keepAliveInterval = setInterval(async () => {
      try {
        const response = await fetch(
          `${this.baseUrl}/${this.sessionId}/keep-alive`,
          {
            method: 'POST',
            headers: {
              Authorization: `Bearer ${this.token}`,
            },
          }
        );

        if (!response.ok) {
          throw new Error('Keep-alive failed');
        }

        console.log('Keep-alive: session active');
      } catch (error) {
        console.error('Keep-alive error:', error);
        this.stopKeepAlive();
      }
    }, 10000);
  }

  stopKeepAlive() {
    if (this.keepAliveInterval) {
      clearInterval(this.keepAliveInterval);
      this.keepAliveInterval = null;
    }
  }
}

// Usage
const manager = new SessionManager(sessionId, token, baseUrl);
manager.startKeepAlive();

// Stop when done
manager.stopKeepAlive();

Next Steps​