Skip to content
Markdown
GuideForDeveloperWith or without Foxden Admin

Embed forms, signing and chat on your site ​

This page lets you put three Foxden pieces inside your own website or app: a Pampas form, the Corsac signing page and the Culpeo chat widget. Each one shows only on the sites you list, so you start by adding your site's origin.

An origin is the scheme and host of your site, with no path: https://www.example.com.

Embed a Pampas form ​

Before you start ​

  • You can use Pampas and the form is published. A form that was never published has no public link to embed.

Steps ​

  1. In Pampas, open the form.

  2. Select Share.

  3. Under Allowed origins, select Add origin.

  4. Enter your site's origin. While you try it out, http://localhost and http://127.0.0.1 work too; any other origin must be https. A form takes up to 20 origins.

  5. Select Save origins. Until your site is listed, browsers refuse to show the form on it.

  6. Under Embed on your own site, copy the code from Iframe (any site). It looks like this:

    html
    <iframe
      src="https://forms.example.com/f/event_sign_up?embed=1"
      title="Event sign-up"
      style="width: 100%; min-height: 720px; border: 0;"
      loading="lazy"
    ></iframe>
  7. Paste it into your page where the form should appear.

The ?embed=1 on the address drops the form page's own background, so the form sits on your page's. Answers are saved through the embed like any other response.

Embed Corsac signing ​

Signers usually open their signing link from an email. To let them sign inside your own app instead, you frame the signing page and listen for what happens in it. This uses the Corsac API.

Before you start ​

  • Someone who can manage Corsac lists your app's origin.
  • You have a Corsac API key and a document that has been sent (status pending).

Allow your site ​

  1. In Corsac's settings, open Company.
  2. Under Embedding the signing page, enter each origin in Allowed origins, one per line. No wildcards; an empty list means no site may frame the page.
  3. Select Save changes.

If the section reads Set by this instance's configuration, the list is fixed on the server (EMBED_ALLOWED_ORIGINS) and the person who runs Corsac changes it there. Any origin other than http://localhost or http://127.0.0.1 must be https.

  1. Ask for the recipient's link, naming the origin of the page that will frame it:

    bash
    curl -s "$CORSAC/recipients/$RCP/signing-url?embed=true&return_origin=https://app.example.com" \
      -H "Authorization: Bearer $KEY"

    If the origin is not on the list, the answer is 403 and says so. A link works only while the document is pending.

  2. Put the returned url in an iframe on that page.

  3. Listen for messages from the signing page. Each one is posted to your origin only:

    js
    window.addEventListener("message", (event) => {
      if (event.origin !== "https://sign.example.com") return;
      const m = event.data;
      if (m?.source !== "corsac") return;
      // m.type: "corsac:ready", "corsac:signed", "corsac:declined" or "corsac:error"
      // m.documentId and m.recipientId; m.code on an error
    });

The messages carry ids only, never names, emails or field values. Once you see corsac:signed, read the document with the API to see whether every signer has finished.

Embed the Culpeo chat widget ​

Before you start ​

  • You can manage Culpeo, and the inbox the chat should land in exists.

Steps ​

  1. In Culpeo, open Settings.

  2. Select Website widget. Each inbox has its own card.

  3. In the inbox's card, under Where it may appear, select Add an origin.

  4. Enter your site's origin.

  5. If you want, change the Words and the Look (Accent, Launcher position, Mark). A field left empty keeps its default.

  6. Select Save widget. The card shows Embeddable once an origin is saved.

  7. Under Install snippet, select Copy snippet. It is one line:

    html
    <script src="https://support.example.com/embed.js" data-inbox="general" async></script>
  8. Paste it anywhere in your page's HTML.

Open preview shows the widget as visitors will see it.

The widget adds a chat button in a corner of the page. Your page's own scripts can also control it:

CallDoes
Culpeo.open()Opens the chat.
Culpeo.close()Closes it.
Culpeo.toggle()Opens or closes it.
Culpeo.ask("text")Opens the chat and asks this question (up to 500 characters).
Culpeo.destroy()Removes the widget from the page.

Troubleshooting ​

The form or chat does not appear on my site ​

Your site's origin is not on the list, or is not written the same way (https://www.example.com and https://example.com are different origins). Add the exact origin your page runs on.

The return_origin is not on Corsac's list of allowed origins. Add it under Embedding the signing page.

The document is not pending: it is still a draft, or it is already completed, declined, voided or expired.

Foxden is open source under Apache-2.0.