Metadata is a set of key-value pairs of custom metadata that is sent back to your endpoints with webhooks and function calls.

Unlike variables, it’s not visible to LLM, so it’s impossible to rewrite the metadata directly through the conversation.

The common use case for metadata is providing the current user ID to identify the user when a function is called or a webhook is received.

For better security, it is recommended to encode the user ID with a secret key so it is impossible to simulate the conversation on behalf of a specific user knowing their user ID.

Metadata could be passed to the following endpoints:

rest/v1/ai-chats/current

rest/v1/assistants/{assistantId}/chat/completions

rest/v1/call/web

rest/v1/call/phone

Metadata could be passed to the CompanionWidget initialization:

CompanionWidget.initializeAssistant(
  // the first argument is variables
  {
      userName: "Bob",
      memoryNotes: "Additional information about the user",
  },
  // the second argument is metadata
  {
    userId: $currentUserId
  }
);

Also, metadata could be passed to the voice-call SDK:

voiceCall.start({
  companionId: string;            // Required
  userId: string;                 // Optional
  variables: Record<string, any>; // Optional
  metadata: Record<string, any>; // Optional
});