> Every page of the Heythere docs is listed in https://heythere.io/docs/llms.txt: fetch it to find a page instead of guessing its URL.

# Contacts: everyone your WhatsApp number talks to

> Everyone who writes to your WhatsApp numbers becomes a contact. See how Heythere identifies them, which fields it keeps, and what they agreed to.

Camille writes to her repair shop's WhatsApp number for the first time, and Heythere creates her contact: a person reachable on WhatsApp in a workspace. A member or their agent can also import people by phone number before they ever write, such as the shop's customers from its CRM.

If Camille also writes to the shop's second number, she stays one contact, with one [conversation](https://heythere.io/docs/concepts/conversations) per number. Her [attributes](https://heythere.io/docs/concepts/attributes), such as `last_service_at`, are shared by every number of the workspace.

## What identifies a contact?

WhatsApp identifies a person by a user ID, and shares their phone number with it, except for some people, such as those who write with a username. A contact therefore has a WhatsApp user ID, a phone number, or both, and each belongs to at most one contact of a workspace. An imported contact gets its user ID when the person first writes. If WhatsApp gives Camille a new user ID, her contact keeps its conversations.

## Which fields does Heythere keep on a contact?

Heythere alone writes a contact's system fields, like `profileName`, `username`, and `lastInboundAt`, from what WhatsApp shares. An automation or `updateContact` sets its `language`, which [automations](https://heythere.io/docs/concepts/automations#how-does-an-automation-answer-in-several-languages-) answer in. Everything else the shop knows about Camille lives in her [attributes](https://heythere.io/docs/concepts/attributes), which a member or their agent edits, and in her consents.

## What does a contact consent to?

Camille's `marketing` consent covers promotions, such as a service offer a year after her last repair. Her `utility` consent covers updates about an order or account, such as her bike being ready. Each is `unknown` until a decision is recorded, then `granted` or `withdrawn`, with when and by what, and never `unknown` again.

Members or agents record one with `updateContact` or `importContacts`, and an automation with a [`set_value` step](https://heythere.io/docs/concepts/steps) setting `contact.marketingConsent` or `contact.utilityConsent`. If Camille stops the shop's marketing messages in WhatsApp, her `marketing` consent is withdrawn, and resuming grants it again. Until she resumes, WhatsApp refuses her every `marketing` template, whatever her consent.

## In the API

Every operation is a REST endpoint and, unless marked REST only, an MCP tool of the same name. [The OpenAPI document](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors.


- `listWorkspaceContacts`: List workspace contacts. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts`
- `getContact`: Get a contact. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/{contactId}`
- `updateContact`: Update a contact's attributes, consents, and language. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/{contactId}`
- `importContacts`: Import contacts by phone number. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/import`
