Airgentic Help
When CRM sync is on, Airgentic writes the captured visitor profile — and any Human Handoff conversation tags — onto a HubSpot contact or Marketo lead. The platform owns that write (one sync, one adapter per CRM). You turn destinations on and map extra fields; you do not write a CRM function.
The same rules apply to both destinations:
An unknown property name fails the whole contact or lead update. Create the fields before the first live sync.
You do not need a field mapping for these.
| Visitor detail | HubSpot property | Marketo REST name |
|---|---|---|
email |
email |
|
| First name | firstname |
firstName |
| Last name | lastname |
lastName |
| Phone | phone |
phone |
| Organisation | company |
— |
| Conversation tags | airgentic_conversation_tags |
airgenticConversationTags |
| Chat session id | airgentic_session_id |
— |
| External user id | airgentic_user_id |
airgenticUserId |
Conversation tags are the labels from Human Handoff (Callback; Enrolment; Visa issue). Clearing every chip on the conversation also clears the CRM field.
The external user id is written only when the chat session has a user_id — typically from a first-party cookie named in Configuration & Design or data-user-id-cookie. It is an opaque value (for example a Marketo tracking cookie). It is not mapped to Marketo’s lead id. HttpOnly cookies cannot be read.
Map extra fields (campus, study area, and so on) only after those properties exist in the CRM, using the exact API / REST name.
Override a built-in name only if your CRM already uses a different property. Otherwise leave the extra mapping list empty for that field.
When a chat session already has a user_id and/or email, Auti looks up the contact once in the background and fills empty visitor-profile fields. Conversation values always win; CRM never overwrites a field the visitor (or the LLM extract) already set.
Search order is visitor_profile.lookup (default: user_id, then email):
| Destination | First lookup | Then |
|---|---|---|
| HubSpot | Contact Search on airgentic_user_id |
Existing email search |
| Marketo | filterType=airgenticUserId |
filterType=email |
airgenticUserId must be searchable in Marketo Field Management. If it is not filterable, identify falls through to email and this page still applies.
Hydrate does not create or patch the CRM record. Writes still happen on the usual sync after the fingerprint changes.
Lookup runs in the background after the session is identified, so the first answer may not yet include CRM fields. Playbooks that match on a hydrated attribute can add a layer on a later turn (earlier URL or geo layers stay).
A playbook CRM lead source is applied on the next write, not on hydrate, and freezes after that write succeeds. On HubSpot it appears on the conversation note (and on a lead-source contact property if one is configured for the service). Marketo does not currently map that label.
Optional YAML:
visitor_profile:
lookup: [user_id, email]
Do these in your HubSpot or Marketo account — the one whose credentials you will paste into Airgentic.
HubSpot (Settings → Properties → Contact properties):
| Internal name | Label | Type |
|---|---|---|
airgentic_conversation_tags |
Airgentic conversation tags | Multi-line text |
airgentic_session_id |
Airgentic session id | Single-line text |
airgentic_user_id |
Airgentic user id | Single-line text |
Also create any extra qualification properties you will map (for example campus, study_area).
Add those properties to the About this contact card (pencil on that left-sidebar card). HubSpot stores the values even if they are not on the layout; they are easy to miss until you add them.
Marketo (Admin → Field Management):
| REST API name | Label | Type |
|---|---|---|
airgenticConversationTags |
Airgentic conversation tags | Text / string |
airgenticUserId |
Airgentic user id | Text / string |
Create extra custom fields only for qualification details you will map. Confirm each REST API name in Field Management before adding a mapping in Airgentic.
On Configuration & Design → Visitor profile:
| Destination | Credentials |
|---|---|
| HubSpot | Private app access token with permission to read and write contacts (and notes, if conversation notes are enabled). |
| Marketo | Identity endpoint, REST endpoint, client id, and client secret. |
Tokens and secrets are stored securely. They are not shown again after you save.
Optional: set a placeholder email domain (for example youruniversity.edu) so chats without a real email still upsert as {session id}@{domain}. Once the visitor gives a real address, later updates use that address and still find the original contact.
Built-in rows (email, name, phone, conversation tags) are already wired. Add extra rows only for fields you created in step 1.
Do not add a mapping for conversation tags unless your CRM uses a different property name than the table above.
airgentic_conversation_tags / airgenticConversationTags updates within a few seconds.Sync does not run when capture is off, CRM sync is off, the destination has no credentials, or there is no email (captured or placeholder).
If a property name in the mapping does not exist in the CRM, the update fails and nothing on that contact or lead is changed. Check the property exists, then try again.