> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iinkedsign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed editor

> Learn how to embed the package editor into your web application.

## Overview

The embed package editor feature allows you to integrate our package editor directly into your web application.
This provides a seamless experience for users, enabling them to modify and template packages before they are sent without leaving your platform.

## Package `state`

When embedding the package editor, it is recommended to set the package `state` to either `add` or `draft`.

### Add `add`

By creating the package in an `add` state the package editor will guide the user through the package properties and templating the documents just like the native add package experience.

<Tip>
  If you plan on updating an existing package and displaying the embedded package editor again you should set the state to `add` in your call to `packages/update`.
  If you do not set the state to `add` during the update, the package will automatically transition into a `draft` state.
  If the package has already been sent the state can no longer be transitioned back to `add`.
</Tip>

### Draft `draft`

If you are adding all the signers and documents or disabling the editing of the package properties,
then creating the package in a `draft` state with `focusTemplating` embed option is the preferred approach.

## Steps

<Steps titleSize="h3">
  <Step title="Add package">
    When you want to embed the package editor, you have to create a package with `generateEditLink` and the `embedded` package option set to `true`.

    ```http Request highlight={6,8} theme={null}
    POST /packages/add
    {
        "name": "Embedded Package Editor",
        "type": "concurrent",
        "state": "draft",
        "generateEditLink": true,
        "options": {
            "embedded": true,
            "embed": {
                "focusTemplating": true
            }
        },
        "signers": [
            {
                "firstName": "signer",
                "lastName": "one",
                "email": "signer.one@example.com"
            }
        ],
        "documents": [
            {
                "fileName": "document.pdf",
                "fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
            }
        ]
    }
    ```

    ```json Response highlight={5} theme={null}
    {
        "package": {
            ...
            "editLink": {
                "link": "https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA"
            },
            ...
        }
    }
    ```

    #### Embed options

    You can customize the embedded package editor experience by setting additional `embed` options.

    <Expandable title="options">
      <ParamField body="embedded" type="boolean">
        Enable embedded signing mode.
      </ParamField>

      <ParamField body="embed" type="object">
        Embed options used to customize the embedded package editor.
        <Badge icon="sparkles" size="sm" color="purple">2.8</Badge>

        <Expandable title="properties">
          <ParamField body="disableSend" type="boolean">
            User can only save changes to draft packages; the user will not be able to send it.
          </ParamField>

          <ParamField body="disableProperties" type="boolean">
            User will not be allowed to modify package properties.
          </ParamField>

          <ParamField body="disableVerification" type="boolean">
            User will not be allowed to modify package verification properties.
          </ParamField>

          <ParamField body="disableSigners" type="boolean">
            User will not be allowed to modify package signers.
          </ParamField>

          <ParamField body="disableDocuments" type="boolean">
            User will not be allowed to modify package documents.
          </ParamField>

          <ParamField body="disableEditing" type="boolean">
            User will not be allowed to modify package properties, verification properties, signers, or documents. They will still be allowed to template each document.
          </ParamField>

          <ParamField body="focusTemplating" type="boolean">
            The first document will be focused when the package editor is loaded instead of the package properties.
          </ParamField>

          <ParamField body="returnUrl" type="string">
            User will be redirected back to the returnUrl when they are done editing the package.
          </ParamField>

          <ParamField body="returnState" type="string">
            Will be included in a `state` query string parameter appended to the `returnUrl`.
          </ParamField>
        </Expandable>
      </ParamField>
    </Expandable>
  </Step>

  <Step title="Embed edtior">
    To embed the package edtior in an iframe, you need to use the `editLink.link` provided in the add package response or by calling the [Packages link API](/v4/api/packages/link) endpoint directly.

    ```html theme={null}
    <iframe 
        id="editor-iframe"
        src="https://sign.syngrafii.com/link/6iC4sCyjRaMTm2FcMjwIVA"
    ></iframe>
    ```

    <Tip>
      If you are embedding existing packages consider generating a new edit link before embedding as they **expire after 60 minutes**.
    </Tip>
  </Step>

  <Step title="Process embed messages">
    When embedding the package editor, you may want to handle certain events such as when the package is sent by the user.
    You can achieve this by listening for messages from the iframe.

    ```javascript theme={null}
    window.addEventListener("message", (event) => {
        // Validate origin
        if (event.origin !== "https://sign.syngrafii.com" || !event.data) return;

        // Handle action
        switch (event.data.action) {
            case "package_close":
                // User has closed the package editor. You should continue with your workflow.
                break;
            case "package_send":
                // User has sent the package and closed the package editor. You should continue with your workflow.
                break;
            case "session_expired":
                // User session has expired. The package editor will show an Expired Session message
                break;
        }
    }, false);
    ```

    See the [Embed messaging guide](/v4/guides/embed-messaging) for more information.
  </Step>
</Steps>

## Redirecting

If your workflow does not allow for embedding via `iframe` you can optionally redirect your users to the package edit link
and have it redirect back to your site by setting the `options.embed.returnUrl` to a valid URL during the call to add package.

```http Request highlight={6,10-11} theme={null}
POST /packages/add
{
  "name": "Embed Package Edtitor",
  "type": "concurrent",
  "state": "draft",
  "generateEditLink": true,
  "options": {
    "embed": {
      "focusTemplating": true,
      "returnUrl": "https://example.com/your-return-url",
      "returnState": "your-state"
    }
  },
  "signers": [
    {
      "firstName": "signer",
      "lastName": "one",
      "email": "signer.one@example.com"
    }
  ],
  "documents": [
    {
      "fileName": "document.pdf",
      "fileId": "682f1158-e3f5-4329-8f88-c52cb5447d8c"
    }
  ]
}
```