← Documentación

WordPress

A WordPress site can take the widget the same way any site does — a <script> tag before the closing </body>. It can also take a plugin that manages that tag for you, so there is nothing to paste into a theme and nothing to put back after a theme update.

Both end up rendering the same script. The difference is who maintains the tag.

Before you start

Either way, the persona needs an origin — the domain the widget is allowed to run on. Each origin has its own public key, and the widget will not start without one. If the dashboard says the persona has no associated origin, add the domain under Origins first.

The public key is safe to publish. It only works from a domain you have registered, so a copy taken from your page source is inert anywhere else. An SDK key (sk_live_…) is a different thing entirely and must never go on a site — it carries full persona authority with no domain binding.

Using the plugin

The plugin gives a site owner a settings screen instead of a snippet, and renders the tag into the footer itself.

Install it, then open Settings → Equilia and fill in three values. All three come from the dashboard: Personas, select a persona, then Show widget.

  • Organization ID
  • Persona ID
  • Public key

Save, then use Test connection. This is the part worth doing. It calls Equilia from your server with your site's real address attached, so a pass means both that the credentials are right and that this domain is registered as an origin — the usual reason a correctly-pasted widget never appears. Without it, that failure only shows up in the browser console of whoever happens to look.

A few display options sit alongside:

  • Button position — which corner the launch button sits in.
  • Show the widget on this site — turn it off to disable the widget without losing the settings.
  • Show an icon instead of a text button.
  • Hide it from administrators — keeps it out of your way while logged in.

Dashboard address should be left alone unless you were given a different one.

Everything else about the widget — greeting, languages, which channels it offers, theme — comes from the persona and is fetched when a visitor opens it. You change those in the dashboard and the site follows.

Pasting the snippet instead

If you would rather not add a plugin, copy the widget script from the persona and place it before the closing </body> tag. Three common ways:

  • A headers-and-footers plugin. Paste the snippet into the footer section. Most such plugins also offer conditional rules if you want it on some pages only.
  • A Custom HTML block. Add one at the bottom of a single page and paste the snippet in. Good for trying it on one page.
  • Theme File Editor. Edit your theme's footer.php directly and paste before </body>.

Editing theme files works, but the edit belongs to the theme rather than to you: updating the theme, or switching it, removes the widget with no warning. If you go this route, use a child theme, and remember the tag is there when something later changes.

Keeping the widget off certain pages

The plugin can hide the widget from logged-in administrators from its settings screen. For anything more specific, it exposes a filter:

// Keep the widget off particular pages.
add_filter( 'equilia_should_render_widget', fn( $show ) => is_page( 'checkout' ) ? false : $show );

A second filter adjusts the embedded configuration before it is printed:

add_filter( 'equilia_widget_config', function ( array $config ): array {
    $config['WIDGET_THEME'] = 'midnight';
    return $config;
} );

Troubleshooting

  • Nothing appears. Usually the domain does not match a registered origin. Run Test connection, which reports exactly that rather than leaving it to the console.
  • A security plugin blocks it. Firewall and hardening plugins can strip third-party scripts. Allow the Equilia script's domain in the plugin's rules.
  • The widget overlaps something. It uses a high z-index. Adjust your theme CSS where they collide.
  • reCAPTCHA does not load. If your site sends a Content Security Policy, it needs to allow google.com and gstatic.com. The conversation itself runs on Equilia's side, but the check is loaded in the visitor's browser.
  • The widget vanished after a theme update. A footer.php edit was overwritten. This is the failure the plugin exists to avoid.

Related

The website widget guide covers the snippet itself — what it carries, inline embedding, and single-page applications. To drive conversations from your own PHP rather than the browser, see the SDKs.