Developers › Recipes
Developer Reference Custom metadata Send fields beyond the standard contract and a workspace can put them on their leads, total them, or use them to route. Optional, additive, and it never affects a score or a price.
Do you need this? Probably not, and that is a fine answer. A connector that sends the standard contract is complete — nothing here can cause a rejection, a conformance note or a degraded lead. Skip the page and nothing breaks. Add it when the answer to one question is yes: is there something this customer's business cares about that LeadLogiX does not already extract? A partner id, a qualifying answer your tooling already computed, a preference their team routes on. Your agent is the only thing in the conversation, so a fact that is not in the transcript and not in the metadata does not exist downstream — this is how it survives. It's a per-customer call The same agent serving two workspaces may send extra keys that only one of them maps. Sending a key nobody maps costs nothing — it is retained and left uninterpreted. Custom fields ride the session you already send — Ingest a session covers that envelope. For your AGENT’S ACTIONS rather than your own fields, see Tool calls as evidence , which is the higher-leverage of the two.
How it works, end to end You add a key to the session metadata No new endpoint and no extra call — the same metadata you already send, with one more key. Name it yourself. The workspace admin maps it, or doesn't In Settings → Custom Signals they point a signal at your key and choose how it appears. In Settings → Lead Tags they can separately write a rule against the same key. Both are their decisions, made without you. It shows up, or it acts A signal renders on the lead (field, badge, or a total in their Analytics Hub). A tag rule drives alerts, CRM sync, automations and who can see the lead. One key, both uses The two features read your metadata independently — neither is built on the other, and a signal does not have to exist for a tag rule to work. A rule names your key with a sourceMetadata. prefix, never a signal's name.
What to send The same envelope, one more key. Values are stringified exactly once, as everywhere else. The standard contract keys ( sessionId , started , embedding , …) as usual, plus yours: metadata { "sessionId": "conv_9F3A21", "started": "2026-07-25T14:01:02.000Z", "partnerCampaignId": "PC-4471", "preferences": "{\"contactTime\":\"evenings\",\"tier\":\"vip\"}" } Constraint Limit Why it matters to you Path depth 5 segments preferences.tier is 2. A value buried 6 deep cannot be reached. Path length 128 characters Long key names spend that budget. Value types text · number · yes/no An object or array cannot be mapped directly — send its leaf fields. Per workspace 25 signals Yours is one of a shared allowance. Send what is useful, not everything. Stringification exactly once A doubly-encoded object cannot be walked into.
Four rules that decide whether it actually works Send leaves, not trees {"tier":"vip"} stringified once is ideal — the admin points at preferences.tier . A deep tree is not reachable. Keep values matchable A tag rule matches with equals . "PC-4471" works; "campaign PC-4471 (spring)" does not. Keep names and types stable Mapping is by path, so renaming a key silently stops a configured signal from finding anything. A key that is a string on some sessions and an object on others populates intermittently. Omit optional keys — don't blank them A rule can test presence alone. An empty string still counts as present , so a key you always send but sometimes leave blank matches every lead. Omit it or send null .
What it cannot do Extra keys are never scored, never priced and never used for identity. Extraction runs as a separate pass after scoring, so nothing you add here can move a lead's quality score or its price — by design, and worth saying to a customer who asks whether sending more will make their leads worth more. It will not. The AI that assigns tags reads the conversation , not your metadata. A fact that must be reasoned about belongs in the transcript; a fact that must be matched exactly belongs in metadata. Send it in both places when both matter. PII belongs where PII belongs Do not use a custom key as a side channel for personal data. It is copied onto the lead where the workspace's own role rules apply to it, and the same privacy rules govern metadata as everywhere else in the contract. You'll know it worked: The customer sees the field on their next lead — not on older ones, because signals are read when a conversation is processed. If a new lead shows nothing, the key is not arriving under the name they mapped, which is a question for you rather than a setting on their side.