# Organizations and workspaces: your team and your brands > Group your people and your brands, and decide who sees what: an administrator sees every workspace, a member only the ones it was given. An agency runs WhatsApp for twelve shops: one organization, with a workspace for each shop. A workspace holds one [WhatsApp connection](https://heythere.io/docs/concepts/whatsapp-connection) with its [contacts](https://heythere.io/docs/concepts/contacts), [conversations](https://heythere.io/docs/concepts/conversations), [message templates](https://heythere.io/docs/concepts/message-templates), and [automations](https://heythere.io/docs/concepts/automations). Karim, who owns the garage, wants to answer his own customers, without seeing the customers of the eleven other shops. ## Who sees which workspace? A member's access is `admin` or `member`: - An administrator of the organization administers every workspace. Its creator becomes the first one, and it always keeps one. - A member works only in the workspaces it was given, with the role `admin` or `member` in each. Karim gets the garage's workspace, and nothing else reaches him: not the other shops' contacts, conversations, or notifications, nor the organization's members. A freelancer handling two shops gets those two. ## What does an administrator do that a member cannot? In a workspace, only its administrators connect WhatsApp, send a [broadcast](https://heythere.io/docs/concepts/broadcasts), and publish an automation [version](https://heythere.io/docs/concepts/versions), since these message contacts. Every member works with its contacts, conversations, templates, and automations, and `listWorkspaceMembers` shows who else does. Only an administrator of the organization renames or deletes it, manages its workspaces, invites people, reads its [usage](https://heythere.io/docs/concepts/usage), and changes what each member works in with `updateOrganizationMemberAccess`. ## How does a person join an organization? An administrator invites their phone number, as an administrator or into chosen workspaces. Heythere sends no message, so tell Karim to sign in to Heythere with that number within 7 days, and he joins with the invited access. ## What does a workspace's map show? Every WhatsApp number of the workspace, each with its [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-), the events it starts at, and its latest [broadcasts](https://heythere.io/docs/concepts/broadcasts), with how far each went. The console shows it on the automations page, and `getWorkspaceMap` returns it to an agent. ## How does an agent choose an organization and a workspace? An agent or [API key](https://heythere.io/docs/concepts/api-access) acts as its user, and sees what that user sees. `listOrganizations` and then `listOrganizationWorkspaces` give the IDs that every other operation names in its path. Deleting a workspace or an organization is permanent: it erases their contacts, conversations, messages, and automations. ## 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. - `createOrganization`: Create an organization. `POST /api/organizations` - `listOrganizations`: List joined organizations. `GET /api/organizations` - `getOrganization`: Get an organization. `GET /api/organizations/{organizationId}` - `updateOrganization`: Update an organization. `PATCH /api/organizations/{organizationId}` - `deleteOrganization`: Delete an organization. `DELETE /api/organizations/{organizationId}` - `listOrganizationMembers`: List organization members. `GET /api/organizations/{organizationId}/members` - `updateOrganizationMemberAccess`: Replace what an organization member works in. `PUT /api/organizations/{organizationId}/members/{memberId}/access` - `removeOrganizationMember`: Remove an organization member. `DELETE /api/organizations/{organizationId}/members/{memberId}` - `inviteOrganizationMember`: Invite an organization member. `POST /api/organizations/{organizationId}/invitations` - `listOrganizationInvitations`: List organization invitations. `GET /api/organizations/{organizationId}/invitations` - `getOrganizationInvitation`: Get an organization invitation. `GET /api/organizations/{organizationId}/invitations/{invitationId}` - `revokeOrganizationInvitation`: Revoke an organization invitation. `DELETE /api/organizations/{organizationId}/invitations/{invitationId}` - `listReceivedOrganizationInvitations`: List received organization invitations. `GET /api/organization-invitations` - `acceptOrganizationInvitation`: Accept an organization invitation. `POST /api/organization-invitations/{invitationId}/acceptance` - `declineOrganizationInvitation`: Decline an organization invitation. `DELETE /api/organization-invitations/{invitationId}` - `createWorkspace`: Create a workspace. `POST /api/organizations/{organizationId}/workspaces` - `listOrganizationWorkspaces`: List organization workspaces. `GET /api/organizations/{organizationId}/workspaces` - `getWorkspace`: Get a workspace. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}` - `listWorkspaceMembers`: List the people who work in a workspace. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/members` - `renameWorkspace`: Rename a workspace. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}` - `deleteWorkspace`: Delete a workspace. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}` - `getWorkspaceMap`: Get the workspace map. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/map` # Usage: see what each workspace consumes on WhatsApp > Read how many WhatsApp conversations and how much AI each workspace of your organization used in a month, to bill each of your clients for it. Studio Nord, an agency, builds WhatsApp automations for its clients, with one workspace for each in its [organization](https://heythere.io/docs/concepts/organizations-and-workspaces): the repair shop where Camille takes her bike, a bakery, a florist. In December, it bills each client for what their workspace used in November. Usage counts two things for each workspace: its billed conversations and what its AI cost. ## What is a billed conversation? One starts when WhatsApp reports the first message delivered to a contact, and covers the messages delivered to that contact on that number for 24 hours, up to 50. When the shop tells Camille at 10 a.m. that her bike is ready, then answers her questions until noon, that is one billed conversation. A message delivered the next day at 11 a.m., or the 51st of the day, starts another. Only messages that reach the contact count. A message that ends `failed` is never billed, and neither are the contact's own messages nor a [test](https://heythere.io/docs/concepts/tests), which messages only a member's own phone. ## What does AI cost? Every request a workspace's [AI](https://heythere.io/docs/concepts/ai) makes, in its automations and in its tests, in US dollars, at the AI provider's listed prices. The [workspace log](https://heythere.io/docs/concepts/workspace-log) shows each request with its cost. ## How does an agent read usage? Only an administrator of the organization reads it. `getOrganizationUsage` gives its totals for a period, such as November, from `2026-11-01T00:00:00Z` to `2026-12-01T00:00:00Z`, and `listOrganizationWorkspaceUsage` gives each workspace's share, which Studio Nord bills to that client. WhatsApp can report a delivery up to 7 days late, so Studio Nord reads November once December 7 has passed. A deleted workspace keeps its usage, without its name. Heythere keeps usage 13 months. ## 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. - `getOrganizationUsage`: Get an organization's usage. `GET /api/organizations/{organizationId}/usage` - `listOrganizationWorkspaceUsage`: List each workspace's usage. `GET /api/organizations/{organizationId}/usage/workspaces` # API access: connect your AI agent to Heythere's API > Let an agent or one of your services call Heythere's API as you, with a token you approve or a key you create, and take that access back anytime. An online shop's owner wants Claude to write the Ember jacket news, and the shop's CRM to read its contacts. Both call Heythere's API as the owner, in every organization the owner belongs to, each with its own credential: - An **access token**, which an agent obtains once you approve it. The agent connects over MCP or REST, and the [API llms.txt](https://app.heythere.io/api/llms.txt) explains how. It lists every operation, and the agent reads the contract of the one it needs with `getApiOperation`, small enough to fit its context. - An **API key**, which you create in the console, on the API access page, for a service of yours that calls the REST API, such as that CRM. Both go in the `Authorization: Bearer` header and act as you, with your role in each organization. Only you create an API key, from a signed-in browser. An agent never obtains one. ## How do I create and store an API key? Name the key after the service that uses it, and choose when it expires: after 30 days, 90 days, a year, or never. Heythere shows the key only once, at creation, so store it in your service's secrets right away. Afterwards, the console shows only its last four characters and when it was last used. ## How do I take access back? The API access page lists your API keys and the agents connected as you. Revoke a key, or disconnect an agent, and every later request with its credential is rejected with a 401. Each user holds at most 20 API keys and 20 connected agents. ## 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. - `getApiOperation`: Get the contract of one operation. `GET /api/operations/{operationName}` - `getApiSchema`: Get one schema of the API. `GET /api/schemas/{schemaName}` # Variables: shared values such as your address or hours > Store values every automation reads, such as your shop's address or opening hours, and change one without publishing your automations again. When the repair shop moves, every message telling Camille where to pick up her bike must give the new address. The shop keeps that address once, as a variable, a value a workspace keeps for all its [automations](https://heythere.io/docs/concepts/automations). A [step](https://heythere.io/docs/concepts/steps) reads a variable named `shop_address` as `{{workspace.shop_address}}` in a message, and as `workspace.shop_address` in a condition or an expression. ## What happens when its value changes? A run reads the value its step finds when it reaches it. The shop saves its new address once, and every published automation gives it from its next step on, with no new [version](https://heythere.io/docs/concepts/versions). ## Who saves a variable? A workspace member, or their agent, with `saveWorkspaceVariable`. A variable keeps the type it was first saved with, like an [attribute](https://heythere.io/docs/concepts/attributes): text, number, boolean, date, list, or schedule. It is never deleted, so a published automation always reads a value of the type it expects. Saving an existing name replaces its value. ## How does an automation read opening hours? Camille writes on Saturday evening, after the shop has closed. A schedule holds weekly slots in one time zone, and dates closed or on special hours. A condition on `workspace.opening_hours.isOpen` tells whether the shop is open, and `{{workspace.opening_hours.nextOpening}}` tells Camille when it opens next, in the language the automation answers in, such as `Tuesday, November 17 at 9:00 AM`. A `wait` step of type `opening` holds her run until the shop opens, from Saturday evening to Tuesday morning. ## Is a variable secret? No. The [workspace log](https://heythere.io/docs/concepts/workspace-log) shows the values runs read, so keep credentials in [secrets](https://heythere.io/docs/concepts/secrets). ## What happens when a variable is missing? Publishing or testing a draft that reads a variable the workspace does not keep fails, naming the step and the variable. ## 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. - `saveWorkspaceVariable`: Save a workspace variable. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/variables/{name}` - `listWorkspaceVariables`: List workspace variables. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/variables` # Secrets: store the API keys your automations send > Keep the API keys your automations send to other services, such as a CRM token, without any step or agent ever reading them back. The repair shop's automation sends each new booking to its CRM, and the CRM asks for an API key. That key is a secret, a credential a workspace keeps for its [automations](https://heythere.io/docs/concepts/automations). An `http_request` [step](https://heythere.io/docs/concepts/steps) reads a secret named `crm_token` as `{{secret.crm_token}}`, so the key never appears in the automation, its versions, or the [workspace log](https://heythere.io/docs/concepts/workspace-log). A [webhook source](https://heythere.io/docs/concepts/webhook-sources) checks the requests it receives with a secret too. ## Who saves a secret? A workspace member, on the workspace's Secrets page in the console. Saving an existing name replaces its value. A secret is only a name and a value, and Heythere keeps the value encrypted and never shows it again, even to an agent. ## What does an agent see? Only the names, with `listWorkspaceSecrets`. `getAutomation` and `replaceAutomationDraft` also return `missingSecrets`, the secrets the draft reads that the workspace lacks, with one console link that saves them all. The agent gives that link and explains in its own words where to find each value, instead of asking for values in chat. ## What happens when a secret is missing? Publishing or testing a draft that reads it fails with a conflict carrying the same link. A step reading a deleted secret sends nothing. It takes its `onError`, or fails the [run](https://heythere.io/docs/concepts/runs). ## 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. - `listWorkspaceSecrets`: List workspace secrets. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/secrets` # MCP servers: let an AI step use your help center or shop > Let an AI agent step search your help center or read an order through a service's MCP server, once a member connects it for the workspace. A customer asks the online shop "Where is my Ember jacket?", and its AI agent step needs the order to answer. An MCP server is a service's endpoint, such as `https://mcp.notion.com/mcp`, that offers tools to AI models, such as searching a knowledge base or reading an order. An `ai_agent` [step](https://heythere.io/docs/concepts/steps) can call the tools of a remote server, as it calls `http_request` tools. Heythere itself calls the server, whatever the step's [AI](https://heythere.io/docs/concepts/ai) provider, so every call appears in the [workspace log](https://heythere.io/docs/concepts/workspace-log) and a tool declared as `writes` is never called twice for the same inputs. ## How does a step use a server? `listMcpServerTools` lists what a server offers. The step enables only the tools it needs, each an `mcp` tool naming the server's URL, the tool, and its input schema. The [version](https://heythere.io/docs/concepts/versions) a member publishes keeps that description. When the server later changes a tool, the step still calls it, and the log notes the change. ## Who connects a server? A server either needs no sign-in, or reads a token. The token comes from headers that read a [secret](https://heythere.io/docs/concepts/secrets), or from a connection a member makes once for the workspace by signing in to the service, on the MCP servers page of the console. The connection acts as that member's account at the service, stays when they leave the workspace, and is deleted on the same page. An agent never sees its tokens, only `listMcpServerConnections`. ## What happens when a server is not connected? `getAutomation` and `replaceAutomationDraft` return `missingMcpServerConnections`, with one console link connecting them all, which the agent gives the member. Testing or publishing such a draft fails with a conflict carrying the same link, and the Test pop-over offers to connect each server. A step whose connection was deleted, or whose server refused its tokens for good, tells its model the business has not connected the server, until a member connects it again. ## 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. - `listMcpServerTools`: List an MCP server's tools. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/mcp-server-tools` - `listMcpServerConnections`: List MCP server connections. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/mcp-server-connections` # WhatsApp connection: link your WhatsApp Business Account > Connect your WhatsApp Business Account and up to 20 of its numbers through Meta's signup, and know what stops a number from sending. Before the online shop can tell its customers that the Ember jacket ships late, it connects its WhatsApp number to Heythere. A workspace's WhatsApp connection links one WhatsApp Business Account, and up to 20 of its phone numbers, to the workspace. Every message the workspace sends or receives goes through it. Meta requires a person of the business to approve the connection in a browser, through Meta's Embedded Signup. An agent starts the connection, and an [administrator](https://heythere.io/docs/concepts/organizations-and-workspaces) of the workspace completes it. ## How does an agent connect a WhatsApp number? 1. Create a connection request with `createWhatsAppConnectionRequest`. Its `url` opens the Heythere console and stays valid for 1 hour. 2. Give the URL to an administrator, and ask them to say when they are done. 3. The administrator selects Connect with WhatsApp, and picks the business account and the phone number in Meta's window. 4. Read the connection with `getWhatsAppConnection` until its `status` is `active`. Connecting another number of the same business account takes a new connection request. A business account and each of its numbers belong to one workspace at a time. ## What stops a connection from sending? | `status` | Meaning | | ----------------- | ------------------------------------------------------------------------------------------ | | `active` | Every number sends and receives messages. | | `action_required` | A number needs an administrator, as its `registrationState` says. The others keep sending. | | `restricted` | Meta stopped the business account from sending, as its `standing` says. | | `access_revoked` | Heythere lost access to the business account: connect again. | | `disconnecting` | An administrator disconnected the workspace. | Most problems with a number end the same way: an administrator reconnects it through a new connection request. A restriction from Meta lifts only on Meta's side, in Meta Business Support Home. ## What does disconnecting remove? Disconnecting stops the workspace's numbers from sending and receiving, and removes the connection's numbers, message templates, and media from Heythere. The templates stay in the business account at Meta, and come back when the workspace connects it again. ## 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. - `createWhatsAppConnectionRequest`: Create a WhatsApp connection link. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests` - `getWhatsAppConnectionRequest`: Get WhatsApp connection request status. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection-requests/{connectionRequestId}` - `getWhatsAppConnection`: Get the workspace WhatsApp connection. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection` - `disconnectWhatsAppConnection`: Disconnect the workspace WhatsApp connection. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/connection` - `createWhatsAppMedia` (REST only): Upload a WhatsApp media. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/media` # Workspace log: find out why a customer got no reply > Find out why a customer got no reply, why a run took a branch, or why WhatsApp refused a message, from 30 days of what Heythere did. A customer of the online shop says they never got the Ember jacket news, and the shop asks its agent why. The agent reads the workspace log, which records what Heythere did and received for a workspace, so it can explain what happened to a contact: why a message started no automation, why a run took a branch, or why WhatsApp refused a message. Heythere keeps each entry 30 days. ## What does the log record? Every entry concerns one [contact](https://heythere.io/docs/concepts/contacts), and the [conversation](https://heythere.io/docs/concepts/conversations) and [run](https://heythere.io/docs/concepts/runs) it is about, if any: - **Exchanges with WhatsApp:** what Heythere asked WhatsApp, and what WhatsApp answered or notified, with WhatsApp's error codes. - **Exchanges with the AI provider:** what an [AI](https://heythere.io/docs/concepts/ai) model was asked, what it answered, and what it cost. - **HTTP requests:** what an `http_request` step sent, secrets left as placeholders, and what it received. - **Routing:** where each message went and why, such as `automation_unpublished` before its [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-) is published. - **Billed conversations:** the delivered message that started each [billed conversation](https://heythere.io/docs/concepts/usage#what-is-a-billed-conversation-). - **Run decisions:** what each run sent, how it judged each reply, the values it wrote, the branch or exit it took, and why it ended. - **Internal errors:** an unexpected failure of Heythere. ## How does an agent read the log? Start from the narrowest ID, here the customer's contact. `listWorkspaceLog` narrows the log to one contact, conversation, run, or message, to some kinds of entries, or to a window of time. When the log shows an error it does not explain, such as an internal error, file a [bug report](https://heythere.io/docs/concepts/bug-reports) that names the entry's `traceId`. ## 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. - `listWorkspaceLog`: List the workspace log. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/log` # Bug reports: let your agent report what Heythere got wrong > When your agent finds something Heythere got wrong, it files a bug report for the team, naming a trace or resource ID, never personal data. You ask your agent why Camille got no answer, and it finds an internal error in the [workspace log](https://heythere.io/docs/concepts/workspace-log) for her run. That is a bug, and the agent tells Heythere's team with a bug report. It files the report for the user who connected it, and only that user reads it, through any of their agents. ## When is it a bug? File a bug report when Heythere contradicts these pages or the [OpenAPI document](https://app.heythere.io/api/openapi.json), an operation answers 500 or keeps answering 5xx, an error's next step cannot be done, or the workspace log holds an internal error. A behavior these pages omit is no bug, nor is a missing feature. ## What must a report name? At least one `traceId` or resource ID, since the team reads the workspace log itself. Never put an access token, a secret, or a contact's personal data in a report, such as a phone number or what they wrote. Name the message or the conversation instead. Check `listBugReports` first, so a bug is not reported twice, and tell the user in one sentence which bug you reported. ## 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. - `createBugReport`: Report a bug. `POST /api/bug-reports` - `getBugReport`: Get a bug report. `GET /api/bug-reports/{bugReportId}` - `listBugReports`: List bug reports. `GET /api/bug-reports` # 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` # 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](https://heythere.io/docs/concepts/contacts) of the workspace can then hold a value for it. A sales team would declare `lead_status` instead. ## Which types can an attribute have? | `type` | Holds | Example | | --------- | ------------------------- | ----------------------------- | | `text` | A text. | `lead_status: qualified` | | `number` | A number. | `orders_count: 3` | | `boolean` | `true` or `false`. | `is_vip: true` | | `date` | A date. | `last_service_at: 2025-11-15` | | `list` | Items, 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.`, in a [condition](https://heythere.io/docs/concepts/steps), a message, or an AI step's instructions. Its [steps](https://heythere.io/docs/concepts/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](https://heythere.io/docs/concepts/versions) 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](https://app.heythere.io/api/openapi.json) describes their parameters, payloads, and errors. - `createContactAttribute`: Declare a contact attribute. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/contact-attributes` - `listContactAttributes`: List contact attributes. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/contact-attributes` # Audiences: pick which customers a broadcast reaches > Pick which customers a broadcast reaches, such as your VIP customers in Lyon, with up to 20 conditions on their fields. An online shop wants its winter sale to reach only its VIP customers in Lyon. An audience narrows a [broadcast](https://heythere.io/docs/concepts/broadcasts) that way. It holds 1 to 20 conditions, and matches a contact when all of them hold. ```json [ { "field": "contact.labels", "operator": "contains", "value": "vip" }, { "field": "contact.city", "operator": "equals", "value": "Lyon" } ] ``` A condition reads `contact.`, an [attribute](https://heythere.io/docs/concepts/attributes) or a system field of the contact. It compares the field with one value or several, ignoring case and accents in texts. It can also compare a number or a date, test whether a text or list contains a value, or test whether the field holds a value. A [`condition` step](https://heythere.io/docs/concepts/steps) uses the same conditions, and reads the run and the trigger too. # Conversations: the WhatsApp 24-hour reply window > One thread per customer and WhatsApp number. Learn when the 24-hour reply window closes, where replies go, and how each message's delivery is tracked. Every message between Camille and her repair shop's WhatsApp number sits in one conversation, between one [contact](https://heythere.io/docs/concepts/contacts) and one number of the workspace. Heythere creates it when the contact first writes there or a [broadcast](https://heythere.io/docs/concepts/broadcasts) first messages them. A message is `inbound` when the contact sent it, and `outbound` when an [automation run](https://heythere.io/docs/concepts/runs), a broadcast, a member, or a [verification](https://heythere.io/docs/concepts/verifications) sent it, whose code never shows. ## When does a conversation's reply window close? WhatsApp lets a business send any message for 24 hours after the contact's latest message, until `replyWindowClosesAt`. If Camille last wrote at 10 a.m. on Monday, the shop answers freely until 10 a.m. on Tuesday. After that, it sends only a [message template](https://heythere.io/docs/concepts/message-templates) Meta approved. ## Which messages does a contact send? Texts, images, videos, documents, audio, voice notes, places, contact cards, the reply button or list row they tapped, and reactions. Any other message, such as a sticker, is `unsupported`. An automation reads Camille's voice note through its `transcript`, which [AI](https://heythere.io/docs/concepts/ai) writes, unless its `transcribesVoiceNotes` is false. ## Where does an inbound message go? To the members during a [live chat](https://heythere.io/docs/concepts/live-chats) or after a handover. Otherwise to the conversation's active [run](https://heythere.io/docs/concepts/runs), which reads it only while waiting for a reply. Without an active run, it starts the number's published [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-). A reaction never starts or continues a run. ## How does Heythere send a message? When the shop tells Camille her bike is ready, the message's `state` starts at `sending`, then follows WhatsApp's reports, up to `read`. A message that never reaches her ends `failed`, with a `reason`, such as `reply_window_closed` when it needed a template. ## 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. - `listWorkspaceConversations`: List workspace conversations. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations` - `listConversationMessages`: List conversation messages. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/messages` - `watchWorkspaceConversations` (REST only): Watch workspace conversations. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/conversation-changes` - `getMessageMedia` (REST only): Get message media. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/messages/{messageId}/media` # Live chats: answer WhatsApp customers yourself > Answer a customer yourself, from the Heythere app or the API, when an automation hands you the conversation or whenever you choose, then hand it back. Camille asks her repair shop whether they can also fix her gears, a question the shop's automation leaves to a person. A live chat is the workspace's members answering a [contact](https://heythere.io/docs/concepts/contacts) themselves in a [conversation](https://heythere.io/docs/concepts/conversations), from the Heythere app or the API. While it lasts, the contact's messages go to the members and start no [run](https://heythere.io/docs/concepts/runs). ## How does a live chat start? With a member's first message to the contact, sent with `sendConversationMessage`. It cancels the conversation's active run. An automation asks for one with a `handover` [step](https://heythere.io/docs/concepts/steps): its run ends `handed_over`, and the conversation awaits a member. Until one writes, Camille's messages start no run, and the conversation shows its `handover`. ## Who is notified? The Heythere iPhone app notifies the workspace's members of a handover, then the member who started the live chat of each message the contact sends. ## What can members send? Text, while the conversation's reply window is open: WhatsApp refuses any other message outside it. `showConversationTyping` shows Camille that a member is typing. ## How does a member hand the contact to an automation? With `startAutomationRun`, such as when Camille asks to join the waitlist for the next repair slot. The [automation of the conversation's number](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-) runs as if its `message.received` trigger had received her latest message. `getConversationAutomation` says whether it can start. ## When does a live chat end? When a member ends it with `endLiveChat` or starts an automation, or when the reply window closes, 24 hours after the contact's latest message. The contact's next message then goes to the number's automation again, as does every message once a handover's reply window closes without a member answering. ## 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. - `sendConversationMessage`: Send conversation message. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/messages` - `showConversationTyping`: Show conversation typing. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/typing` - `endLiveChat`: End live chat. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/live-chats/{liveChatId}/end` - `startAutomationRun`: Start automation run. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/automation/runs` - `getConversationAutomation`: Get the conversation's automation. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/conversations/{conversationId}/automation` # Message templates: get WhatsApp templates approved by Meta > Create the WhatsApp templates Meta must approve before you message a customer after 24 hours, follow their review, and send them from an automation. Camille last wrote to her repair shop two days ago, so the shop can no longer message her freely. To tell her the bike is ready, it sends a message template: a message Meta reviews before a business sends it outside a [conversation's reply window](https://heythere.io/docs/concepts/conversations#when-does-a-conversation-s-reply-window-close-). A workspace's templates are those of the business account its [WhatsApp connection](https://heythere.io/docs/concepts/whatsapp-connection) links. Heythere submits the templates it creates to Meta, and keeps every template of the account in sync, including those created in Meta's tools. ## What does a review state mean? | `reviewState` | Meaning | | ---------------- | -------------------------------------------------------------------- | | `pending_review` | Meta is reviewing the template. | | `approved` | The template can be sent. | | `rejected` | Meta refused the template; `reason` says why. | | `paused` | Meta paused the template because of its quality rating. | | `disabled` | Meta disabled the template. | | `in_appeal` | Meta is reviewing an appeal of its rejection. | | `archived` | Meta archived the unused template; unarchive it in WhatsApp Manager. | | `unrecognized` | Meta reports a state Heythere does not know yet. | ## Which rules does a template follow? - A `name` is unique per language in the business account, and a template's `name` and `language` never change. - A `category` is `marketing`, `utility`, or `authentication`, and Meta may move a template between `marketing` and `utility`. - A variable is written `{{name}}`, such as `{{order_number}}`, and needs an example for Meta's review. - A `standard` template has an optional header, a body, an optional footer, and buttons. A `carousel` template has a body and cards. An `authentication` template sends a one-time code. A template can be edited while it is `approved`, `rejected`, or `paused`, and Meta limits how often an approved template changes. ## How does an automation send a template? A `send_template` step names an `approved` template and gives each of its variables a value, such as `{{run.first_name}}`, and sends even after the reply window closed. A template it cannot send, such as one with a media header, fails the [run](https://heythere.io/docs/concepts/runs). ## 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. - `createWhatsAppMessageTemplate`: Create a WhatsApp message template. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/message-templates` - `listWhatsAppMessageTemplates`: List WhatsApp message templates. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/message-templates` - `getWhatsAppMessageTemplate`: Get a WhatsApp message template. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/message-templates/{messageTemplateId}` - `updateWhatsAppMessageTemplate`: Update a WhatsApp message template. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/message-templates/{messageTemplateId}` - `deleteWhatsAppMessageTemplate`: Delete a WhatsApp message template. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/whatsapp/message-templates/{messageTemplateId}` # Broadcasts: send a WhatsApp message to many customers > Send one approved WhatsApp template to many customers, now or at a time you pick, skip those who did not agree to it, and follow each message. A shop needs to tell everyone who pre-ordered its Ember jacket that it ships two weeks late. That is a broadcast: one approved `marketing` or `utility` [message template](https://heythere.io/docs/concepts/message-templates), sent from one of the workspace's WhatsApp numbers to its [contacts](https://heythere.io/docs/concepts/contacts). An optional [audience](https://heythere.io/docs/concepts/audiences) narrows those contacts with conditions on `contact.`, such as the customers whose `preorder` is `ember_jacket`. Each value of the template can read the contact, so `Hello {{contact.first_name}}` greets each customer by name. ## How does a broadcast go out? A member writes it as a `draft`, which they can still change or delete. An administrator sends it. Heythere picks the recipients at that moment, and the broadcast stays `sending` until each one is handled, then becomes `completed`. Cancel it while it is `sending`, and the recipients not messaged yet end `not_sent`. Each message lands in the customer's [conversation](https://heythere.io/docs/concepts/conversations), which it opens if they never wrote to that number. Their reply goes to the run waiting for it, or else to the number's [automation](https://heythere.io/docs/concepts/triggers#which-automation-answers-a-number-). ## Can a broadcast go out later? To land the news on Monday morning, an administrator schedules the draft: it stays `scheduled`, with that time on its number's card in the [workspace map](https://heythere.io/docs/concepts/organizations-and-workspaces#what-does-a-workspace-s-map-show-), then sends by itself. Until then they can move it, send it now, or unschedule it to edit it. If its template stops being sendable first, it sends nothing and returns to a draft whose `missedSchedule` says why. ## Which contacts does a broadcast skip? A customer who never agreed to marketing messages does not get the jacket news. `listBroadcastRecipients` gives each recipient's `status` and, when skipped, its `skipReason`: - `marketing_consent_missing`: the template is `marketing` and the contact's `marketing` [consent](https://heythere.io/docs/concepts/contacts#what-does-a-contact-consent-to-) is not `granted`. - `utility_consent_withdrawn`: the template is `utility` and the contact withdrew its `utility` consent. - `template_value_missing`: a value of the template reads a field the contact does not hold. Meta can change a template's category, so Heythere checks consent again just before each message, against the category the template has then. A recipient ends `failed`, with a `failureReason`, when its message never reaches them or the template stops being sendable first. ## Why does a broadcast take a while? Meta limits how many contacts a number can message each day. When the shop's number reaches that limit, the broadcast pauses, stays `sending`, and goes on once Meta allows more messages. ## 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. - `createBroadcast`: Create a broadcast draft. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts` - `listWorkspaceBroadcasts`: List workspace broadcasts. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts` - `getBroadcast`: Get a broadcast. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}` - `updateBroadcast`: Update a broadcast draft. `PATCH /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}` - `deleteBroadcast`: Delete a broadcast draft. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}` - `sendBroadcast`: Send a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/send` - `scheduleBroadcast`: Schedule a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/schedule` - `unscheduleBroadcast`: Unschedule a broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/unschedule` - `cancelBroadcast`: Cancel a sending broadcast. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/cancel` - `listBroadcastRecipients`: List a broadcast's recipients. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/broadcasts/{broadcastId}/recipients` # Verifications: send one-time codes on WhatsApp > Prove that a customer holds a phone number by sending a one-time code on WhatsApp from your own number, then checking the code they type. Before Camille books a repair on her repair shop's website, the site needs to know that the number she typed is hers. It asks Heythere to start a verification: Heythere sends a six-digit code to Camille on WhatsApp, from the shop's own number, and the site checks the code she types. The shop needs no other provider for its codes. `startVerification` takes the sending number, Camille's number, a `purpose`, and the `language` of the message. The purpose says why she receives a code: `sign_in`, `sign_up`, or `action_confirmation`, such as confirming a payment. `checkVerificationCode` then answers `approved`, `incorrect` with the attempts left, `expired`, or `too_many_attempts`. ## What does Camille receive? A WhatsApp message with her code and a button to copy it, sent through an authentication [message template](https://heythere.io/docs/concepts/message-templates) that Heythere creates on the shop's business account the first time it needs one. In Heythere, her [conversation](https://heythere.io/docs/concepts/conversations) with the shop shows a `verification_code` message with its purpose and its delivery, never the code: Heythere keeps only a fingerprint of it. When Camille never wrote to the shop, she becomes a [contact](https://heythere.io/docs/concepts/contacts) known by her phone number. ## How long does a code work? A code works for 10 minutes and takes 5 attempts. Starting a new verification of the same number and purpose replaces the pending one, so only the newer code works. Heythere refuses a code sent too soon after another, or too many codes to one number, one workspace, or one country, which keeps someone from flooding Camille with codes. ## What does a code cost? A delivered code counts in a [billed conversation](https://heythere.io/docs/concepts/usage#what-is-a-billed-conversation-) like any other message. A code WhatsApp never delivers is never billed. ## Where to look when a code does not arrive? `getVerification` shows how far WhatsApp carried the code, and why it failed when it did, such as a number that is not on WhatsApp. When WhatsApp refuses the code outright, `startVerification` answers with that reason at once. ## 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. - `startVerification`: Send a one-time verification code on WhatsApp. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications` - `checkVerificationCode`: Check a verification code. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}/check` - `getVerification`: Get a verification. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/verifications/{verificationId}` # Automations: automate replies on your WhatsApp number > Decide what your WhatsApp number does when a customer writes. Your agent drafts the steps, you review them in the console, an administrator publishes. When Camille writes to her repair shop's WhatsApp number, the shop's automation asks her name, checks whether her bike is ready, and hands her to the team when she asks for a person. An automation is a graph that messages a [contact](https://heythere.io/docs/concepts/contacts) and reacts to their replies. Each WhatsApp number the workspace connects has one. The shop's manager describes what they want to their agent, the agent writes the graph, and the manager reviews it in the console, beside its number, before anything reaches a customer. ## What makes a graph? - **[Triggers](https://heythere.io/docs/concepts/triggers)** are its entry points: `message.received` starts a run when a contact writes to the automation's number, at the step it leads to. - **[Steps](https://heythere.io/docs/concepts/steps)** send messages, ask questions, use [AI](https://heythere.io/docs/concepts/ai), wait, and write values. - **Transitions** lead from a trigger or a step to the next step. Each reply button or list row has its own. Every trigger and step has an ID its author chooses, such as `ask_name`, unique within the graph. A graph has at most 20 triggers and 100 steps, and no transition leads back to an earlier step. ## How does an automation reach contacts? 1. Connecting a number gives it an empty automation, whose draft a member or their agent writes. 2. They save the draft as a [version](https://heythere.io/docs/concepts/versions), with a message saying what changed. 3. An administrator publishes that version. 4. A contact who writes to that number starts a [run](https://heythere.io/docs/concepts/runs): one contact going through that version. ## How does an agent write a draft? `replaceAutomationDraft` writes the whole draft at once, in the shape `getAutomation` returns. Read the draft before replacing it, since a member may have changed it meanwhile, and build it over a few replacements, so a watching member sees it take shape. Saving refuses a draft that breaks a drafting rule, such as a step no trigger reaches. A saved draft may still hold what publishing would refuse, listed as `draftProblems`, which the console page shows on their nodes. Its `templatePreviews` hold what a contact reads of each [template](https://heythere.io/docs/concepts/message-templates) a `send_template` step sends. ## How does an automation answer in several languages? An automation that lists its `languages`, such as `["en", "fr"]`, answers each [contact](https://heythere.io/docs/concepts/contacts) in their `language` when it offers it, and in its first language otherwise. Each text a contact reads is then either one text for every language, such as a link, or one per language, such as `{ "en": "Hi!", "fr": "Bonjour !" }`. A `send_template` step names its template's language and variables once or per language. The steps, buttons, and transitions stay the same in every language. Publishing refuses a text missing one of the automation's languages. Heythere does not guess a contact's language. A `classify` step that tells it from their first message, or a question that asks it, leads to a `set_value` step that sets `contact.language`, and the following steps answer in it. The console shows the texts in the language picked in the canvas corner. ## 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. - `getAutomation`: Get an automation. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}` - `replaceAutomationDraft`: Replace an automation's draft. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/draft` - `watchAutomation` (REST only): Watch an automation. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/changes` # Triggers: start a WhatsApp automation at the right moment > Start an automation when a customer writes, when your software changes one of their fields, when a date of theirs comes, or when another service sends an event. Camille's repair shop writes to her at three moments: when she messages its WhatsApp number, when its software marks her bike ready, and a year after her last service. Each moment is a trigger, an entry point of an [automation](https://heythere.io/docs/concepts/automations)'s graph that starts a [run](https://heythere.io/docs/concepts/runs) at the step it leads to. Its triggers listen to the WhatsApp number the automation answers, and publishing a [version](https://heythere.io/docs/concepts/versions) activates them. None starts a run while an active run, a [live chat](https://heythere.io/docs/concepts/live-chats), or a handover holds the conversation. A `message.received` trigger starts a run when a contact writes to that number in its conversation. Since the contact just wrote, the run starts inside the conversation's [reply window](https://heythere.io/docs/concepts/conversations#when-does-a-conversation-s-reply-window-close-), and can answer freely. A voice note starts it at once, and its transcript is the trigger's text. ## How does a change of a contact start a run? An `attribute.changed` trigger starts a run when `updateContact` changes the field it listens to: a declared [attribute](https://heythere.io/docs/concepts/attributes), the contact's `language`, or a consent. When the shop's software sets Camille's `repair_status` to `ready`, she gets "your bike is ready". Its optional `when` holds conditions on `trigger.before`, `trigger.after`, and `contact.`, such as `trigger.after` equals `ready`, so only that change starts a run. The run starts in the contact's conversation with the automation's number, opened if the contact never wrote to it. It is likely outside the reply window, so its steps send only [templates](https://heythere.io/docs/concepts/message-templates), each one the contact's [consent](https://heythere.io/docs/concepts/contacts#what-does-a-contact-consent-to-) allows. An import, a new contact, or a value a run writes starts no run. The automation reads `contact.` later, when it needs it. ## When does a date start a run? A `date.reached` trigger watches a date of the contact, a `date` [attribute](https://heythere.io/docs/concepts/attributes) or `createdAt` and `lastInboundAt`, and fires some days from it at a time of day in a time zone, or some minutes from an instant. A year after Camille's last service, at 10am Paris time, she gets the service offer. The firing moves when the date changes, and a moment already past starts no run. As for a change, the run starts in the contact's conversation with the automation's number, opened if needed, and sends only templates. ## How does another service start a run? A `webhook.received` trigger starts a run when a [webhook source](https://heythere.io/docs/concepts/webhook-sources) receives a matching request, such as your site reporting an unfinished booking, for the known contact whose phone number it holds. Its `fields` become `trigger.`. Like an `attribute.changed` run, it opens the conversation if needed and sends only templates. ## Which automation answers a number? Its own. Each number the workspace connects gets one automation, created empty with it, which never moves to another number. A number connected again finds its automation as it left it. `getWorkspaceMap` lists every number with its automation's ID and graph. Until that automation publishes a version, the number starts no run, and its messages wait in the inbox for the members. ## How does an automation tell contacts apart? Every message that starts a run starts the same trigger, so the steps after it sort the contacts. A [`condition` step](https://heythere.io/docs/concepts/steps) reads the contact's attributes or the message's text, such as a keyword, and a `classify` step lets [AI](https://heythere.io/docs/concepts/ai) tell what the contact wants, such as booking a repair or checking on a bike. The [workspace log](https://heythere.io/docs/concepts/workspace-log) says why a message started no run, such as `automation_unpublished` when its number's automation has no published version yet, and why a change started none, such as `active_run`. # Webhook sources: start automations from Stripe or your site > Let Stripe, your booking site or any other service tell an automation that something happened, so it writes to a customer or a waiting run goes on. Oliver starts booking a bike on the rental shop's site and leaves before paying. The site tells Heythere, and the shop's automation writes to him on WhatsApp. The site reaches Heythere through a webhook source: an address of the workspace that another service posts events to, such as your site when a booking is left unfinished, or Stripe when a deposit is paid. Its requests start [runs](https://heythere.io/docs/concepts/runs) through `webhook.received` [triggers](https://heythere.io/docs/concepts/triggers), and resume runs that wait at a `wait` [step](https://heythere.io/docs/concepts/steps) of type `webhook`. An agent creates one with `saveWebhookSource`, which returns its `url`. The member pastes it where the service sends webhooks. ## How does Heythere know a request comes from that service? Anyone could post to that address, so each source checks the signature the service puts on every request, with a signing secret the member saves as a workspace [secret](https://heythere.io/docs/concepts/secrets). Its `verification` says how the service signs: Stripe's `Stripe-Signature` header, an HMAC of the body as GitHub or Shopify send it, the Standard Webhooks headers, or a token in a header. A request that fails the check is refused, and the source keeps the latest refusal and its reason in `lastRefusal`. ## How does a request reach a contact or a run? - A `webhook.received` trigger reads the contact's phone number at `contactPhoneNumberPath`, so the site sends Oliver's number with the booking. It starts a run for a contact the workspace knows, opening their conversation with the automation's number if they never wrote to it, unless a run, a [live chat](https://heythere.io/docs/concepts/live-chats) or a handover holds it. Its run sends only [templates](https://heythere.io/docs/concepts/message-templates), each one the contact's consent allows. - A `wait` step of type `webhook` waits for a request that names its run. The automation sends Oliver a Stripe Payment Link for his deposit, with `{{run.id}}` as its `client_reference_id`, and Stripe sends it back at the source's `runIdPath` once he pays. The step saves the request's values and goes on to confirm his booking, or takes its timeout. A request that comes before the run reaches the step resumes nothing. A request whose event key, read at `eventKeyPath`, came before is not handled again, so a service retrying a delivery starts nothing twice. ## Where to look when nothing happens? Oliver left his booking and got no message? `listWebhookSourceEvents` lists the requests the source accepted in the last 30 days, with their body and what each trigger or run did with them, such as `contact_unknown` when the workspace does not know his number, or `run_active`. A request refused before it was kept shows only in `lastRefusal`. ## 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. - `saveWebhookSource`: Save a webhook source. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}` - `listWorkspaceWebhookSources`: List webhook sources. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources` - `listWebhookSourceEvents`: List the requests of a webhook source. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}/events` - `deleteWebhookSource`: Delete a webhook source. `DELETE /api/organizations/{organizationId}/workspaces/{workspaceId}/webhook-sources/{name}` # Steps: what a WhatsApp automation can do > Ask questions, send messages, use AI, wait, save values, and call your other tools, one step of an automation at a time. When Camille asks whether her bike is ready, the repair shop's automation checks its repair software, asks her for a pickup time, and hands her to a member when she wants one. Each of those is a step, one node of an [automation](https://heythere.io/docs/concepts/automations)'s graph. A [run](https://heythere.io/docs/concepts/runs) executes one step at a time, then follows its transition to the next. | `type` | Does | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `send_text` | Sends a text. | | `send_link` | Sends a text with a button that opens a link. | | `send_template` | Sends a [template](https://heythere.io/docs/concepts/message-templates), even outside the reply window. | | `ask_text` | Asks for a `text`, `number`, or `email`, and can save it. | | `ask_buttons` | Asks the contact to tap one of 1 to 3 reply buttons. | | `ask_list` | Asks the contact to pick one of at most 10 rows. | | `ai_agent` | Converses with an [AI](https://heythere.io/docs/concepts/ai) agent, saves values, and picks its exit. | | `classify` | Takes the category [AI](https://heythere.io/docs/concepts/ai) finds in the conversation. | | `condition` | Takes the first branch whose conditions hold, or its `onElse`. | | `wait` | Waits for a duration, a date, the opening of a [schedule](https://heythere.io/docs/concepts/variables), a [webhook](https://heythere.io/docs/concepts/webhook-sources) request, or a polled answer. | | `set_value` | Writes values to the run or to the contact, fixed, computed, or generated. | | `handover` | Ends the run and hands the conversation to the members in a [live chat](https://heythere.io/docs/concepts/live-chats). | | `http_request` | Calls another service, such as Slack or a CRM, and saves values of its response. | A run ends at a step with nothing after it. A `handover` sends nothing itself, so a `send_text` before it tells the contact a member will answer. Publishing refuses a message other than a `send_template` that could go out after the [reply window](https://heythere.io/docs/concepts/conversations#when-does-a-conversation-s-reply-window-close-) closes. That happens after a `wait` until a date or a schedule's opening, or when waits and question timeouts add up to 24 hours since the contact's latest message. ## Where do steps keep values? A step saves a value to the run, as `run.`, which lasts as long as the run, or to the contact, as an [attribute](https://heythere.io/docs/concepts/attributes) that later runs read too. A message inserts a value with a placeholder, such as `{{contact.first_name}}`, or a workspace [variable](https://heythere.io/docs/concepts/variables), such as `{{workspace.shop_address}}`. ## How does a question work? Each reply button or list row leads to its own next step. The contact answers by text or voice note, and taps or names a choice. Heythere's [AI](https://heythere.io/docs/concepts/ai) reads a reply the usual formats do not, such as "thirty-one" or "around 3pm" for "Afternoon"; `readsRepliesWithAi` false turns that off. An unclear reply asks again; the fifth in a row takes the optional `timeout`, as silence past it does, or ends the run. ## How does a `set_value` step compute a value? It evaluates a JavaScript expression, such as `run.price * run.quantity`, that reads `contact.`, `run.`, and `trigger.` by name, with the methods of texts, numbers, lists, and dates. An expression never calls an API. One that throws, such as `run.total.trim()` on a number, writes none of the step's values and fails the [run](https://heythere.io/docs/concepts/runs). ## How does a `condition` step choose a branch? It takes the first branch whose conditions all hold, or `onElse`. A condition compares a field, as an [audience](https://heythere.io/docs/concepts/audiences) does, is a boolean expression, such as `run.age >= 18`, or is a statement [AI](https://heythere.io/docs/concepts/ai) judges. ## How does an `http_request` step call another service? It sends its request when the run reaches it, reading placeholders such as `{{run.email}}` into its URL, headers, and JSON body, and credentials from workspace [secrets](https://heythere.io/docs/concepts/secrets), as `{{secret.crm_token}}`. A 2xx response saves the values `responseValues` names, such as `body.lead.id` to `contact.crm_id`, and the run takes `next`. Any other outcome takes `onError`, or fails the run without it. It reaches only public addresses. # AI: let models answer and sort WhatsApp conversations > Use AI models in an automation to talk with a customer, sort a conversation, check a condition or write a value, within what Meta allows on WhatsApp. Camille asks her repair shop on WhatsApp whether it can fit a new chain this week. In the shop's automation, an `ai_agent` step answers her, saves the day she wants, and takes the exit that leads to the next step. An automation uses AI only where its author put it or left a default on, for the purpose they gave. Heythere offers no assistant that chats about anything. | Where | Does | | ------------------------- | ----------------------------------------------------------------------- | | `ai_agent` step | Converses with the contact, saves what it learns, and takes an exit. | | `classify` step | Takes the category of the conversation, such as billing or delivery. | | `ai` condition | Holds when a statement, such as "The contact is upset", is likely true. | | `generate` in `set_value` | Writes a value from instructions, such as a summary to `run.summary`. | | A question, by default | Reads a reply in the contact's own words. | | A voice note, by default | Becomes a transcript every step reads. | Each reads its instructions and the run's recent messages. An agent step also reads photos, PDFs, and, on demand, earlier messages and runs. The [workspace log](https://heythere.io/docs/concepts/workspace-log) records each request, its cost, and what an agent did, after the summary of why its model gave. ## What does an agent step hold? - **Instructions**: who the business is, what the step is for, how it writes, what it knows of the contact. In an automation that answers in several languages, it writes in the one it answers the contact in. - **Values** it saves to the run or contact: text, email, number, yes or no, date, list, or choices. - **Exits**, each with what it requires. The model takes one whose `when` is settled, and one without `when` once its values are known. - **Tools**: `web_search`, when its model's `searchesWeb` is true, limited to `allowedDomains`; `http_request` calls, saving what they return; [MCP server](https://heythere.io/docs/concepts/mcp-servers) tools. - **A model** from `listAiModels` and its **reasoning effort**. More effort handles harder requests, slower and dearer. A turn may send several messages, with buttons, a list, or a link, and close with an exit. The step texts in short messages and reads voice notes past their transcript's slips. Camille sees it typing, and what she adds meanwhile reaches it before it answers. It may leave a thanks unanswered. It takes every message the business sent as its own, and may write as soon as its step starts, so put an `ask_text` before it to let the contact answer first. The step ends at an exit, its timeout, or the 50th reply, and runs only in the reply window. ## What is a decision model? A model that answers how likely each category or statement is, instead of writing text. A `classify` step names a `decisionModels` entry of `listAiModels` and takes `onUncertain` when no category stands out. `ai` conditions use Jev. Neither writes to the contact, so both run outside the reply window. ## How does `set_value` generate? The step asks its model once for every `generate` value, each typed as its target, from the values before the step. An unusable answer writes none and fails the [run](https://heythere.io/docs/concepts/runs). ## What does Meta allow? Since 15 January 2026, Meta's WhatsApp terms forbid offering AI as the service itself. They allow AI that serves a business's own purpose, such as support, sales, or onboarding. Keep each step's instructions on that purpose. ## 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. - `listAiModels`: List AI models. `GET /api/ai-models` # Versions: publish an automation without breaking chats > Edit an automation's draft freely, save versions of it, and publish one without breaking the conversations already under way. The repair shop wants its automation to ask Camille for a pickup time before it tells her the bike is ready. Its agent changes the draft and saves it as a version, then an administrator publishes it. An automation has one draft, the versions saved from it, and at most one published version, much like code and its commits. - **Draft.** Members and their agents edit it freely. Nothing in the draft reaches a contact. - **Version.** A snapshot of the draft that never changes, with a message saying what changed. Its author saves it as major (3 after 2.1) when it changes the graph's shape or a trigger, and as minor (2.2) otherwise. - **Published version.** The version whose triggers are active. Only [administrators](https://heythere.io/docs/concepts/organizations-and-workspaces) of the workspace publish, because publishing starts messaging contacts. - **Restore.** Copies a version into the draft, without losing the draft's changes or touching the published version. Publishing refuses a version that would fail a run, naming the trigger or step of each problem: a value read before any step writes it, an undeclared [attribute](https://heythere.io/docs/concepts/attributes), a condition comparing values of different kinds, or an [AI](https://heythere.io/docs/concepts/ai) model or reasoning effort Heythere does not offer. `getAutomation` lists them for the draft as `draftProblems`. A [run](https://heythere.io/docs/concepts/runs) stays on the version it started with. If Camille is already answering when the shop publishes, she finishes on the previous version, so publishing never breaks a conversation under way. ## 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. - `createAutomationVersion`: Version an automation's draft. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/versions` - `listAutomationVersions`: List automation versions. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/versions` - `getAutomationVersion`: Get an automation version. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/versions/{automationVersionId}` - `publishAutomationVersion`: Publish an automation version. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/published-version` - `restoreAutomationVersion`: Restore an automation version. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/versions/{automationVersionId}/restore` # Runs: follow each customer through an automation > Follow one customer through an automation, see where they stand, and find out why it stopped when it failed. Camille writes "Is my bike ready?" to her repair shop's WhatsApp number, and the shop's automation starts answering her. That is a run: one [contact](https://heythere.io/docs/concepts/contacts) going through one [version](https://heythere.io/docs/concepts/versions) of an [automation](https://heythere.io/docs/concepts/automations), in her [conversation](https://heythere.io/docs/concepts/conversations) with that number. A [trigger](https://heythere.io/docs/concepts/triggers) starts a run, or a member does when they [hand the conversation back](https://heythere.io/docs/concepts/live-chats#how-does-a-member-hand-the-contact-to-an-automation-) to an automation. If the shop publishes a new version while Camille is still answering, her run stays on the version it started with until it ends. ## What does a run's state mean? Camille's run is `waiting` while she picks a pickup time, and `completed` once it reaches its last step. | `state.type` | Meaning | | ------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `running` | The run executes a step, such as a `wait`. | | `waiting` | A question [step](https://heythere.io/docs/concepts/steps), or an `ai_agent` step, waits for a reply. | | `completed` | The run reached a step with nothing after it. | | `handed_over` | A `handover` step handed the conversation to the members. | | `cancelled` | Its [test](https://heythere.io/docs/concepts/tests) ended, or a member wrote in a [live chat](https://heythere.io/docs/concepts/live-chats) or started another run. | | `failed` | The run stopped at a step, for a reason it keeps. | ## Why does a run fail? Say the automation asks the shop's repair software for the bike's status, and the software is down. With no `onError` path on that `http_request` step, Camille's run stops `failed`, and its `failure` says why. A run also fails when a message cannot be sent, when WhatsApp or the AI provider stays unavailable, when an `ai_agent` step neither writes nor takes an exit, or when it reaches a step runs do not execute. The OpenAPI document lists each reason. ## How does an agent find out what happened? Ask your agent why Camille got no answer. It reads the run's `state` to see where it stopped, then calls `listWorkspaceLog` with the run's `automationRunId` to list every decision that led there, as the [workspace log](https://heythere.io/docs/concepts/workspace-log) explains. ## 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. - `listAutomationRuns`: List automation runs. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs` - `getAutomationRun`: Get an automation run. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/runs/{automationRunId}` # Tests: try a WhatsApp automation on your own phone > Try an automation's draft on your own phone before any customer sees it, as yourself or as a simulated contact, at any time of the week, and see how each step went. Before the repair shop publishes the automation that answers "Is my bike ready?", its owner tries the draft on their phone. That is a test: an [automation](https://heythere.io/docs/concepts/automations)'s draft running on a workspace member's phone, before any [version](https://heythere.io/docs/concepts/versions) is published. It messages from Heythere Playground, Heythere's number for tests, not the automation's [number](https://heythere.io/docs/concepts/whatsapp-connection), so it counts no conversation. ## How does a test start? A member selects Test on the automation's console page, or their agent calls `createAutomationTest` and gives them its `url`. The test copies the draft; the page shows a link and QR code to Heythere Playground. The member's next message to it starts the [run](https://heythere.io/docs/concepts/runs) at the draft's `message.received` trigger. Starting a test refuses what publishing would, but checks only that trigger and the steps it reaches, and a test sends no template. Only the member who started it receives it, on their sign-in number. Starting another test ends it. ## Which contact does a test play? The member's [contact](https://heythere.io/docs/concepts/contacts), or a simulated contact picked under Play as, such as a Camille whose bike is ready. The agent building the automation sets each simulated contact's attributes, consents, language and creation date with `replaceAutomationSimulatedContacts`, one per path. Later tests keep the pick. ## At what time does a test play? Now, or at a time the member picks under Play at (`playAt`), such as a Saturday evening, to see the automation outside opening hours without touching the workspace's [variables](https://heythere.io/docs/concepts/variables). The run's time starts there and moves on. Waits of type duration, date or opening end at once, jumping the test's time to their end; webhook and polling waits take real time. ## What does a test change? Nothing a contact sees. Contact values go to the test's own copy of the contact it plays, a `handover` step ends the test, and its messages and run appear in no conversation or list of runs. It reads voice notes as their transcript, bills its AI requests and transcriptions like any [AI](https://heythere.io/docs/concepts/ai) request, and really sends its `http_request` steps. ## When does a test end? With its run, when stopped with `stopAutomationTest`, when the member starts another, or 24 hours after their last message. ## How do a member and an agent follow a test? The console page marks the steps and transitions the run took. Its log groups the run's workspace log by step, and selecting an entry shows where the run stood. An agent reads the test with `getAutomationTest`, and the run's decisions with `listWorkspaceLog` and its `automationRunId`. ## 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. - `createAutomationTest`: Test an automation's draft. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/tests` - `getAutomationTest`: Get an automation test. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/tests/{automationTestId}` - `listAutomationTests`: List automation tests. `GET /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/tests` - `stopAutomationTest`: Stop an automation test. `POST /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/tests/{automationTestId}/stop` - `replaceAutomationSimulatedContacts`: Replace an automation's simulated contacts. `PUT /api/organizations/{organizationId}/workspaces/{workspaceId}/automations/{automationId}/simulated-contacts` # Glossary: the words Heythere uses, and the ones it avoids > The one word Heythere uses for each concept, in the console, the API and these pages, and the words it avoids, with what it says instead. Heythere gives each concept one name, used in the console, the API, and these pages. | Term | Meaning | | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | [Organization](https://heythere.io/docs/concepts/organizations-and-workspaces) | Its members and its workspaces; a member works only in the workspaces it was given. | | [Workspace](https://heythere.io/docs/concepts/organizations-and-workspaces) | Where a WhatsApp connection, its contacts, conversations, templates, and automations live. | | [WhatsApp phone number](https://heythere.io/docs/concepts/whatsapp-connection) | A number the workspace messages from. A workspace can have several. | | [Contact](https://heythere.io/docs/concepts/contacts) | A person reachable on WhatsApp in a workspace, identified by its WhatsApp user ID, its phone number, or both. | | [Attribute](https://heythere.io/docs/concepts/attributes) | A typed field the workspace declares on its contacts: text, number, boolean, date, or list. | | [Language](https://heythere.io/docs/concepts/automations#how-does-an-automation-answer-in-several-languages-) | The language a contact reads, such as `fr`. | | [Audience](https://heythere.io/docs/concepts/audiences) | Conditions on a contact that narrow a broadcast's recipients. | | [Conversation](https://heythere.io/docs/concepts/conversations) | One per contact and phone number: every message exchanged on that number. | | [Reply window](https://heythere.io/docs/concepts/conversations#when-does-a-conversation-s-reply-window-close-) | The 24 hours after the contact's last message in a conversation. Outside it, every message is a template. | | [Live chat](https://heythere.io/docs/concepts/live-chats) | Members answering a contact themselves in a conversation, while automations wait. | | [Template](https://heythere.io/docs/concepts/message-templates) | A message Meta reviews before a business sends it outside the reply window. | | [Broadcast](https://heythere.io/docs/concepts/broadcasts) | A template sent once to the contacts an audience selects. | | [Verification](https://heythere.io/docs/concepts/verifications) | A one-time code sent on WhatsApp to prove that a person holds a phone number. | | [Automation](https://heythere.io/docs/concepts/automations) | A WhatsApp number's graph of steps that messages a contact and reacts to the replies: a draft, a published version. | | [Trigger](https://heythere.io/docs/concepts/triggers) | An entry point of an automation graph, which starts a run on the automation's number. | | [Webhook source](https://heythere.io/docs/concepts/webhook-sources) | An address another service posts events to, which start or resume runs. | | [Step](https://heythere.io/docs/concepts/steps) | One node of an automation graph that sends, asks, waits, or writes. | | [Agent step](https://heythere.io/docs/concepts/ai) | An `ai_agent` step, which converses with the contact with an AI model, saves values, and chooses its exit. | | [Version](https://heythere.io/docs/concepts/versions) | A snapshot of an automation's graph that never changes, with a message saying what changed. | | [Run](https://heythere.io/docs/concepts/runs) | A contact going through one automation version in one conversation. | | [Test](https://heythere.io/docs/concepts/tests) | An automation's draft run on a member's own phone from Heythere Playground, before it is published. | | [Run variable](https://heythere.io/docs/concepts/steps#where-do-steps-keep-values-) | A value a step saves to its run, which lasts as long as the run. | | [Variable](https://heythere.io/docs/concepts/variables) | A typed value the workspace keeps, such as its address, which every automation reads as `workspace.`. | | [Secret](https://heythere.io/docs/concepts/secrets) | A credential the workspace keeps for its `http_request` steps, which no one reads back. | | [MCP server](https://heythere.io/docs/concepts/mcp-servers) | A service's endpoint whose tools agent steps call, which a member may connect once for the workspace. | | [Workspace log](https://heythere.io/docs/concepts/workspace-log) | What Heythere did and received for a workspace, kept 30 days to explain a conversation. | | [Usage](https://heythere.io/docs/concepts/usage) | What each workspace of an organization consumed: billed conversations and AI cost. | | [Billed conversation](https://heythere.io/docs/concepts/usage#what-is-a-billed-conversation-) | The messages delivered to one contact on one number for 24 hours after the first, up to 50. | | [Bug report](https://heythere.io/docs/concepts/bug-reports) | A bug an agent reports to Heythere's team, with the IDs that locate it. | | [API key](https://heythere.io/docs/concepts/api-access) | A credential a user creates so their service calls the API as them. | ## Which words does Heythere not use? | Word | Heythere says | | ---------------------------- | ------------------------------------------------------------ | | Bot | [Automation](https://heythere.io/docs/concepts/automations). | | Flow | Automation: a WhatsApp Flow is Meta's in-chat form. | | Tag | An item of a list [attribute](https://heythere.io/docs/concepts/attributes). | | Agent, for a person | Member: an agent is an AI agent. | | Teammate | Member. | | Revision | [Version](https://heythere.io/docs/concepts/versions). | | Preview, simulation, sandbox | A [test](https://heythere.io/docs/concepts/tests). | | AI step, AI assistant | An [agent step](https://heythere.io/docs/concepts/ai), or the AI part it names. | | Prompt | A step's instructions. | | Customer service window | Reply window, Meta's name for it. | | Feedback, issue, ticket | [Bug report](https://heythere.io/docs/concepts/bug-reports), for bugs only. |