CTA overlays
A CTA overlay opens the link’s destination in a full-page frame and draws
your message on top of it. It is available on Pro, Business and Enterprise.
The edge serves it only when the destination allows framing: Elido checks
the destination’s X-Frame-Options and CSP frame-ancestors headers in the
background when you attach an overlay and again every day. Until the check
passes, and for sites that forbid framing, visitors get a normal redirect.
Positions
position | What visitors see |
|---|---|
bottom_bar | A bar along the bottom of the page (up to 640 px wide, centred) |
top_bar | The same bar along the top |
bottom_right | A floating card in the bottom-right corner (360 px) |
bottom_left | A floating card in the bottom-left corner |
modal_center | A centred dialog over a dimmed backdrop; Esc or a click on the backdrop closes it |
On screens narrower than 560 px the corner cards become a bottom sheet and bars stretch to the screen width. Every position has a close button.
Types and the fields they use
The overlay object has one flat set of fields. Each cta_type uses them as
follows; the API answers 422 when the fields do not fit the type.
cta_type | headline | body_text | button_text | button_url | other |
|---|---|---|---|---|---|
text_button | required | optional | required | required | image_url |
email_capture | required | optional | submit label (optional) | privacy policy (optional) | image_url |
discount_code | required | optional | the code, max 40 | shop link (optional) | image_url |
social_follow | required | 1-8 profile URLs, one per line | - | - | |
survey | the question | 2-6 answers, one per line, max 80 | thank-you text (optional) | - | |
custom_html | optional | - | - | - | custom_html (required, max 10 000) |
Limits: headline 200 characters, body text 1000, button text 80, URLs 2048
(absolute http/https only). Colours are #rgb or #rrggbb.
- Discount code shows the code with a Copy button; copying counts as a click.
- Social follow shows one button per profile, labelled with the network name (Instagram, X, LinkedIn, YouTube, TikTok and about 25 others; any other site shows its host name).
- Survey shows the answers as buttons. One click records the answer.
- Email capture shows an email field, a consent line (“By subscribing
I agree to receive emails from the owner of this link. You can unsubscribe at any time”, shown next to an unticked checkbox the visitor must tick) and, if you set
button_url, a link to your privacy policy. - Custom HTML is shown in a sandboxed frame inside the card: no
scripts, no forms, no requests except
httpsimages; links open in a new tab. The frame is sized to its content, estimated from the markup because the frame has no scripts (at most 160 px in a bar, 260 px in a corner card, 360 px in the modal); longer content scrolls inside it.
Look and language
The card follows the visitor’s light or dark system theme. button_bg and
button_text_color colour the button (and the Copy button); bg_color and
text_color are stored but the card does not use them. The fixed labels
(Close, Copy, Subscribe, the consent line, “Powered by Elido”) appear in the
visitor’s browser language, in the 13 product languages. Your own text is
shown as written.
Create an overlay
curl -X POST https://api.elido.app/v1/workspaces/1/cta \
-H "Authorization: Bearer $ELIDO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Newsletter modal",
"cta_type": "email_capture",
"position": "modal_center",
"headline": "Get the monthly digest",
"body_text": "One email a month, no spam.",
"button_text": "Count me in",
"button_url": "https://example.com/privacy"
}'Then attach it to a link with cta_overlay_id on POST /v1/links or
PATCH /v1/links/{id}, or pick it in the link editor.
PATCH /v1/workspaces/{id}/cta/{cta_id} changes only the fields you send;
send "" to clear a text field.
Collected answers
Email and survey answers are stored per overlay. Read them in the dashboard under CTA overlays → Answers, or through the API:
curl https://api.elido.app/v1/workspaces/1/cta/42/submissions \
-H "Authorization: Bearer $ELIDO_TOKEN"
# {"items":[{"id":7,"kind":"email","email":"[email protected]","link_id":12,...}],
# "total":1,"answers":[]}?format=csv returns up to 1000 rows as CSV. DELETE /v1/workspaces/{id}/cta/{cta_id}/submissions/{submission_id} removes one
answer, for example when a visitor asks you to erase their email. Reading
and deleting answers needs the cta_submissions.view permission, which
admins and owners have by default.
Details of the visitor side:
- The overlay page posts to
POST https://api.elido.app/v1/public/cta/{cta_id}/submit. - One visitor can send 5 answers to an overlay at once, then one every 12 seconds; there is also a cap per overlay.
- A repeat email for the same overlay is stored once.
- No IP address or user agent is stored with an answer.
- Elido does not send emails to these addresses. You are the controller of the list; export it to your email tool.
Tracking
The overlay records an impression when it is shown and a click when the
visitor uses the button, copies the code, opens a social profile or sends
an answer. GET /v1/workspaces/{id}/cta/{cta_id}/stats returns the totals.
What overlays do not do
- Only the link’s main destination is framed. A/B variants and targeting rules get a normal redirect.
- Encrypted links cannot use an overlay.
- Bulk link creation does not accept
cta_overlay_id. - There is no delay, exit-intent trigger or A/B test of overlay copy, and “Powered by Elido” cannot be removed.
- Because of caching, a change to an overlay can take a few minutes to reach visitors.