Introduction
The Marketo integration works differently from our website integrations. It doesn't add anything to your web pages. Instead, it connects the Airgentic assistant to your Adobe Marketo Engage instance, so the people your assistant talks to arrive in Marketo as leads, with their details filled in.
It is built on Visitor Profiles. While a visitor chats, the assistant fills in a profile: name, email, phone, and the qualification details you choose, such as student type, programme of interest, campus or intended intake. When CRM sync is on, Airgentic writes that profile to Marketo through the Marketo REST API.
The integration does three things:
- Lead create-or-update. Profile details are written to a Marketo lead, matched by email. Only the fields you map are sent.
- Returning-visitor match. If your site runs Munchkin tracking, a visitor Marketo already knows can be matched to their lead before they type anything. Their earlier anonymous web activity is merged into the lead.
- Conversation activities. Each conversation is recorded as a custom activity in the lead's Activity Log. You can use it in smart lists and campaigns.
There is no sync tool to install and no Marketo function to write. You create a few fields in Marketo, give Airgentic an API user, and turn the destination on. For more about what a visitor profile holds and how fields are captured, see Visitor Profiles.
1. How it works
- A visitor chats with your assistant. As they share details, the assistant records them on the visitor profile. Advisors see the same profile on the Human Handoff card.
- Once the profile has an email address, Airgentic creates or updates the Marketo lead with that email.
- When a captured detail or a conversation tag changes, Airgentic writes again. Nothing is sent when nothing has changed.
- When the conversation has been quiet for a while (30 minutes by default), Airgentic records it as a custom activity on the lead.
Airgentic is not a CRM. Marketo stays your system of record for leads, and Airgentic only writes the fields you have mapped.
2. What is sent to Marketo
These fields are sent automatically. You don't need to map them.
- Email to
email - First name to
firstName - Last name to
lastName - Phone to
phone - Conversation tags to
airgenticConversationTags. These are the labels from Human Handoff and AI tagging, for exampleCallback; Enrolment; Visa issue. - External user id to
airgenticUserId, when your site provides one
You can also map extra qualification fields to Marketo lead fields you name, such as campus, study area or intended intake. Use the field's exact REST API name from Field Management. For a picklist field, the allowed values in Airgentic must be copied exactly from the Marketo picklist. The assistant can only store a value from that list, and anything else is discarded before the write.
Conversation tags build up on the lead over time. Tags from earlier conversations stay, and this conversation's tags are added. If the combined tags would exceed Marketo's 255-character limit, the oldest whole tags are left off so the newest fit.
3. Protecting existing leads
Airgentic does not verify an email typed into chat, so a visitor could enter someone else's address. You can list fields, such as name and phone, that may only fill an empty Marketo field and never replace an existing value. Other fields, such as study area or intake, still take the latest value from the conversation.
Values that Airgentic reads from Marketo are shown to your advisors on Human Handoff. They are never shown 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 doesn't lead it to repeat someone else's details.
4. Returning visitors and Munchkin
If your website runs Marketo Munchkin tracking, Airgentic can use the _mkto_trk cookie to recognise returning visitors:
- A visitor whose browser Marketo already knows is matched to their lead from the cookie, before they type anything. Empty profile fields are filled from the lead in the background, and advisors see those values at handoff.
- When a chat writes to a lead, Airgentic links the browser's cookie to that lead once, using 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 isn't used as a match. The visitor is matched once they give an email address.
Looking up a lead never creates or changes it. Writes happen only through the normal create-or-update described above.
5. Conversation activities
Airgentic records each conversation as a custom activity on the lead it was matched to. It shows in the lead's Activity Log and can drive smart lists and campaigns, for example "had an Airgentic conversation in the last 7 days", "handed off to an advisor" or "tagged Callback".
Each activity can include:
- When the conversation started and ended, and the page the visitor was on
- The Airgentic service and the playbooks that applied
- This conversation's tags, including any the AI added
- Whether a human advisor took part, and the advisor's first name
- Whether the visitor asked for a follow-up, and their message
- The number of messages, and the visitor's 1 to 5 rating if they gave one
- The visitor's opening question and a short AI summary of the conversation
- A link that opens the conversation in the Airgentic console for your staff
- The full transcript (off by default)
The activity type only needs the fields you want. Airgentic sends only the fields your type defines, so you can start small and add more later. Transcripts can be long and may contain personal details the visitor typed, so leave them off if staff should open the conversation in Airgentic instead.
Activities are queued in Airgentic and written in batches of up to 300. They survive restarts and are written once, even across several servers. If Marketo is busy, or the activity type isn't approved yet, they wait and are sent later.
6. Attributing applications and enquiries to a chat
Airgentic can also set a first-party cookie on your site that holds the visitor's latest conversation ID, the same ID that is sent to Marketo. A Marketo form on your site can read it into a hidden field set to Get value from: Cookie value. That links an application or enquiry submitted later back to the chat that preceded it.
The cookie can be shared across your subdomains, for example from your main site to your applications portal. It can also wait for the visitor's consent in Cookie Yes before it is written.
7. Marketo API usage
Marketo's API limits apply to the whole instance and are shared with your other integrations: 100 calls per 20 seconds, plus a daily quota. Airgentic keeps its share small:
- The access token is reused for its full lifetime.
- The lead is read once per conversation, and later writes 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. This can be lowered or raised for your instance.
- If Marketo reports that its rate limit or daily quota has been reached, Airgentic waits. After a quota error it stops calling Marketo until the quota resets at midnight US Central time. You can also set an optional daily cap on Airgentic's calls.
A conversation that identifies a visitor typically uses one lookup plus one write for each change. We recommend a dedicated Marketo API user for Airgentic, so its usage shows separately under Admin → Integration → Web Services.
8. Setting it up
In Marketo
- In Admin → Field Management, create two text fields:
airgenticConversationTags(Airgentic conversation tags) andairgenticUserId(Airgentic user id). MakeairgenticUserIdsearchable so returning visitors can be matched by it. - Create any extra qualification fields you want to map, and note each field's REST API name.
- Create an API-only user with a role that can read and write leads and write activities. In Admin → LaunchPoint, create a custom service for that user and copy its client ID and client secret.
- From Admin → Web Services, copy the Identity and REST endpoints.
- For conversation activities, create the custom activity type, or ask us to create it for you. Marketo's Admin screen doesn't offer the Text and Link field types used for the summary, transcript and links, so we usually create it through the API. Either way, it must be approved before activities can be written.
Create the fields before the first live sync. Marketo rejects an update that names a field it doesn't have, and nothing on that lead is changed.
In Airgentic
- Open Configuration & Design → Visitor profile.
- Turn on Visitor profile capture and CRM sync.
- On the Marketo tab, turn Marketo on and enter the Identity endpoint, REST endpoint, client ID and client secret. The secret is stored in a key vault and isn't shown again after you save.
- Map any extra qualification fields to their Marketo REST API names.
- To use Munchkin matching, set the user id cookie to
_mkto_trk. - Ask Airgentic support to turn on conversation activities and the attribution cookie, if you want them.
Test it
- Start a chat and give a name and email address.
- Confirm the lead appears in Marketo with the expected fields.
- On Human Handoff, claim the conversation, add a tag, and confirm
airgenticConversationTagsupdates within a few seconds. - After the conversation has been quiet for the activity delay, confirm the activity appears in the lead's Activity Log.
9. When a write is skipped
Nothing is written when visitor profile capture or CRM sync is off, when Marketo has no credentials, or when the profile has no email address. A failed or deferred write is retried on the visitor's next message.
Learn more
- Visitor Profiles: what a visitor profile holds, how fields are captured, and how the same profile feeds HubSpot and Marketo
- Human Handoff: how advisors see the profile and tag conversations
- Questions about setting up Marketo? Contact us.