Link Chats to Form Submissions

Last updated October 24, 2026 · 13 views · 3 min read

What is visitor linking?

Visitor linking ties a visitor's chat to a form or survey they submit later, so your team sees the whole story in one place. When a visitor who has chatted fills in a form on your site, the submission carries a signed link that identifies the visitor and the conversation. Your team no longer has to match a lead to a chat by hand.

Visitor linking is off until you turn it on, and it is set per account.

Turn it on

1. Open Account and select the Visitor Linking tab.

2. Turn on Link chats to form submissions.

3. Set the Link lifetime. This is how long a link stays valid after the visitor chats. You can choose any value from 1 to 1440 minutes.

If the tab shows that links are not available on your account yet, contact Velaro support to finish setup.

Privacy and consent

A link is only created for a visitor who has started a chat.
If your site uses a cookie or consent banner, no link is created until the visitor accepts functional storage.
A link carries ids only. It never contains a name, email address or any other contact detail.
A link only works for the account that created it. A link from one account is rejected by every other account.
Links follow your conversation retention settings.

Use it with Velaro surveys and forms

Surveys and pre-chat and post-chat forms hosted by Velaro attach the link automatically once the feature is on. Submissions then show which chat they came from, and the conversation shows the later submissions.

Use it with your own forms

Your own form posts the link value to your server. Your server exchanges it for the visitor and conversation ids by calling the resolve endpoint with your API key.

1. Your page adds the link as a hidden field named velaro_link.

2. Your server receives the form post.

3. Your server sends a POST to /api/v1/visitor-links/resolve with { "token": "<velaro_link value>" }.

4. The response returns visitorId, conversationBaseId and contactId. Store them with your lead or ticket.

Never trust a visitor id sent from the browser. Always resolve the link on your server.

Manage it with the Velaro CLI and MCP

You can read and change the same settings with the Velaro CLI and the Velaro MCP.

velaro visitor-link settings get
velaro visitor-link settings set --enabled true --ttl-minutes 30
velaro visitor-link diagnose
velaro visitor-link resolve <token>

The MCP tools are visitor_link_get_settings, visitor_link_set_settings, visitor_link_diagnose and visitor_link_resolve.

Troubleshooting

What you see	Why	What to do
No `velaro_link` value on the form	The visitor has not chatted yet, linking is off, or consent was not given	Confirm linking is on and the visitor accepted functional storage
Resolve says the link is expired	The visitor waited longer than the link lifetime	Increase the link lifetime
Resolve rejects the link	The link came from a different account	Resolve it with the key of the account that created it
The tab says links are not available	Account setup is not finished	Contact Velaro support

Run velaro visitor-link diagnose <token> to check a specific link.

Was this article helpful?

How can we help you?