# Custom Fields, Lead Profile & Notes Every contact has the basics — name, phone, email, channel. But you usually know a lot more about the people you talk to: their company, their birthday, what they bought last time, which conference they came in from. This page covers the extra pieces of information you can attach to a contact, and where each one lives. --- ## Overview | What | Best for | Where it lives | |---|---|---| | **Custom Fields** | Short structured facts (company, position, birthday, plan, etc.) | A list of key/value pairs on the contact | | **Notes (= Lead Profile)** | A free-form description of who this person is and why they matter — read by the AI when personalising replies | A single text area on the contact | | **Status** | Tracking where a contact is in their journey, including marking them spam | A single value on the contact | > **If you've used the app for a while:** what used to be two separate things — a long-form "Lead Profile" and a stacking list of dated Notes — are now merged into **one field**, labelled **Notes** on the contact's full record. There's no longer a separate timestamped notes log with titles; everything you'd write about a contact goes in this one box. See [Notes](#notes-lead-profile) below for what that means in practice. --- ## Defining Custom Fields Custom fields are reusable across all your contacts. Once you create a field like `company`, it becomes part of your account's schema and appears as a suggestion every time you edit another contact. **Field type:** Custom fields are free-text only — there are no dropdown, radio-button, or multiple-choice types. If you want a field to only ever hold one of a few set values (like a lead source of "Newsletter", "Referral", or "Ad"), type the same value consistently, or bulk-fill it via a spreadsheet export/re-import so every contact uses the exact wording you want. **Naming rules:** - Field names must use lowercase letters, numbers, and underscores only, and must start with a letter or underscore (for example `lead_source`, not `Lead Source`). - **Unaccented English letters only** — spaces, capitals and accented or non-Latin characters are rejected. Even if the rest of your account is in another language, name the field `cumpleanos` or `birthday`, not `cumpleaños`. Only the name is restricted; the value you store in it can be in any language. - An account can have up to **50 custom fields**. - Pick the name carefully — once a field is used in a template or campaign you cannot delete it without first removing those references. --- ## Filling In Custom Fields on a Contact 1. In the left sidebar, click **Contacts**. 2. Click a contact's row to open the [quick-view panel](creating-contacts.md), then click **Edit** — or click **New contact** to start a fresh one. 3. In the contact form, find the **Custom Fields** section. 4. Type a name into **Add a field** (existing field names appear as suggestions — click one to reuse it), click **Add**, then type the value. 5. Click **Save** on the form to store it. Fields that already have a value show up on the quick-view panel and the full contact record as read-only rows — to change a value, reopen **Edit**. **Deleting a field** from the edit form removes that value from the contact. Removing a field from every contact and your account's schema entirely still isn't possible while it's referenced by a template or campaign. --- ## Letting the AI Fill Custom Fields For You Your AI Agent can save information straight into custom fields as it comes up in the conversation — a birthday, a partner's name, a dietary requirement, a table preference — so you can use it later in a broadcast or a follow-up. This is off by default, and it only ever writes into fields you have explicitly picked. Two things have to be in place, and **both** are needed — this is the most common reason people find that nothing was saved: **1. Create the fields first.** The AI can only write into fields that already exist on your account. Add them the normal way (see [Filling In Custom Fields on a Contact](#filling-in-custom-fields-on-a-contact) above) — for example `customer_birthday`, `partner_name`, `dietary_notes`. Remember the naming rules: lowercase letters, numbers and underscores only. **2. Give the Agent permission and pick the fields.** 1. Click **AI Agents** in the sidebar and open the Agent. 2. Go to the **AI abilities** tab. 3. Under **Contact updates**, turn on **Allow AI to collect extra info**. 4. A card titled **Collect extra info during booking** appears, listing your custom fields. Turn on the toggle next to **each** field the AI is allowed to fill in — creating a field is not enough on its own, and any field left off is silently ignored. (If the card says you have no custom fields yet, go back and create them first.) 5. Click **Save**, then **Publish** the Agent. Changes sit in the draft until you publish, so an unpublished change won't affect live conversations. Publishing pushes **every** pending draft change live, not only this one, so glance over the other tabs first if you've been editing. **Good to know:** - **It works throughout the conversation, not only when booking.** Despite the card's wording — bookings are where the feature started — the AI saves a value the moment the contact mentions it, whether or not an appointment is involved. You don't need bookings switched on at all. - **Each field can be marked required.** Required only means "must be collected before the AI confirms an appointment" — it never blocks a normal conversation, and it does nothing on an Agent that doesn't take bookings. - **The AI saying it "noted" something is not the same as saving it.** If the field isn't created and switched on, the AI can still reply politely that it has taken note, but nothing lands on the contact. Check the contact record to confirm a value actually saved. - **Tell the Agent when to ask.** In the Agent's instructions, describe when each field applies ("if the guest mentions an allergy or diet, save it to `dietary_notes`"). The AI reads that in plain language, so it won't interrogate everyone with the same list. - **Nothing is backfilled.** Only conversations from the moment you publish are captured — details already mentioned in past chats are not filled in retroactively. - **Set this up on the account that owns the contacts.** Custom fields belong to a single account, so on an agency setup create them inside the sub-account whose Agent is doing the talking, not on the parent agency account. - **Free-form notes belong in a field too.** The conversational AI cannot write into a contact's **Lead profile / Notes** box (see below) — that one is for you and your team, though [Automations](../automations/automations.md) and the API can write it. If you want the AI itself to record something like "asked for a coeliac dish", make it a custom field such as `dietary_notes`. --- ## What the AI Can Read During a Conversation If you're deciding where a piece of information should live so the AI can **act on it while chatting**, this is the difference that matters: - **Custom fields: the AI reads them on every reply.** All of a contact's custom field values are available to the AI throughout the conversation — however the field was filled in (by you, by the AI earlier, through an import or the API). So a rule in your Agent's instructions like "greet returning customers by their `preferred_barber`" works, because the AI can see the value at that moment. - **Tags: the AI does not see them while chatting.** Tagging runs as a separate step after the AI's reply is sent — the AI applies tags based on your descriptions, but it is not shown which tags a contact already carries during the conversation. Instructions like "if the contact has the VIP tag, offer the discount" will **not** work. The rule of thumb: anything the AI should read and act on mid-conversation goes in a **custom field**. **Tags** are for everything that happens around the conversation — filtering and segmenting contacts, targeting broadcasts, and firing [tag webhooks](../integrations/webhooks.md) into your other systems the moment the AI applies one. --- ## Bulk-Loading Custom Fields The import wizard's column mapping only recognises **first name, last name, phone, email, tags, and notes** — there's no "map this spreadsheet column to a custom field" step (tags, by contrast, do import as real tags). To bulk-load custom field values today, use the API — which route you take depends on whether the contacts already exist. **Adding brand-new contacts?** The API's bulk contact-import endpoint takes custom field values right in the same call, so you don't need a second pass. Include a `custom_fields` object on each record alongside the name, phone and email, and the contacts arrive with their custom fields already filled in. The request format is documented in the Contacts section of the API reference. **Filling in contacts you already have?** 1. List your contacts through the API to get each contact's ID. The CSV export does not include a contact ID column or any custom-field columns. See [API Access](../integrations/api-access.md) for how to get a key and call the endpoint. 2. Fill in the values in your spreadsheet. 3. Use the API's contact-update endpoint (see [API Access](../integrations/api-access.md)) to write them back per contact, since the import wizard itself doesn't have a custom-field column mapping yet. Each update only touches the keys you send — any custom fields you leave out keep their current values. --- ## Notes (= Lead Profile) On a contact's **full record** (click **Open full record** from the quick-view panel), the **Notes** panel is a single free-text box — the same underlying field also referred to as "Lead Profile" elsewhere. In the contact's **Edit** form the very same box is labelled **Lead profile**, described as "Internal notes about this contact", so don't go hunting for a second field. Write anything relevant to the conversation: business type, pain points, company size, recent activity, anything that helps personalise outreach. **How the AI uses it:** in a message template — a broadcast message, a follow-up, an AI Agent's instructions — you can include a placeholder like `{{personal_context|write a one-line opener that references their business}}`. When that template is sent to a specific contact, the AI reads their Notes and writes a personalised line using what's there. If a contact has no Notes, the placeholder is simply removed from the message. The AI does **not** write this for you — you or your team fill it in. Think of it as the cheat sheet you'd want a sales rep to read before picking up the phone. If you want the AI itself to record something it learns in a conversation, use a custom field instead — see [Letting the AI Fill Custom Fields For You](#letting-the-ai-fill-custom-fields-for-you). Editing is straightforward: type in the box, then click **Save note** (or **Discard** to drop unsaved changes). There's no separate title or date per entry — it's one running text block per contact, so if you want a dated log, prefix each addition with the date yourself. --- ## Status Every contact has a **Status** badge showing where they are in their journey: | Status | What it means | |---|---| | **New** | Just came in, not yet engaged. | | **Engaged** | Actively in conversation. | | **Lead** | Showing buying interest. | | **Customer** | Converted. | | **Churned** | Was a customer, no longer active. | | **Spam** | Hidden from your main lists; the AI bot will not engage with them, Do Not Disturb is turned on, and they're excluded from campaigns. | Click the **Status** badge directly in the contacts table to change it inline — for any status except Spam, which you set through the bulk **Mark as spam** action (and its confirmation) since it has those extra side effects. Unmarking spam is available the same way, as **Unmark as spam**. --- ## Assigning a Contact to a Team Member Ownership assignment — giving one teammate a contact so others don't reply by accident — is set from the **Chats** screen rather than the Contacts page: open the conversation and use the assignee control there. See [Chat Interface](../chats/chat-interface.md) for the full walkthrough. Only account owners and users with the right permission can change an assignment. --- ## Using Custom Fields in Broadcasts and Templates Custom fields earn their keep inside outgoing messages. Anywhere you can write a message — broadcast messages, WhatsApp templates, AI Agent instructions — you can drop in a placeholder like: ``` Hey {{first_name}}, hope things are going well at {{company}}! ``` When the message goes out, `{{first_name}}` and `{{company}}` are replaced with the values from each contact. If a contact doesn't have that field filled in, the placeholder is left blank. Some tips: - **Use lowercase, underscore-style names** — the placeholder must match the field name exactly (`{{company}}`, not `{{Company}}`). - **Built-in fields work too** — `{{first_name}}`, `{{last_name}}`, `{{email}}`, and `{{phone_number}}` work without setting them up as custom fields. - **Combine with Notes** — for AI-personalised lines, use `{{personal_context|your instruction}}` instead of a fixed custom field; the AI writes something fresh based on the contact's Notes. - **You can't delete a field that's in use** — if a template uses `{{company}}`, the system blocks deleting `company` until you remove it from those templates. --- ## Need Help? A good rule of thumb for what goes where: - A **short, structured fact you'll filter or merge on** → custom field. - A **paragraph of context for the AI or your team to read** → Notes. - **Who owns the conversation** → the assignee, set from Chats. Still stuck? Reach out to support and we'll help you set it up. --- ## Next Steps - [Adding a New Contact](creating-contacts.md) — add contacts one at a time, plus a full tour of the Contacts screen. - [Importing Contacts from a File](importing-contacts.md) — bring in a spreadsheet. - [Chat Interface](../chats/chat-interface.md) — where contact assignment lives.