Contacts

Attributes: custom fields on your WhatsApp contacts

Declare typed fields on your WhatsApp contacts, such as a last service date, keep their labels in a list, and let automations read and write them.

A repair shop wants to remind Camille of her bike's service a year after the last one. It declares a last_service_at attribute of type date, and every contact of the workspace can then hold a value for it. A sales team would declare lead_status instead.

Which types can an attribute have?

typeHoldsExample
textA text.lead_status: qualified
numberA number.orders_count: 3
booleantrue or false.is_vip: true
dateA date.last_service_at: 2025-11-15
listItems, each at most once.labels: [vip, berlin]

A list attribute holds a contact's labels. Heythere has no separate tags.

An attribute's name and type never change, since automations read it by name. No attribute takes the name of a contact's system field.

How do automations use attributes?

An automation reads an attribute as contact.<attribute>, in a condition, a message, or an AI step's instructions. Its steps write attributes: a question saves the answer, an ai_agent step what it learns, and a set_value step sets, computes, or generates a value, or adds or removes a list item.

An automation uses only attributes the workspace declared, with a type that holds the value. Publishing a version refuses one that does not.

In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. The OpenAPI document describes their parameters, payloads, and errors.

  • POST

    createContactAttribute

    Declare a contact attribute

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contact-attributes
  • GET

    listContactAttributes

    List contact attributes

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contact-attributes