google-tag-manager-guide
Google Tag Manager Integration
Velaro integrates with Google Tag Manager (GTM) in two directions: GTM deploys your Velaro chat widget to any website without code changes, and Velaro pushes chat events into the GTM data layer so you can send them to Google Analytics 4, Google Ads, Meta Pixel, or any other tag.
---
Deploy the Velaro Widget via GTM
Use this method to add the Velaro chat widget to any website where GTM is already installed.
1. In Velaro, go to Settings → Deployments
2. Select the deployment you want to embed, then click Get Code
3. Copy the embed snippet
4. In Google Tag Manager, click Tags → New
5. Set the tag type to Custom HTML
6. Paste the Velaro embed snippet into the HTML field
7. Set the trigger to All Pages (or a specific page trigger if you want the widget on selected pages only)
8. Click Save, then publish your GTM container
The widget appears on your site immediately after the container is published. No changes to your website code are required.
---
Push Chat Events to GTM
Velaro fires events into the GTM dataLayer automatically when the widget is deployed via GTM. These events are available to any tag in your container.
Events fired
| Event name | When it fires |
|---|---|
| chat_started | Visitor opens the chat widget and sends the first message |
| message_sent | Visitor sends any message in an active conversation |
| conversation_resolved | Agent or bot marks the conversation resolved |
| csat_submitted | Visitor submits a CSAT rating |
| form_submitted | Visitor completes a pre-chat or contact form |
| bot_escalated | Bot transfers the conversation to a live agent |
Variables available in the data layer
| Variable | Description |
|---|---|
| visitor_id | Velaro's anonymous visitor identifier |
| session_id | Current conversation session ID |
| chat_score | CSAT score (1–5), populated on csat_submitted |
| resolution_type | bot, agent, or abandoned, populated on conversation_resolved |
---
Send Events to GA4
1. In GTM, create a new tag with type Google Analytics: GA4 Event
2. Select your GA4 configuration tag
3. Set the event name to {{Event}} (this passes the Velaro event name directly)
4. Add any parameters you want (e.g., chat_score: {{dlv - chat_score}})
5. Set the trigger to Custom Event and enter the Velaro event names you want to track (e.g., chat_started, csat_submitted)
6. Save and publish
---
Send Events to Google Ads
To record chat interactions as Google Ads conversions:
1. Create a conversion action in Google Ads for the event you want to track (e.g., chat_started)
2. In GTM, add a Google Ads Conversion Tracking tag
3. Set the trigger to the Velaro custom event (e.g., chat_started)
4. Save and publish
---
Send Events to Meta Pixel
1. In GTM, add a Custom HTML tag with your Meta Pixel event code
2. Reference the Velaro event using {{Event}} or fire a specific pixel event (e.g., fbq('track', 'Lead')) on chat_started
3. Set the trigger to the Velaro custom event
4. Save and publish
---
Troubleshooting
| Symptom | What to check |
|---|---|
| Widget not appearing on site | Confirm the GTM container is published and the tag trigger is set to All Pages (or the correct page trigger). Use GTM Preview mode to verify the tag fires. |
| Events not in GA4 | Use GTM Preview mode to confirm the Velaro events are firing in the data layer. Confirm the GA4 event tag trigger matches the Velaro event name exactly (case-sensitive). |
| chat_score variable empty | chat_score is only populated on the csat_submitted event. Confirm your CSAT survey is enabled in Settings → Chat Settings → CSAT. |
| Widget loads on wrong pages | Review the trigger in your GTM Velaro tag. Switch from All Pages to a Page Path trigger if you want the widget on specific URLs only. |
| Multiple widgets appear | If your site also has the Velaro snippet installed directly in the HTML, remove it — loading the widget twice causes duplicates. |
Was this article helpful?