Remote method calls

Overview

With RPC your application can define methods on one participant that can be invoked remotely by other participants within a room, and may return a response. This feature can be used to request data, coordinate application-specific state, and more. When used to forward function calls from an AI Agent, your LLM can directly access data or manipulate UI in your application's frontend.

Method registration

First register the method at the destination participant with localParticipant.registerRpcMethod and provide the method's name and a handler function. Any number of methods can be registered on a single participant.

localParticipant.registerRpcMethod(
  'greet',
  async (data: RpcInvocationData) => {
    console.log(`Received greeting from ${data.callerIdentity}: ${data.payload}`);
    return `Hello, ${data.callerIdentity}!`;
  }
);

Method invocation

Use localParticipant.performRpc to invoke the registered RPC method on a remote participant by providing the destination participant's identity, the method name, and the payload. This is an asynchronous operation that returns a string, and may raise an error.

try {
  const response = await localParticipant.performRpc({
    destinationIdentity: 'recipient-identity',
    method: 'greet',
    payload: 'Hello from RPC!',
  });
  console.log('RPC response:', response);
} catch (error) {
  console.error('RPC call failed:', error);
}

Method names

Method names can be any string, up to 64 bytes long (UTF-8).

Payload format

RPC requests and responses both support a string payload, with a maximum size of 15KiB (UTF-8). You may use any format that makes sense, such as JSON or base64-encoded data.

Response timeout

performRpc uses a timeout to hang up automatically if the response takes too long. The default timeout is 10 seconds, but you are free to change it as needed in your performRpc call. In general, you should set a timeout that is as short as possible while still satisfying your use case.

The timeout you set is used for the entire duration of the request, including network latency. This means the timeout the handler is provided will be shorter than the overall timeout.

Errors

performRpc will return certain built-in errors (detailed below), or your own custom errors generated in your remote method handler.

To return a custom error to the caller, handlers should throw an error of the type RpcError with the following properties:

• code: A number that indicates the type of error. Codes 1001-1999 are reserved for LiveKit internal errors.
• message: A string that provides a readable description of the error.
• data: An optional string that provides even more context about the error, with the same format and limitations as request/response payloads.

Any other error thrown in a handler will be caught and the caller will receive a generic 1500 Application Error.

Built-in error types