Poe Embed API

 sendUserMessage<Stream extends boolean>(
    /** The text to send.  In most cases this should start with `@BotName` */
    text: string,
    options?: {
      /** Files to include */
      attachments?: File[];
      /** Whether to invoke the handler with incomplete results as they are available or to only invoke it with the final complete result.  Each result contains all tokens so far. */
      stream?: Stream;
      /** Whether to open the chat on send. */
      openChat?: boolean;
      /** The registered name of the handler function to invoke with the results */
      handler?: string;
      /** Optional additional context to pass to the handler. */
      handlerContext?: HandlerContext;
    }
  ): Promise<
    { success: boolean}
  >;

  registerHandler(
    /**
     * String identifier for the handler. Used to associate responses with this callback.
     */
    name: string,
    /**
     * Callback function that receives response messages. Each result contains an array
     * of messages with their content and status.
     * The handlerContext specified in the sendUserMessage call will also be passed to the callback.
     */
    func: (result: SendUserMessageResult, context: HandlerContext) => void
  ): VoidFunction;

let someFile: File

window.Poe.registerHandler("myHandler", (result) => {
  console.log(result.responses[0]?.content)
})

let result = await window.Poe.sendUserMessage(
    "@assistant what is this?",
    { attachments: [someFile], stream: true, handler: "myHandler" }
 )
 console.log(result) // { success: true }

type SendUserMessageResult = {
  status: "incomplete" | "complete" | "error";
  /**
   * In most cases, this will be a single bot message however in some cases a single human message
   * may trigger multiple bot responses.
   */
  responses: Message[];
};

/** A message from the bot. */
type Message = {
  messageId: string;
  /** The name of the bot that sent the message. e.g. "Assistant" */
  senderId: string;
  /** The entire content of the message recieved so far */
  content: string;
  /** Either text/plain or text/markdown */
  contentType: string;
  /** Each status should be handled to let the user know the current state of the message. */
  status: "incomplete" | "complete" | "error";
  /** A user friendly message to explain the current status.  Usually only specified for error status. */
  statusText?: string;
  attachments?: MessageAttachment[];
};

interface PoeEmbedAPIError extends Error {
  errorType: PoeEmbedAPIErrorType;
}

type PoeEmbedAPIErrorType = "UNKNOWN" | "INVALID_INPUT" | "USER_REJECTED_CONFIRMATION" | "ANOTHER_CONFIRMATION_IS_OPEN"

/** The public interface of the Embed API.  This class is accessible from `window.Poe` */
interface PoeEmbedAPI {
  /** Send a message to the bot. */
  sendUserMessage<Stream extends boolean>(
    /** The text to send.  In most cases this should start with `@BotName` */
    text: string,
    options?: {
      /** Files to include in the user message. */
      attachments?: File[];
      /** Whether to invoke the handler with incomplete results as they are available or to only invoke it with the final complete result.  Each result contains all tokens so far. */
      stream?: Stream;
      /** Whether to open the chat on send. */
      openChat?: boolean;
      /** The name of the handler function to invoke with the results */
      handler?: string;
      /** Optional additional context to pass to the handler. */
      handlerContext?: HandlerContext;
    }
  ): Promise<
    { success: boolean}
  >;

  /** Register a handler function that is invoked with the results of the `sendUserMessage` call. The handler should be registered before the `sendUserMessage` call is made and ideally before the user has made interactions with the page. */
  registerHandler(
    /** The name of the handler function to register. This name should match the `handler` option in `sendUserMessage`. */
    name: string,
    /** The function that is invoked with the results of the `sendUserMessage` call. */
    func: (result: SendUserMessageResult, context: HandlerContext) => void
  ): VoidFunction;

  APIError: typeof PoeEmbedAPIError;
}

/** Error that may be thrown by an Embed API method such as `sendUserMessage` */
class PoeEmbedAPIError extends Error {
  errorType: PoeEmbedAPIErrorType;
}

type MessageAttachment = {
  attachmentId: string;
  mimeType: string;
  url: string;
  isInline: boolean;
  name: string;
};

/** A message from the bot. */
type Message = {
  messageId: string;
  /** The name of the bot that sent the message. e.g. "Assistant" */
  senderId: string;
  /** The entire content of the message recieved so far */
  content: string;
  /** Either text/plain or text/markdown */
  contentType: string;
  /** Each status should be handled to let the user know the current state of the message. */
  status: "incomplete" | "complete" | "error";
  /** A user friendly message to explain the current status.  Usually only specified for error status. */
  statusText?: string;
  attachments?: MessageAttachment[];
};

type SendUserMessageResult = {
  status: "incomplete" | "complete" | "error";
  /**
   * In most cases, this will be a single bot message however in some cases a single human message
   * may trigger multiple bot responses.
   */
  responses: Message[];
};

type HandlerContext = Record<string, any>;
type HandlerFunc = (
  result: SendUserMessageResult,
  context: HandlerContext
) => void;

type PoeEmbedAPIErrorType =
  | "UNKNOWN"
  | "INVALID_INPUT"
  | "USER_REJECTED_CONFIRMATION"
  | "ANOTHER_CONFIRMATION_IS_OPEN";

/** accessible via window.Poe */
declare global {
  interface Window {
    Poe: PoeEmbedAPI;
  }
}