Frequently asked questions
Answers to common questions about matching a chatter to their own data, and how attachments count toward usage.
How do I match the person I'm chatting with to a row in my own data table?
A common pattern: an agent backed by a data table needs to answer "what's my order status" or "what's my account balance" — which requires finding the current chatter's own row before it can answer.
The source of truth: a contact ID field
Add a field of type contact ID to your collection. This is the single source of truth for who a record belongs to:
- It's stamped automatically. Every time your agent creates a record, the platform fills this field with the current conversation's contact, resolved server-side from the channel the message arrived on. The agent — and therefore anyone chatting with it — can never set or spoof it.
- It's immutable. Once a record is created, its owning contact cannot be changed.
- It scopes reads. Set the agent's data table access to self-scoped, on the agent's data table permissions. The agent can then only read rows whose contact ID matches the current contact, so "what's my order status" just works, and one person can never see another person's rows. This is enforced on the server; the agent cannot opt out of the filter.
That's the whole pattern: add the contact ID field, turn on self-scoped access, and both writing the owner and filtering to the owner happen automatically.
Why not just ask for a name, email, or ID number?
Do not have the agent ask the chatting user for their name, email, phone number, or an ID number and then search your data table with that as the lookup key. Anything typed into a chat is a self-reported claim, not proof of identity — anybody can claim to be anybody. An agent that trusts a user-supplied identifier to look up records can be tricked into handing one person's data to someone else.
Always identify the caller by the platform-resolved contact ID, never by a value the user asserted in the conversation. Encrypted fields also support exact-match search only and are never returned to the agent in plaintext, so they cannot be used as an identity lookup key either — use the contact ID.
Don't use an admin skill for this
A contacts-admin style skill is a different tool, meant for workspace admins or internal agents to manage the entire contact list — search across every contact, create, update, merge, delete, and link identities. It is not scoped to "the current caller." Attaching it to a public-facing agent lets that agent, and therefore anyone who can steer it in chat, search and read every contact in your workspace. Reserve admin-level skills for internal agents your own team controls — never attach one to a customer-facing agent.
Do photo, file, and voice note attachments count as extra interactions?
Yes, per attachment. A turn is billed as one base interaction, plus one more interaction for each photo, file, or voice note attached to that turn — not a flat addition regardless of count. Uploading 5 photos in a single turn adds 5 interactions, 6 total for that turn. This matches the actual processing cost: each attachment gets its own analysis — a vision model per photo, a dedicated pass per file, transcription per voice note. See interaction counting for the full breakdown.