Visitor Profiles and CRM

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:

1. Create the Airgentic properties in your HubSpot or Marketo account first.
2. Turn on that destination and add credentials.
3. Map only extra qualification fields that already exist in the CRM. Standard contact fields and conversation tags are sent automatically.

An unknown property name fails the whole contact or lead update. Create the fields before the first live sync.

What is sent automatically

You do not need a field mapping for these.

Conversation tags are the labels from Human Handoff (Callback; Enrolment; Visa issue). The CRM field builds up over time: tags from the contact's earlier conversations stay, and this conversation's tags are added to them. Removing a chip removes it from the CRM only if it was added in this conversation.

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. It is not mapped to Marketo’s lead id. HttpOnly cookies cannot be read. When the cookie is Marketo's own Munchkin cookie (_mkto_trk), Airgentic does not copy it into airgenticUserId; see Munchkin cookie.

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.

Existing contacts: overwrite or fill blanks

Airgentic does not verify an email typed into chat, so a visitor could enter someone else's address. By default, values captured in the conversation replace the values on the matching contact or lead. List the fields that should only ever fill an empty CRM field:

visitor_profile:
  integrations:
    marketo:
      fill_blank_only: [first_name, last_name, phone]

Fields in that list are written only when the CRM record has no value for them. Other fields, such as study area or intended intake, still take the latest value from the conversation. A visitor can still correct a value they gave earlier in the same chat. email and conversation tags cannot be listed.

Values that Airgentic reads from the CRM are shown to staff on Human Handoff, but never to the AI assistant or the visitor. The assistant treats them as unknown until the visitor states or confirms them. So a mistyped email, or a shared computer that matches someone else's record, does not lead the assistant to repeat another person's details.

Inbound lookup (hydrate on identify)

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):

airgenticUserId must be searchable in Marketo Field Management. If it is not filterable, identify falls through to email and this page still applies.

Munchkin cookie (Marketo)

If your website runs Marketo Munchkin tracking, set the user id cookie to _mkto_trk:

user_id_cookie: _mkto_trk

Then:

• A returning visitor whose browser Marketo already knows is matched to their lead from the cookie, before they type anything.
• When a chat writes to a lead, Airgentic links the browser's cookie to that lead once (Marketo's Associate Lead call). Marketo then merges the browser's earlier anonymous web activity into the lead, as it does when someone fills in a Marketo form.

A cookie that Marketo has only seen anonymously is not used as a match. The visitor is matched once they give an email address.

Hydrate does not create or patch the CRM record. Writes still happen on the usual sync after the fingerprint changes.

The lookup asks for every mapped field, so phone and custom qualification fields fill as well as name and email. Filled values are visible to staff, not to the assistant (see above).

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 — one note per conversation, updated as the chat goes on (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]

Go-live checklist

Do these in your HubSpot or Marketo account — the one whose credentials you will paste into Airgentic.

1. Create the Airgentic properties

HubSpot (Settings → Properties → Contact properties):

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):

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.

2. Turn on sync in Airgentic

On Configuration & Design → Visitor profile:

1. Turn Visitor profile capture on.
2. Turn CRM sync on.
3. Open the HubSpot or Marketo tab, turn that destination on, and enter credentials.

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}. Use a domain that does not receive mail. Placeholders have limits:

• With a placeholder domain, the profile is re-sent on every turn, which uses far more API calls.
• Marketo: once the visitor gives a real address, Airgentic writes to the lead with that address. The placeholder lead is left behind as a separate record.
• HubSpot: the placeholder contact is updated with the real address. If another contact already has that address, HubSpot rejects the update.

Leave the placeholder domain empty unless you need anonymous chats in the CRM.

3. Map only extra fields

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.

4. Verify with a test chat

1. Start a chat, give a name or email (or rely on the placeholder domain).
2. Confirm the contact or lead appears in the CRM with the expected fields.
3. On Human Handoff, claim the conversation, add a tag, and confirm airgentic_conversation_tags / airgenticConversationTags updates within a few seconds.
4. Remove one of those tags and confirm it disappears from the CRM field. Tags from the contact's earlier conversations stay.

When a write is skipped

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.

A failed or deferred write is retried on the visitor's next turn.

Conversation activity (Marketo)

Airgentic can record each conversation as a custom activity on the visitor's lead, so it shows in the lead's Activity Log and can drive smart lists and campaigns ("had an Airgentic conversation in the last 7 days", "handed off to an advisor", "tagged Callback").

When an activity is written

• One activity per conversation, written after the chat has been quiet for 30 minutes (quiet_minutes, 5–1440). If the visitor clicks to start a new conversation, the previous one is written straight away.
• It goes to the lead the conversation was matched to: by email, or for a returning visitor by Munchkin cookie or airgenticUserId. Conversations that never match a lead are not written.
• The activity date is when the conversation started.
• If the visitor comes back to the same conversation after it was written, a second activity is written with the later details. Adding a tag afterwards does not write another activity; tags still update airgenticConversationTags on the lead.
• Activities are queued in Airgentic. They survive restarts, are written once even across several servers, and go up to 300 per API call. If the activity type does not exist yet, or Marketo is busy, they wait and are sent later. They are dropped after waiting 7 days.

Create the activity type

In Marketo, Admin → Marketo Custom Activities → New Custom Activity:

• API name: airgenticConversation (or your own; set it as activity_type)
• Primary field: API name conversationId, type String
• Add the fields below that you want. Leave out any you don't need; Airgentic only sends fields the type has. Then Approve the activity type.

The Marketo API user also needs the Read-Write Activity permission.

Turn it on

visitor_profile:
  integrations:
    marketo:
      activity:
        activity_type: airgenticConversation
        quiet_minutes: 30
        include_summary: true
        include_transcript: false
        attributes: {}        # e.g. {tags: chatTags} to use your own field name, or {page_url: ""} to leave one out

Transcripts can be long and may contain personal details the visitor typed. Leave include_transcript off if staff should open the transcript in Airgentic instead.

Marketo API usage

Marketo limits are per instance and shared with your other integrations: 100 calls per 20 seconds, and a daily quota. Airgentic keeps its share small:

• The access token is reused for its full lifetime instead of being requested on every write.
• The lead is read once per conversation. Later writes in the same conversation reuse it.
• A write happens only when a captured detail or a tag changes.
• Airgentic makes at most 20 Marketo calls per 20 seconds across all of its servers. Set max_calls_per_20s (1–100) to change this.
• If Marketo reports that its rate limit or daily quota is reached, Airgentic waits. After a quota error it stops calling Marketo until the quota resets at midnight US Central time.
• Optional daily_call_limit caps Airgentic's own calls per Marketo day.

visitor_profile:
  integrations:
    marketo:
      max_calls_per_20s: 20
      daily_call_limit: 20000

A conversation that identifies a visitor typically uses one lookup plus one write for each change. Linking a Munchkin cookie adds one call per lead per visit. Conversation activities are batched up to 300 per call, plus one call an hour to read the activity type. Use a dedicated Marketo API user for Airgentic so its usage shows separately under Admin → Integration → Web Services.

Related documentation

• Visitor Profiles — What visitor profiles are and how fields are captured
• Playbooks — Match on hydrated fields; set CRM lead source on the next write
• Human Handoff — Tagging conversations and taking over a chat