Contacts

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 per number. Her 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 answer in. Everything else the shop knows about Camille lives in her attributes, which a member or their agent edits, and in her consents.

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 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 describes their parameters, payloads, and errors.

  • GET

    listWorkspaceContacts

    List workspace contacts

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts
  • GET

    getContact

    Get a contact

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/{contactId}
  • PATCH

    updateContact

    Update a contact's attributes, consents, and language

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/{contactId}
  • POST

    importContacts

    Import contacts by phone number

    /api/organizations/{organizationId}/workspaces/{workspaceId}/contacts/import