using livekit-server-sdk JS, how do I pass metadata alongside the token request

Thanks for reaching out, Guillaume. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

this is how I’m setting the metadata

export async function POST(req: Request) {
  try {
    if (LIVEKIT_URL === undefined) {
      throw new Error('LIVEKIT_URL is not defined');
    }
    if (API_KEY === undefined) {
      throw new Error('LIVEKIT_API_KEY is not defined');
    }
    if (API_SECRET === undefined) {
      throw new Error('LIVEKIT_API_SECRET is not defined');
    }

    // Parse agent configuration from request body
    const body = await req.json();
    const student: Student = body?.student;

    // Generate participant token
    const participantName = 'user';
    const participantIdentity = `voice_assistant_user_${Math.floor(Math.random() * 10_000)}`;
    const roomName = `voice_assistant_room_${Math.floor(Math.random() * 10_000)}`;

    const participantToken = await createParticipantToken(
      { identity: participantIdentity, name: participantName, metadata: JSON.stringify(student) },
      roomName,
    );

    // Return connection details
    const data: ConnectionDetails = {
      serverUrl: LIVEKIT_URL,
      roomName,
      participantToken: participantToken,
      participantName,
    };
    const headers = new Headers({
      'Cache-Control': 'no-store',
    });
    return NextResponse.json(data, { headers });
  } catch (error) {
    if (error instanceof Error) {
      console.error(error);
      return new NextResponse(error.message, { status: 500 });
    }
  }
}

function createParticipantToken(
  userInfo: AccessTokenOptions,
  roomName: string,
): Promise<string> {
  const at = new AccessToken(API_KEY, API_SECRET, {
    ...userInfo,
    ttl: '15m',
  });
  const grant: VideoGrant = {
    room: roomName,
    roomJoin: true,
    canPublish: true,
    canPublishData: true,
    canSubscribe: true,
  };
  at.addGrant(grant);

  return at.toJwt();

despite that, I’m still getting an empty metadata field when receiving the request on the agent side

Let's walk through some helpful steps to figure out why the metadata field might be coming up empty when using `createParticipantToken`: 1. Make Sure Metadata is Properly Passed: Double-check that the

metadata

field is clearly included in the

AccessTokenOptions

object. Here's a quick example:

const participantToken = await createParticipantToken(
  {
    identity: "user-identity",
    name: "User Name",
    metadata: JSON.stringify(student),
  },
  roomName,
);

1. Validate the Token Contents: Try decoding the JWT token you generated to see if the

metadata

field is actually there. You can use online JWT decoders or libraries like

jose

to peek inside the token. 2. Check How You Access Metadata on the Client Side: Make sure you're retrieving the metadata correctly. For instance:

console.log(room.localParticipant.metadata);

Or you can listen for updates like this:

room.localParticipant.on('metadataUpdated', () => {
  console.log(room.localParticipant.metadata);
});

1. Verify Your API Credentials: It's important to confirm that

LIVEKIT_API_KEY

and

LIVEKIT_API_SECRET

are set correctly and passed properly to the

AccessToken

constructor. 2. Watch Out for Overwritten Metadata: Check that the metadata isn’t accidentally being overwritten with an empty string or undefined during token creation. 3. Consider Optional Permissions: If you want to update metadata after joining, remember to include

canUpdateOwnMetadata: true

in the

VideoGrant

. If you’re still running into trouble, take a close look at the generated token to see whether the issue might be with how the token is created or how it’s handled on the client side. I’m here to help if you need more guidance! Sources: src/pages/api/token.ts | src/room/Room.ts | packages/livekit-server-sdk/src/AccessToken.ts | app/api/connection-details/route.ts | Authentication | LiveKit Docs

I decoded the token and it does contain the metadata. I don’t understand why the metadata is empty on the agent side

Thanks for sharing that the metadata is present in the token! To help us get to the bottom of why the agent might be seeing it as empty, could you please share a bit more about how the agent is accessing or processing the metadata? For example: • Are you using a specific method or API to retrieve the metadata on the agent side? • Is the agent set up to handle metadata, and have you noticed any logs or errors that might give us a clue? Understanding these details will really help us figure out what’s going on and find the best way to assist you.

export default defineAgent({
    prewarm: async (proc: JobProcess) => {
      proc.userData.vad = await silero.VAD.load();
    },
    entry: async (ctx: JobContext) => {
      const vad = ctx.proc.userData.vad! as silero.VAD;
      
      const metadata = ctx.job.metadata ? JSON.parse(ctx.job.metadata) : {};
      console.log("metadata", metadata);

This is how I access the metadata on the agent side

It looks like you’re accessing the metadata in the agent the right way! That’s a great start. Let’s go over a few additional things together to make sure everything’s set up correctly: 1. Make Sure Metadata is Properly Passed During Dispatch: When you dispatch the agent, the metadata needs to be explicitly included. Here’s an example to guide you:

lk dispatch create \
--agent-name test-agent \
--room my-room \
--metadata '{"user_id": "12345"}'

1. Check the Metadata in the Job Context: The

ctx.job.metadata

field should have the metadata string. If it’s coming up empty, it’s worth double-checking that the metadata was indeed sent during dispatch. 2. Look Out for JSON Parsing Issues: The metadata string needs to be valid JSON. If there’s a formatting problem,

JSON.parse

will throw an error, so it’s good to verify this. 3. Use Logs to Inspect Metadata: Adding some logging can help confirm what’s inside

ctx.job.metadata

before parsing. For example:

console.log("Raw metadata:", ctx.job.metadata);

If you still find the metadata empty after these checks, it might be related to how the agent is dispatched or how the metadata is passed along. Please feel free to reach out if you’d like me to help you troubleshoot further—I’m here to support you! Sources: Job lifecycle | LiveKit Docs | Agent dispatch | LiveKit Docs | External data and RAG | LiveKit Docs | Making calls using SIP | LiveKit Docs | Dispatching agents | LiveKit Docs

how do I access the metadata I set in the localparticipant token in the agent code?

I don't have the answer you're looking for. You could also try asking your question: • in one of the other Slack channels or • to https://deepwiki.com/livekit/livekit_composite which is trained on all LiveKit source code If you find the answer, please post it here to help others!