RPC

Overview

A participant can remotely execute a custom method on another participant and await a response. This is useful when a response or delivery confirmation is necessary for your application. AI Agent applications can use RPC to forward LLM function calls to the UI, fetch data that's available only within the frontend environment (e.g. geolocation), and more.

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}!`;
  }
);

Performing RPC

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