Working with the API

The examples below use the client configured in Getting started. All network calls return promises. Use try/catch around calls to handle validation and request failures.

Chats

await emby.createChat({
  id: 'support-42',
  title: 'Support',
  type: 'group',
  owner: { id: 'u-1', name: 'Alice' },
  metadata: { department: 'support' },
});

const { chat } = await emby.getChatInfo('support-42');
await emby.updateChat('support-42', { title: 'Customer support' });

Always provide an owner with an ID when creating a chat, even though the convenience input type makes it optional. For private chats, supply the other participant when creating the chat.

Create and update calls do not return the chat body by default. Use a separate read or request a representation through the generated API:

const result = await emby.api.chatCreate({
  header: { Prefer: 'return=representation' },
  body: {
    chat: {
      id: 'support-43',
      title: 'Support',
      type: 'group',
      owner: { id: 'u-1', name: 'Alice' },
    },
  },
});
console.log(result.chat);

To delete a chat, call await emby.deleteChat('support-42'). Deletion is accepted before the background cleanup finishes.

Messages

const sent = await emby.sendMessage(
  'support-42',
  { id: 'u-1', name: 'Alice' },
  [],
  'Hello from our server',
);
console.log(sent.message_ids);

const messages = await emby.getMessagesFromChat(
  'support-42',
  { with_users: true },
  1,
  100,
);
for (const id of messages.messages_sort) {
  console.log(id, messages.messages[id].text);
}

For getMessagesFromChat, the page and limit are the third and fourth arguments. Both default to 1; values inside the query object are ignored by this convenience method.

The sender needs both id and name. The participants array is used only if sending the message creates the chat. To create a chat this way, pass a chat object with create: true instead of just its ID.

await emby.updateMessage('support-42', 'm-1', { text: 'Updated text' });
await emby.deleteMessage('support-42', 'm-1');
await emby.sendTyping('support-42', 'u-1', 5);

Deleting a message marks it deleted and clears its text. sendTyping accepts a duration from 1 to 60 whole seconds. For attachments, see Voice messages.

Generated methods

Every REST operation has a method under emby.api. Its input separates path parameters, query parameters, body and headers:

const result = await emby.api.chatList({
  query: { limit: 20, page: 1, with_owner: '1' },
  timeout: 5_000,
});

await emby.api.chatSendMessage({
  path: { chat_id: 'support-42' },
  body: {
    user: { id: 'u-1', name: 'Alice' },
    messages: [{ text: 'Hello', disable_notification: true }],
  },
});

Generated methods cover settings, webhooks, Firebase and resources as well as chat and user operations. Use them when a convenience method does not expose an endpoint option, such as with_owner or a chat type of supergroup or channel.

Request inputs are checked with Zod before the request is sent. Responses are typed but are not runtime-validated. See the REST API reference for wire formats and endpoint constraints, and TypeScript for extracting SDK input and response types.

Raw requests

requestApi() is the underlying transport. Prefer a generated method when one exists, because raw requests do not validate inputs and default to an unknown response type.

const result = await emby.requestApi<{ status: boolean }>(
  'chats/support-42/webhook',
  { url: 'https://example.com/hooks/chat' },
  'put',
);

The path is relative to /api/v1/. See Emby for all method signatures.