# Add labels to contact Source: https://docs.heyy.io/api-reference/add-labels-to-contact /api-reference/openapi-v3.json post /contacts/{contactId}/labels # Add recipients Source: https://docs.heyy.io/api-reference/add-recipients /api-reference/openapi-v3.json post /campaigns/{campaignId}/recipients # Assign chat to team Source: https://docs.heyy.io/api-reference/assign-chat-to-team /api-reference/openapi-v3.json post /chats/{chatId}/assign_team # Assign chat to user Source: https://docs.heyy.io/api-reference/assign-chat-to-user /api-reference/openapi-v3.json post /chats/{chatId}/assign_user # Bulk upsert contacts Source: https://docs.heyy.io/api-reference/bulk-upsert-contacts /api-reference/openapi-v3.json post /contacts/bulk # Change chat status Source: https://docs.heyy.io/api-reference/change-chat-status /api-reference/openapi-v3.json post /chats/{chatId}/status # Create attribute Source: https://docs.heyy.io/api-reference/create-attribute /api-reference/openapi-v3.json post /attributes # Create campaign Source: https://docs.heyy.io/api-reference/create-campaign /api-reference/openapi-v3.json post /campaigns # Create contact Source: https://docs.heyy.io/api-reference/create-contact /api-reference/openapi-v3.json post /contacts # Create label Source: https://docs.heyy.io/api-reference/create-label /api-reference/openapi-v3.json post /labels # Delete attribute Source: https://docs.heyy.io/api-reference/delete-attribute /api-reference/openapi-v3.json delete /attributes/{attributeId} # Delete campaign Source: https://docs.heyy.io/api-reference/delete-campaign /api-reference/openapi-v3.json delete /campaigns/{campaignId} # Delete chat Source: https://docs.heyy.io/api-reference/delete-chat /api-reference/openapi-v3.json delete /chats/{chatId} # Delete contact Source: https://docs.heyy.io/api-reference/delete-contact /api-reference/openapi-v3.json delete /contacts/{contactId} # Delete label Source: https://docs.heyy.io/api-reference/delete-label /api-reference/openapi-v3.json delete /labels/{labelId} # Get attribute Source: https://docs.heyy.io/api-reference/get-attribute /api-reference/openapi-v3.json get /attributes/{attributeId} # Get automation Source: https://docs.heyy.io/api-reference/get-automation /api-reference/openapi-v3.json get /automations/{automationId} # Get campaign Source: https://docs.heyy.io/api-reference/get-campaign /api-reference/openapi-v3.json get /campaigns/{campaignId} # Get channel Source: https://docs.heyy.io/api-reference/get-channel /api-reference/openapi-v3.json get /channels/{channelId} # Get chat Source: https://docs.heyy.io/api-reference/get-chat /api-reference/openapi-v3.json get /chats/{chatId} # Get contact Source: https://docs.heyy.io/api-reference/get-contact /api-reference/openapi-v3.json get /contacts/{contactId} # Get file Source: https://docs.heyy.io/api-reference/get-file /api-reference/openapi-v3.json get /files/{fileId} # Get journey Source: https://docs.heyy.io/api-reference/get-journey /api-reference/openapi-v3.json get /journeys/{journeyId} # Get label Source: https://docs.heyy.io/api-reference/get-label /api-reference/openapi-v3.json get /labels/{labelId} # Get public file URL Source: https://docs.heyy.io/api-reference/get-public-file-url /api-reference/openapi-v3.json get /files/{fileId}/public_url Returns a stable public URL for an uploaded file, creating one if it does not exist yet. Use this URL when referencing the file by URL (for example, in automation template media overrides). The URL does not expire. # Mark chat as not sensitive Source: https://docs.heyy.io/api-reference/mark-chat-as-not-sensitive /api-reference/openapi-v3.json post /chats/{chatId}/mark_as_not_sensitive # Mark chat as read Source: https://docs.heyy.io/api-reference/mark-chat-as-read /api-reference/openapi-v3.json post /chats/{chatId}/mark_as_read # Mark chat as sensitive Source: https://docs.heyy.io/api-reference/mark-chat-as-sensitive /api-reference/openapi-v3.json post /chats/{chatId}/mark_as_sensitive # Mark chat as unread Source: https://docs.heyy.io/api-reference/mark-chat-as-unread /api-reference/openapi-v3.json post /chats/{chatId}/mark_as_unread # Pause automation Source: https://docs.heyy.io/api-reference/pause-automation /api-reference/openapi-v3.json post /automations/{automationId}/pause # Remove labels from contact Source: https://docs.heyy.io/api-reference/remove-labels-from-contact /api-reference/openapi-v3.json delete /contacts/{contactId}/labels # Remove recipients Source: https://docs.heyy.io/api-reference/remove-recipients /api-reference/openapi-v3.json delete /campaigns/{campaignId}/recipients # Search attributes Source: https://docs.heyy.io/api-reference/search-attributes /api-reference/openapi-v3.json post /attributes/search # Search automations Source: https://docs.heyy.io/api-reference/search-automations /api-reference/openapi-v3.json post /automations/search # Search campaigns Source: https://docs.heyy.io/api-reference/search-campaigns /api-reference/openapi-v3.json post /campaigns/search # Search channels Source: https://docs.heyy.io/api-reference/search-channels /api-reference/openapi-v3.json post /channels/search # Search chats Source: https://docs.heyy.io/api-reference/search-chats /api-reference/openapi-v3.json post /chats/search # Search contacts Source: https://docs.heyy.io/api-reference/search-contacts /api-reference/openapi-v3.json post /contacts/search # Search journeys Source: https://docs.heyy.io/api-reference/search-journeys /api-reference/openapi-v3.json post /journeys/search # Search labels Source: https://docs.heyy.io/api-reference/search-labels /api-reference/openapi-v3.json post /labels/search # Send message Source: https://docs.heyy.io/api-reference/send-message /api-reference/openapi-v3.json post /messages/send # Start campaign Source: https://docs.heyy.io/api-reference/start-campaign /api-reference/openapi-v3.json post /campaigns/{campaignId}/start # Subscribe contact Source: https://docs.heyy.io/api-reference/subscribe-contact /api-reference/openapi-v3.json post /contacts/{contactId}/subscribe # Subscribe contacts to journey Source: https://docs.heyy.io/api-reference/subscribe-contacts-to-journey /api-reference/openapi-v3.json post /journeys/{journeyId}/subscribe # Trigger automation Source: https://docs.heyy.io/api-reference/trigger-automation /api-reference/openapi-v3.json post /automations/{automationId}/trigger # Unpause automation Source: https://docs.heyy.io/api-reference/unpause-automation /api-reference/openapi-v3.json post /automations/{automationId}/unpause # Unsubscribe contact Source: https://docs.heyy.io/api-reference/unsubscribe-contact /api-reference/openapi-v3.json post /contacts/{contactId}/unsubscribe # Unsubscribe contacts from journey Source: https://docs.heyy.io/api-reference/unsubscribe-contacts-from-journey /api-reference/openapi-v3.json post /journeys/{journeyId}/unsubscribe # Update attribute Source: https://docs.heyy.io/api-reference/update-attribute /api-reference/openapi-v3.json put /attributes/{attributeId} # Update campaign Source: https://docs.heyy.io/api-reference/update-campaign /api-reference/openapi-v3.json put /campaigns/{campaignId} # Update contact Source: https://docs.heyy.io/api-reference/update-contact /api-reference/openapi-v3.json put /contacts/{contactId} Updates contact profile fields (first name, last name, and custom attributes). Phone number and email cannot be changed here — use upsert to create or match by identifier. # Update label Source: https://docs.heyy.io/api-reference/update-label /api-reference/openapi-v3.json put /labels/{labelId} # Upload file Source: https://docs.heyy.io/api-reference/upload-file /api-reference/openapi-v3.json post /files # Upsert contact Source: https://docs.heyy.io/api-reference/upsert-contact /api-reference/openapi-v3.json post /contacts/upsert # Authentication Source: https://docs.heyy.io/api-reference/v3/authentication How to authenticate requests to the Heyy API v3. The Heyy API uses bearer tokens passed in the `Authorization` header to authenticate calls. ## Obtaining your API key You can create and manage API keys in the Heyy web app. Follow these steps: Navigate to the [**API Keys** settings page](https://app.heyy.io/settings/api-keys) in your Heyy workspace. API Keys settings Click **Create API key** to open the creation form. Create API key form Enter a descriptive **Name** for the key (for example, "CRM integration" or "Website bot"), then click **Create**. Generated API key Copy the generated key using the copy button and store it somewhere safe. Click **Done** when you are finished. > **Important** > For security reasons, the full key is only shown once when it is created. If you lose it, you will need to create a new key. ## Sending the bearer token Include your API token in every request using the `Authorization` header with the `Bearer` scheme: ```bash theme={null} curl https://api.heyy.io/v3/... \ -H "Authorization: Bearer " ``` Guidelines: * Always send requests over **HTTPS**. Requests over `http://` may fail or be rejected. * Keep your API tokens secret and **never** embed them in client-side code or public repositories. * If you suspect a token is compromised, revoke it in the Heyy dashboard and create a new one. All operations allowed by the Heyy API are scoped to your account, so any request made with your token has access to your workspace data. # Error Handling Source: https://docs.heyy.io/api-reference/v3/error-handling How the Heyy API reports errors and how to handle them. The Heyy API uses conventional HTTP response codes to indicate success or failure. Response codes in the **2xx** range indicate success. Codes in the **4xx** range indicate a client error—the request failed given the information provided. Codes in the **5xx** range indicate an error on Heyy's servers. ## HTTP error codes in use The API uses the following HTTP codes to communicate errors: | HTTP Code | Error type | Description | | --------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Client error | Returned when there is a type mismatch in the request body, invalid fields, or other structural issues in the request. | | 401 | Unauthorized | Returned when the request could not be authenticated (e.g. missing or invalid API key). | | 404 | Not found | Returned when the requested resource does not exist. | | 429 | Too many requests | Returned when you exceed the [rate limit](/api-reference/v3/rate-limiting). Throttle requests and use the rate limit headers to retry appropriately. | | 500 | Unexpected error | Returned when an unexpected problem occurs on our servers. Retry with exponential backoff. | ## Error object Every error response uses the same structure: `success` set to `false` and a single `error` object with `messageKey` and `message`. For **400** responses, `error` may also include `invalidParams` with field-level validation details. ```json theme={null} { "success": false, "error": { "messageKey": "contact_not_found", "message": "No contact could be found for this resource identifier. Please make sure to use the correct contact ID." } } ``` # Overview Source: https://docs.heyy.io/api-reference/v3/overview Welcome to the Heyy Developer Guide! Whether you’re integration a simple API or building complex integrations, this guide will help you implement our API. Heyy banner Heyy banner ## Welcome to the Heyy API The Heyy API is a REST API that lets you build rich messaging experiences on top of Heyy. Use it to: * Send and receive messages across your connected channels. * Manage contacts, chats, broadcasts, and more. * Automate repetitive workflows and integrate Heyy with your existing tools. Whether you are adding a simple integration or building a full customer messaging platform, this documentation will help you get started quickly and stay productive. # Pagination Source: https://docs.heyy.io/api-reference/v3/pagination Page through search results with pagination in the request and response. Search endpoints return paginated arrays. Control page size with **`pagination`** in the request body; read totals from the response. ## Request shape ```json theme={null} { "pagination": { "page": 0, "limit": 10 } } ``` | Field | Type | Description | | ------- | ------------- | ---------------------------------------------------------------- | | `page` | integer ≥ 0 | Zero-based page index. Defaults to **0** when omitted. | | `limit` | integer 1–100 | Rows per page. Defaults to **10** when omitted. Maximum **100**. | Omit `pagination` entirely to use defaults. ## Response shape Paginated search responses wrap results like this: ```json theme={null} { "success": true, "data": [], "pagination": { "page": 0, "limit": 10, "total": 142 }, "query": { "query": "equals(status, 'open')", "sortBy": "desc(createdAt)", "search": "acme" } } ``` | Field | Description | | ------------------ | ----------------------------------------------------------------------------------------- | | `success` | Always `true` for successful paginated search responses | | `data` | Array of resources for the current page | | `pagination.page` | Current page index | | `pagination.limit` | Page size used for this request | | `pagination.total` | Total matching rows across all pages | | `query` | Echo of the `query`, `sortBy`, and `search` values applied to this request (when present) | ## Paging through results Increment `page` until `page * limit >= total`: ```bash theme={null} # Page 0 → rows 0–9 # Page 1 → rows 10–19 # … ``` ## Related fields Search bodies combine pagination with optional [`query`](/api-reference/v3/query), [`sortBy`](/api-reference/v3/sort-by), and [`search`](/api-reference/v3/search) filters. # Query Source: https://docs.heyy.io/api-reference/v3/query Filter list results with structured query expressions on search endpoints. Most list endpoints use `POST .../search` with an optional **`query`** string in the request body. Use it to filter rows before pagination is applied. `query` is a **structured expression**, not plain keyword search. For text matching across searchable fields, use the separate [`search`](/api-reference/v3/search) field instead. ## Request shape ```json theme={null} { "query": "equals(status, 'open')", "pagination": { "page": 0, "limit": 25 } } ``` All search body fields are optional. Omit `query` to return unfiltered results (subject to your workspace permissions and any endpoint-specific defaults). ## Expression syntax `query` uses a function-call syntax parsed as an expression tree. Combine filters with logical operators: | Function | Description | | ----------- | ------------------------- | | `and(...)` | All conditions must match | | `or(...)` | Any condition must match | | `not(expr)` | Negates a condition | ### Comparisons | Function | Description | | -------------------------------------------------------------------- | --------------------------------------------------------- | | `equals(field, value)` | Exact match (string, number, date, or boolean) | | `has(field)` | Field is present / not null | | `startsWith(field, value)` | String prefix match | | `endsWith(field, value)` | String suffix match | | `contains(field, value)` | Substring match | | `gt(field, value)` / `gte(field, value)` | Numeric greater than / greater than or equal | | `lt(field, value)` / `lte(field, value)` | Numeric less than / less than or equal | | `before(field, date)` / `after(field, date)` | Date comparisons | | `relativeBefore(field, n, unit)` / `relativeAfter(field, n, unit)` | Relative date windows (`unit`: `days`, `weeks`, `months`) | | `relativeEqual(field, n, unit)` / `relativeNotEqual(field, n, unit)` | Relative date equality checks | | `inArray(field, [values])` | Value is in a list | | `containsAll(field, [values], key?)` | Array field contains all values | | `containsAny(field, [values], key?)` | Array field contains any value | | `equalsSet(field, [values], key?)` | Array field matches the set exactly | ### Field references * Use the resource field name directly, for example `status`, `createdAt`, or `name`. * Reference another column in the expression with `col('fieldName')`. * Filter on a contact attribute with `getBy('attributes', 'id', 'attribute-id')` or `getBy('attributes', 'name', 'attribute_name')`. ## Examples ```json theme={null} { "query": "and(equals(status, 'open'), contains(name, 'Acme'))" } ``` ```json theme={null} { "query": "or(equals(channelType, 'whatsapp'), equals(channelType, 'instagram'))" } ``` ```json theme={null} { "query": "relativeAfter(createdAt, 7, 'days')" } ``` Field names are case-sensitive. Each search endpoint documents its filterable fields on the `query` property in the API reference. # Rate Limiting Source: https://docs.heyy.io/api-reference/v3/rate-limiting How API rate limits work and how to handle 429 responses. API rate limits are in place to protect the Heyy API from traffic spikes that could put our systems at risk. We measure the number of requests sent to the API and throttle when they exceed the allowed amount. When you exceed the limit, we respond with **429 Too Many Requests** and include the following headers:
Header Name Description
X-RateLimit-Limit Maximum number of requests allowed for the app.
X-RateLimit-Remaining Number of requests left in the current minute.
X-RateLimit-Reset Time when the request count resets to the maximum. Shown as a UNIX timestamp.
## Rate limits by plan Limits are applied per **1-minute** window. The table below shows the maximum number of requests allowed per minute for each plan. | Plan | Requests per minute | | ---------- | ------------------- | | Hobby | 100 | | Pro | 500 | | Ultra | 1,000 | | Enterprise | Custom | ## Error response example When you are rate limited, the API returns **429 Too Many Requests** with this body: ```json theme={null} { "success": false, "error": { "messageKey": "rate_limit_exceeded", "message": "Too many requests. Limit is applied per minute per tenant. Please retry after the time indicated by the X-RateLimit-Reset header." } } ``` Use the `X-RateLimit-Reset` header to know when you can send requests again, and consider implementing exponential backoff or queuing to avoid hitting the limit repeatedly. # Search Source: https://docs.heyy.io/api-reference/v3/search Full-text search on list endpoints using the search request body field. In addition to structured [`query`](/api-reference/v3/query) filters, search endpoints accept an optional **`search`** string for keyword-style lookup. ## `search` vs `query` | Field | Purpose | | ------------ | -------------------------------------------------------------------- | | **`query`** | Structured filter expressions (`equals`, `contains`, `and`, `or`, …) | | **`search`** | Free-text search across the resource's searchable fields | You can use them together: ```json theme={null} { "search": "john acme", "query": "equals(status, 'open')", "sortBy": "desc(updatedAt)", "pagination": { "page": 0, "limit": 25 } } ``` ## Request shape ```json theme={null} { "search": "your keywords here" } ``` `search` is a plain string. Matching behavior (which columns are searched and how terms are tokenized) depends on the resource. Each search endpoint documents the `search` property in the API reference. # Sort By Source: https://docs.heyy.io/api-reference/v3/sort-by Order search results with sortBy expressions. Search endpoints accept an optional **`sortBy`** string in the request body to control result ordering. ## Request shape ```json theme={null} { "sortBy": "desc(createdAt)", "pagination": { "page": 0, "limit": 25 } } ``` If `sortBy` is omitted, the API uses the endpoint's default ordering. ## Expression syntax `sortBy` uses the same expression parser as [`query`](/api-reference/v3/query), but only sorting functions are allowed. ### Single field ```json theme={null} { "sortBy": "asc(name)" } ``` ```json theme={null} { "sortBy": "desc(updatedAt, 'nulls last')" } ``` | Function | Description | | -------------------------------------------- | ------------------------------ | | `asc(field)` | Ascending order | | `desc(field)` | Descending order | | `asc(field, 'nulls first' \| 'nulls last')` | Ascending with null placement | | `desc(field, 'nulls first' \| 'nulls last')` | Descending with null placement | ### Multiple fields Chain sort keys with `sort(...)`: ```json theme={null} { "sortBy": "sort(desc(updatedAt), asc(name))" } ``` ### Attribute fields Sort by a contact attribute using `getBy`: ```json theme={null} { "sortBy": "asc(getBy('attributes', 'name', 'company'))" } ``` Field names are case-sensitive. Each search endpoint documents its sortable fields on the `sortBy` property in the API reference. # Versioning Source: https://docs.heyy.io/api-reference/v3/versioning How Heyy versions its public API and deprecates older versions. The Heyy API is versioned in the request path, following semantic versioning principles. ### Versioning model * We use **major** and **minor** versions (for example, `v2`, `v3`). * Major versions are encoded in the base path of the API: ```bash theme={null} GET https://api.heyy.io/v2/... GET https://api.heyy.io/v3/... ``` ### Current version The current latest version of the Heyy API is **v3**. Use it for all new integrations. ### API v2 sunset [API v2](/api-reference/v2/overview) is deprecated and will be **sunset on November 1, 2026**. After that date, v2 endpoints will no longer be available. If you are still on v2, plan your migration to v3 before the sunset date. Key changes include: * Search endpoints use `POST .../search` with a request body instead of list `GET` endpoints. * Broadcasts are now **campaigns**. * Workflows are now **automations**. * Webhook management uses the [v3 API webhook endpoints](/webhooks/overview#manage-webhooks-via-api). If you need help planning or executing a migration between versions, please contact our support team and we'll be happy to assist. ### Deprecation policy When we release a new major version: * The previous major version remains **available and supported for up to 3 months** after the new version is published. * We clearly communicate deprecation timelines and the exact sunset date in advance. This window is intended to give you enough time to: * Test your integration against the new version. * Roll out changes safely across your environments. # Facebook Messenger Source: https://docs.heyy.io/channels/facebook Connect your Facebook Page to handle Messenger conversations in your Heyy Inbox with automations, AI Employees, and campaigns. Facebook channel Facebook Messenger lets you handle conversations from your Facebook Page directly in your Heyy [Inbox](/quick-start/inbox). Your customers can message you on Messenger while you use the same [automations](/quick-start/automations/triggers), [AI Employees](/quick-start/ai-employees), [contacts](/quick-start/contacts), and [campaigns](/quick-start/campaigns) as with WhatsApp, Instagram, and Live Chat. ## Requirements Before you connect, ensure: * **Admin role**: The user who clicks **Connect** must be an **admin** with access to the Facebook Page you want to connect. * **Page in Business Portfolio**: The Page must be connected to your [Meta Business Portfolio](https://business.facebook.com). Go to [**Pages** in Business settings](https://business.facebook.com/latest/settings/pages) and confirm the Page is listed there. If the Page is not in your Business Portfolio, add it before starting the onboarding flow. ## Connecting 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **Facebook** (Messenger). 4. Click **Connect** in the dialog. Clicking **Connect** opens **Meta’s Facebook Messenger onboarding flow**. You’ll be asked to sign in with Facebook (if needed) and to authorize Heyy to manage messaging for your Facebook Page. Complete the flow in the window that opens. When authorization succeeds, Heyy creates the channel and the dialog closes. Your Messenger channel then appears in **Settings → Channels**. ### About Meta’s onboarding flow Heyy uses [Login Connect with Messenger](https://developers.facebook.com/docs/facebook-login/login-connect/) so you can connect your Facebook Page to Heyy in one step. During the flow, Meta may ask you to: * Sign in to Facebook or confirm your account. * Choose the **Facebook Page** you want to connect (you must have admin or appropriate access to that Page). * Grant Heyy permission to send and receive messages on behalf of that Page. For more on the Messenger Platform and requirements (e.g. Page, app, permissions), see Meta’s documentation: * [Messenger Platform overview](https://developers.facebook.com/docs/messenger-platform/overview/) * [Messenger Platform getting started](https://developers.facebook.com/docs/messenger-platform/getting-started/quick-start/) * [Login Connect with Messenger](https://developers.facebook.com/docs/facebook-login/login-connect/) If the connection fails or you don’t see your Page, check that your [Meta Business Portfolio](https://business.facebook.com) and [Business Info](https://business.facebook.com/latest/settings/business_info) are complete, and that you have the right role on the Page. For help, [contact Heyy support](https://heyy.io/contact-us). ## Editing Open the channel from **Settings → Channels** and use the **Profile** tab. ### Profile * **Internal name**: A label for this channel inside Heyy (e.g. “Support Messenger”). You can edit this at any time. * **Display name**: The name of your Facebook Page as shown to customers. This is read-only and comes from your Page; to change it, update the Page on Facebook. * **Edit profile on Facebook**: Use the button to open your Facebook Page in a new tab so you can edit the Page profile, profile picture, and other settings on [Facebook](https://www.facebook.com). ## Removing Disconnecting or deleting a Messenger channel is **irreversible**. Heyy will no longer send or receive messages for that Page. Existing conversations and history for that channel may be lost or no longer accessible. If you might need the data later, export or back up before disconnecting. To remove a Messenger channel, go to **Settings → Channels**, open the Messenger channel, and use the disconnect or delete option for that channel. ## Use cases * **Customer support**: Answer questions and resolve issues on Messenger. All chats appear in your [Inbox](/quick-start/inbox). * **Marketing and follow-up**: Use [campaigns](/quick-start/campaigns) to reach contacts on Messenger, or offer Messenger as a follow-up channel (e.g. from [Live Chat](/channels/live-chat) or your website) so customers can continue the conversation where they prefer. * **Automations**: Use [Messenger triggers](/quick-start/automations/triggers) and [Facebook actions](/quick-start/automations/facebook-actions) (e.g. send message, wait for reply, quick replies) for welcome flows, qualification, or routing. * **AI Employees**: Assign an [AI Employee](/quick-start/ai-employees) to handle first-line replies on Messenger 24/7. Ensure your Facebook Page is published and your [Business Info](https://business.facebook.com/latest/settings/business_info) is complete before connecting. Keep your Page profile and profile picture up to date so customers recognize your brand. # Instagram Source: https://docs.heyy.io/channels/instagram Connect your Instagram account to handle Instagram Direct messages in your Heyy Inbox with automations, AI Employees, and campaigns. Instagram channel Instagram lets you handle Instagram Direct messages in your Heyy [Inbox](/quick-start/inbox). Your customers can message you on Instagram while you use the same [automations](/quick-start/automations/triggers), [AI Employees](/quick-start/ai-employees), [contacts](/quick-start/contacts), and [campaigns](/quick-start/campaigns) as with WhatsApp, Messenger, and Live Chat. ## Requirements Before you connect, ensure: * **Admin role**: The user who clicks **Connect** must be an **admin** with access to the Instagram account and the linked Facebook Page. * **Professional account**: The Instagram account must be a **professional account** (Creator or Business), not a personal account. * **Connected to a Page**: The Instagram account must be **connected to a Facebook Page**. See [Connect Instagram to a Facebook Page](https://www.facebook.com/help/instagram/570895513091465). * **Both in Business Portfolio**: Both the **Facebook Page** and the **Instagram account** must be in your [Meta Business Portfolio](https://business.facebook.com). Verify your Page in [**Pages** in Business settings](https://business.facebook.com/latest/settings/pages) and add or link your Instagram account—see [Add an Instagram account to your business portfolio](https://facebook.com/business/help/620548115562686). If either is not in your portfolio, add or connect them before starting the onboarding flow. ## Connecting 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **Instagram**. 4. Click **Connect** in the dialog. Clicking **Connect** opens **Meta’s Instagram onboarding flow**. You’ll be asked to sign in with Facebook (if needed) and to authorize Heyy to manage messaging for your Instagram account. Complete the flow in the window that opens. When authorization succeeds, Heyy creates the channel and the dialog closes. Your Instagram channel then appears in **Settings → Channels**. ### About Meta’s onboarding flow Heyy uses Meta’s embedded signup so you can connect your Instagram account to Heyy in one step. During the flow, Meta may ask you to: * Sign in to Facebook or confirm your account. * Choose the **Instagram account** you want to connect (you must have admin access to that account and its linked Page). * Grant Heyy permission to send and receive messages on behalf of that Instagram account. If the connection fails or you don’t see your Instagram account, check that your account is a professional account, that it’s connected to a Page, that both are in your [Meta Business Portfolio](https://business.facebook.com) and [Business Info](https://business.facebook.com/latest/settings/business_info) is complete, and that you have the right role (Admin). For help, [contact Heyy support](https://heyy.io/contact-us). ## Editing Open the channel from **Settings → Channels** and use the **Profile** tab. ### Profile * **Internal name**: A label for this channel inside Heyy (e.g. “Support Instagram”). You can edit this at any time. * **Display name**: The Instagram username (handle) as shown to customers. This is read-only and comes from your Instagram account; to change it, update your profile on Instagram. * **Edit profile on Instagram**: Use the button to open your Instagram profile in a new tab so you can edit your profile, bio, and settings on [Instagram](https://www.instagram.com). ## Removing Disconnecting or deleting an Instagram channel is **irreversible**. Heyy will no longer send or receive messages for that Instagram account. Existing conversations and history for that channel may be lost or no longer accessible. If you might need the data later, export or back up before disconnecting. To remove an Instagram channel, go to **Settings → Channels**, open the Instagram channel, and use the disconnect or delete option for that channel. ## Use cases * **Customer support**: Answer questions and resolve issues on Instagram Direct. All chats appear in your [Inbox](/quick-start/inbox). * **Marketing and follow-up**: Use [campaigns](/quick-start/campaigns) to reach contacts on Instagram, or offer Instagram as a follow-up channel (e.g. from [Live Chat](/channels/live-chat) or your website) so customers can continue the conversation where they prefer. * **Automations**: Use [Instagram triggers](/quick-start/automations/triggers) and [Instagram actions](/quick-start/automations/instagram-actions) (e.g. send message, wait for reply) for welcome flows, qualification, or routing. * **AI Employees**: Assign an [AI Employee](/quick-start/ai-employees) to handle first-line replies on Instagram 24/7. Ensure your Instagram account is a professional account and connected to a Facebook Page before connecting. Keep your [Business Info](https://business.facebook.com/latest/settings/business_info) and [Meta Business Portfolio](https://business.facebook.com) up to date so the connection goes smoothly. # Live Chat Source: https://docs.heyy.io/channels/live-chat Embed a Live Chat widget on your website for support, information, and more, with full Heyy features like Inbox, automations, and AI Employees. Live chat channel Live Chat is a widget you embed on your website so visitors can chat with you directly. Use it for customer support, FAQs, lead capture, or any conversation you want to have on your site. All chats appear in your Heyy [Inbox](/quick-start/inbox), and you get the same [automations](/quick-start/automations/triggers), [AI Employees](/quick-start/ai-employees), [contacts](/quick-start/contacts), and [campaigns](/quick-start/campaigns) as with WhatsApp, Instagram, and other channels, no separate tool. ## Connecting a Live Chat channel 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **Live Chat**. 4. In the dialog, fill in: * **Name** (required): A label for this channel (e.g. "Website support"). * **Primary color**: The accent color for the widget (default is pink). You can change this later. * **Websites** (optional): Domains where the widget is allowed to load (e.g. `example.com`). Leave empty to allow all domains, or add domains for tighter security. 5. Click **Create**. You’ll be taken to the channel’s edit page to configure content, style, security, visibility, and installation. ## Editing and updating your Live Chat Open the channel from **Settings → Channels** and use the tabs to change how the widget looks and behaves. ### Content * **Title**: The heading shown in the widget. * **Message placeholder**: Placeholder text in the message input (e.g. "Ask a question..."). * **Initial messages**: Messages shown when the chat opens (e.g. "Hello, how can I help you today?"). * **Suggested messages**: Quick-reply buttons visitors can tap. * **Profile picture**: Avatar for the widget. * **Remove Powered by**: Option to hide the Heyy branding. ### Style * **Theme**: Light or dark. * **Primary color**: Widget accent color. * **Alignment**: Position the widget on the left or right. * **Direction**: Left-to-right or right-to-left for RTL languages. * **Position**: Fine-tune the widget’s position (X/Y). ### Security * **Allowed domains**: List of domains where the widget may load. Restrict this to your real sites for security. * **Secret keys**: Keys for server-side user identification using our SDK (coming soon!). ### Visibility * **Hidden paths**: URL paths on your site where the widget is hidden (e.g. thank-you or checkout pages). ### Installation * **Embed code**: A script snippet with your **widget ID** that you add to your website. Copy it from this tab. * Platform-specific steps are available for **Code**, **Webflow**, **WordPress**, **Framer**, **Wix**, and **Squarespace**. After you add the script to your site, the widget loads from Heyy and appears according to your content and style settings. ## Removing a Live Chat channel Deleting a Live Chat channel is **irreversible**. The widget will stop working on all sites where it’s embedded. Existing conversations and history for that channel may be lost or no longer accessible. If you might need the data later, export or back up before deleting. Remove the embed code from your site if you no longer want the widget to appear. To remove a Live Chat channel, go to **Settings → Channels**, open the Live Chat channel, and use the delete or remove option for that channel. ## Use cases * **Customer support**: Answer questions and resolve issues directly on your site. All chats land in your [Inbox](/quick-start/inbox). * **Information and FAQs**: Use initial and suggested messages, plus an [AI Employee](/quick-start/ai-employees), to guide visitors to the right information. * **Lead capture**: Start conversations, capture [contacts](/quick-start/contacts) and attributes, and follow up with [campaigns](/quick-start/campaigns) or other channels (e.g. [WhatsApp](/channels/whatsapp)). * **Automations**: Use [Live Chat triggers](/quick-start/automations/triggers) and [Live Chat actions](/quick-start/automations/live-chat-actions) (e.g. send message, wait for reply) for welcome flows, routing, or follow-ups. * **AI Employees**: Assign an [AI Employee](/quick-start/ai-employees) to handle first-line replies 24/7. Restrict **allowed domains** so the widget only loads on your real sites. Use **hidden paths** to hide the widget on specific pages (e.g. thank-you or checkout). Test the widget on a staging domain before going live. # SMS Source: https://docs.heyy.io/channels/sms Connect a Twilio phone number to Heyy to send and receive SMS messages in your Inbox, automations, and campaigns. SMS channel SMS lets you text with customers using a **Twilio** phone number, directly from your Heyy [Inbox](/quick-start/inbox). You can also use the same Heyy features you use on other channels, like [automations](/quick-start/automations/triggers), [AI Employees](/quick-start/ai-employees), [contacts](/quick-start/contacts), and [campaigns](/quick-start/campaigns). ## Before you connect (Twilio prerequisites) To use SMS in Heyy, you’ll need: 1. A **Twilio account** 2. A **Twilio phone number** that can send/receive SMS (you buy this inside Twilio) Twilio charges separately for phone numbers and SMS usage. Heyy connects to Twilio — your SMS costs are billed by Twilio. ## Connecting an SMS channel (Twilio) 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **SMS**. 4. In the dialog, fill in: * **Name** (required): A label for this channel (e.g. "Support SMS"). * **Twilio phone number** (required): The number you purchased in Twilio. * **Twilio credentials** (required): Your Twilio account credentials (as shown in the Heyy setup). 5. Click **Create** (or **Connect**) to finish. Once connected, Heyy will start receiving inbound SMS and sending outbound SMS through your Twilio number. ## How SMS conversations work in Heyy * **Inbound messages**: When someone texts your Twilio number, the conversation appears in your Heyy Inbox. * **Outbound messages**: When you reply in Heyy, we send the SMS through Twilio. * **Contacts**: Phone numbers are used to create/identify [contacts](/quick-start/contacts). ## Common setup notes * **Use a fresh Twilio number**: If the number is already wired to another system, inbound messages may not reach Heyy. * **Deliverability & compliance**: SMS rules vary by country and use case. If Twilio flags traffic or requires additional steps (like registration), complete that in Twilio. ## Automations, AI Employees, and campaigns After the SMS channel is connected, you can: * Use [automations](/quick-start/automations/triggers) to send replies, route conversations, tag contacts, and notify your team * Assign an [AI Employee](/quick-start/ai-employees) to handle first-line SMS replies * Send SMS via [campaigns](/quick-start/campaigns) (where available in your workspace) ## Removing an SMS channel Deleting an SMS channel is **irreversible**. Inbound messages to that Twilio number will no longer appear in Heyy, and you won’t be able to send messages from Heyy using that channel. If you might need the data later, export or back up before deleting. To remove an SMS channel, go to **Settings → Channels**, open the SMS channel, and use the delete or remove option. ## Use cases * **Customer support**: Let customers text you and manage everything in your [Inbox](/quick-start/inbox). * **Order updates**: Send status notifications or follow-ups using [automations](/quick-start/automations/triggers). * **Re-engagement**: Reach out to existing customers using [campaigns](/quick-start/campaigns). * **AI-first support**: Use an [AI Employee](/quick-start/ai-employees) to reply instantly, escalate to a human, or collect info before handoff. If inbound SMS aren’t showing up, double-check that you purchased the number in Twilio and that the number is the same one connected in Heyy. # WhatsApp Source: https://docs.heyy.io/channels/whatsapp Connect your WhatsApp business number to handle conversations in your Heyy Inbox and send outbound messages, with automations, AI Employees, and campaigns. WhatsApp channel WhatsApp lets you handle conversations from WhatsApp directly in your Heyy [Inbox](/quick-start/inbox). Your customers can message you on WhatsApp while you use the same [automations](/quick-start/automations/triggers), [AI Employees](/quick-start/ai-employees), [contacts](/quick-start/contacts), and [campaigns](/quick-start/campaigns) as with Messenger, Instagram, and Live Chat. You can also send WhatsApp [campaigns](/quick-start/campaigns) to multiple contacts, or offer WhatsApp as a follow-up channel in [Live Chat](/channels/live-chat) so customers can take the conversation with them. You can connect WhatsApp in two ways: **Cloud API** (number hosted by Meta, manage only in Heyy) or **Coexistence** (use the WhatsApp Business App on your phone and the Heyy Inbox at the same time). Each option has different requirements and a different Meta onboarding flow. ## Cloud API Cloud API is the standard integration. Your number is hosted by Meta and you manage all conversations through Heyy. The number **cannot** be used on the WhatsApp mobile app once connected. This option is recommended for most users and offers the most stable connection. ### Requirements Before you connect with Cloud API, ensure: * **New or clean number**: A valid phone number that can receive an SMS or voice call for verification. *Important:* This number **cannot** be active on the WhatsApp mobile app (Standard or Business) once the connection is complete. * **Meta Business Portfolio**: Your [Meta Business Portfolio](https://business.facebook.com) must be ready with [**Business Info**](https://business.facebook.com/latest/settings/business_info) fully completed. Incomplete info may cause connection restrictions—complete your [Business Info](https://business.facebook.com/latest/settings/business_info) before starting the onboarding. If you already started and the number didn’t connect fully, complete [Business Info](https://business.facebook.com/latest/settings/business_info) and then [contact Heyy support](https://heyy.io/contact-us). ### Connecting 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **WhatsApp**. 4. Click **Connect Number** in the dialog. 5. In the Meta flow, choose **“Create a WhatsApp Business account”** and follow the steps below (pick Portfolio, fill business details, add or get a number, verify, then continue to the end). Clicking **Connect Number** opens **Meta’s WhatsApp onboarding flow**. You’ll create or link a WhatsApp Business account, add or get a phone number, and verify it. When the flow completes, Heyy creates the channel and your WhatsApp channel appears in **Settings → Channels**. You’ll manage all conversations through Heyy; the number is hosted by Meta and is not used on the mobile app. ### About Meta’s onboarding flow For Cloud API, Meta’s flow creates a new WhatsApp Business account (hosted by Meta). Follow these steps: 1. **Pick Business Portfolio**: Select your [Meta Business Portfolio](https://business.facebook.com) (or create one and complete [Business Info](https://business.facebook.com/latest/settings/business_info)). 2. **Create a WhatsApp Business account**: In the WhatsApp Business account setup, select the **“Create a WhatsApp Business account”** option. 3. **Fill in business details**: Enter your business details. The **display name** should match or contain the name of your [Business Portfolio](https://business.facebook.com/latest/settings/business_info). 4. **Choose how to add a number**: * **Use a display name only**: Get a free **+1 555** Meta phone number. *Note:* You cannot send templates or initiate conversations with these numbers; they are mainly for testing. * **Add a new number**: Select **“Add a new number”** and enter a phone number that can receive an SMS or phone call for verification. This number must not be active on the WhatsApp mobile app once connected. 5. **Verify the phone number**: Enter the OTP you received (SMS or voice call) to verify the number. 6. **Finish the flow**: Continue with **Next**, **Continue**, and any remaining steps until the flow is complete. For more on WhatsApp Business Platform (Cloud API), see Meta’s [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api) and [Embedded Signup](https://developers.facebook.com/docs/whatsapp/embedded-signup) documentation. If the connection fails or your number doesn’t connect fully, check that your [Business Info](https://business.facebook.com/latest/settings/business_info) is complete and that the number isn’t active on the WhatsApp mobile app. For help, [contact Heyy support](https://heyy.io/contact-us). ## Coexistence Coexistence lets you use the **WhatsApp Business App** on your smartphone while managing conversations through the **Heyy Inbox** at the same time. Useful if you rely on the mobile app for voice calls or other app-only features. Stability is generally lower than Cloud API. ### Requirements Before you connect with Coexistence, ensure: * **WhatsApp Business App not linked elsewhere**: Your existing WhatsApp Business App must **not** be connected to any other Business Platform. Check and disconnect if needed: * **Android:** In the WhatsApp Business App, open the **3 dots** (top right) → **Settings** → **Account** → **Business Platform**. If an app is listed, tap it and **Disconnect**. You’re ready if you see “Connect to the Business Platform”. * **iPhone:** In the WhatsApp Business App, go to **Settings** → **Account** → **Business Platform**. If an app is listed, tap it and **Disconnect**. You’re ready if you see “Connect to the Business Platform”. * **App version**: WhatsApp Business app version **2.24.17** or higher. * **Meta Business Portfolio**: Your [Meta Business Portfolio](https://business.facebook.com) must be fully completed with [**Business Info**](https://business.facebook.com/latest/settings/business_info). Your display name should match your business Portfolio name or contain it. ### Connecting 1. Go to **Settings → Channels** in your Heyy dashboard. 2. Click **Add Channel**. 3. Select **WhatsApp**. 4. Click **Connect Number** in the dialog. 5. In the Meta flow, follow the Coexistence steps below (Connect a WhatsApp Business App, enter number, scan QR or enter code, then select “Don’t share chats”). Clicking **Connect Number** opens **Meta’s WhatsApp onboarding flow**. When you choose Coexistence, you’ll link your existing WhatsApp Business number (the one on your phone) to Heyy. When the flow completes, Heyy creates the channel. You can keep using the WhatsApp Business App on your phone for voice calls and other features while managing chats in the Heyy Inbox. ### About Meta’s onboarding flow For Coexistence, Meta’s flow connects your existing WhatsApp Business App to Heyy. Follow these steps: 1. Select your [Meta Business Portfolio](https://business.facebook.com) (or create one and complete [Business Info](https://business.facebook.com/latest/settings/business_info)). 2. In the WhatsApp Business account field, select the **“Connect a WhatsApp Business App”** option. 3. Enter the phone number that is connected to your WhatsApp Business App. 4. On your phone, open the WhatsApp Business App and either scan the QR code shown on screen or copy and enter the code. You may also receive a WhatsApp message from Facebook with a quick link to open the camera for the QR scan. 5. After scanning or entering the code, when prompted, select **“Don’t share chats”**. *Important:* Heyy does not support sharing chats with the app; choosing to share chats may lead to connection errors. 6. Continue with **Next**, **Continue**, and any remaining steps until the flow is complete. If the connection fails or you don’t see Coexistence as an option, ensure your WhatsApp Business App is disconnected from any other Business Platform and that your [Business Info](https://business.facebook.com/latest/settings/business_info) is complete. For help or to switch between Cloud API and Coexistence, [contact Heyy support](https://heyy.io/contact-us). ## Editing Open the channel from **Settings → Channels** and use the **Profile** tab. Changes are reflected in a live preview of your WhatsApp Business profile. ### Profile * **Internal name**: A label for this channel inside Heyy (e.g. “Support WhatsApp”). You can edit this at any time. * **Display name**: The business name shown to customers on WhatsApp. This is read-only and comes from your Meta Business profile; to change it, use the link button to open [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/phone_numbers/) in Meta Business Suite and edit the number’s display name there. * **Profile photo**: The profile picture for your WhatsApp Business account. You can upload or remove an image. * **Category**: Your business vertical (e.g. Retail, Health, Finance). Choose the option that best matches your business. * **Description**: A short business description. Supports WhatsApp-style formatting (e.g. bold, italics). * **Address**: Your business address (optional). * **Email**: Your business email (optional). * **Websites**: Up to two website URLs (optional). * **About**: Short “about” text shown on your profile (max 140 characters). Saving the form updates your WhatsApp Business profile; the preview on the right shows how it will look to customers. ## Removing Disconnecting or deleting a WhatsApp channel is **irreversible**. Heyy will no longer send or receive messages for that number. Existing conversations and history for that channel may be lost or no longer accessible. If you might need the data later, export or back up before disconnecting. To remove a WhatsApp channel, go to **Settings → Channels**, open the WhatsApp channel, and use the disconnect or delete option for that channel. ## Use cases * **Customer support**: Answer questions and resolve issues on WhatsApp. All chats appear in your [Inbox](/quick-start/inbox). * **Marketing and follow-up**: Use [campaigns](/quick-start/campaigns) to reach contacts on WhatsApp, or offer WhatsApp as a follow-up channel (e.g. from [Live Chat](/channels/live-chat)) so customers can continue the conversation where they prefer. * **Automations**: Use [WhatsApp triggers](/quick-start/automations/triggers) and [WhatsApp actions](/quick-start/automations/whatsapp-actions) (e.g. send message, wait for reply) for welcome flows, qualification, or routing. * **AI Employees**: Assign an [AI Employee](/quick-start/ai-employees) to handle first-line replies on WhatsApp 24/7. **Cloud API:** Complete your [Business Info](https://business.facebook.com/latest/settings/business_info) before starting the onboarding and use a number that is not (and will not be) used on the WhatsApp mobile app once connected. **Coexistence:** Ensure your WhatsApp Business App is not connected to any other Business Platform and that your [Business Info](https://business.facebook.com/latest/settings/business_info) is complete. # AI Employees Source: https://docs.heyy.io/quick-start/ai-employees The **AI Employees** page is where you create, train, and manage digital teammates that handle customer conversations. Each AI Employee has a name, role, knowledge base, and optional actions—so you can hire support agents, sales agents, and more, then use them in [Automations](/quick-start/automations/ai-actions) to reply, qualify leads, and route chats. AI Employees ## Left Sidebar – AI Employees List On the left sidebar, you’ll find your **AI Employees** list and a way to hire new ones. ### Switching Between AI Employees * Click an AI employee in the sidebar to open their card. The main workspace updates to show that employee’s name, role, avatar, and tabs. * Each entry shows the employee’s **name** and **role** (e.g. Customer support, Sales agent). Your list is the main way to move between employees. ### Hire AI Employee * **Hire AI Employee** – At the bottom of the sidebar (or as a dedicated entry), click **Hire AI Employee** to create a new AI employee. A new employee is created with a default name and the **Customer support** role, and you’re taken straight to their card to set the name, role, model, and instructions. * If you have no AI employees yet, you may be taken to a dedicated **Hire** page with an empty state and a **Hire AI Employee** button; clicking it creates the first employee and opens their card. Your plan may limit how many AI employees you can have. If you hit the limit, you’ll be prompted to upgrade. *** ## Hiring a New AI Employee To hire a new AI employee: 1. Click **Hire AI Employee** in the left sidebar (or on the Hire page if you have no employees). 2. A new AI employee is created with a default name and the **Customer support** role, and you’re navigated to their card. 3. On the card, open the **Goals and personality** tab and set: * **Name** – A friendly identifier (e.g. Sandra, Alex). * **Role** – Choose a role that matches how this employee should behave. Available roles include: Customer support, Sales agent, Technical support, Life coach, Personal trainer, Travel agent, Recruiter, Financial advisor, Nutritionist, Real estate agent. Changing the role can update the default **Instructions** (persona, principles, constraints). * **Model** – The AI model that powers the employee (e.g. Gemini 2.5 Flash, GPT-4o Mini). Options may include Gemini 2.0 Flash, 2.5 Flash, 2.5 Pro, 3 Pro, 3 Flash, and GPT-4o Mini, 4o, 4.1 Nano, 4.1 Mini, 4.1, and GPT-5 Nano, 5 Mini, 5, 5.1, 5.2 Instant. * **Instructions** – A markdown editor where you define persona, core principles, and constraints. Role templates pre-fill this; you can edit it at any time. 4. Optionally add **Knowledge** (links and documents) and **Tools and integrations** (actions), then click **Set live** when the employee is ready to use in automations. After hiring, the new AI employee appears in the left sidebar. Use the **Goals and personality** tab to refine name, role, model, and instructions before going live. *** ## Main Workspace – AI Employee Card When you select an AI employee, the main workspace shows their **card**: header, tabs, and (on wide screens) the **Playground** on the right. ### Header and Toolbar * **Breadcrumbs** – Navigate back to AI Employees or parent pages. * **Set live** / **Set inactive** – **Set live** activates the AI employee so it can be used in [Automations](/quick-start/automations/ai-actions) (e.g. as an **AI Employee** action). **Set inactive** turns it off so it no longer runs in workflows. * **Retrain** – After you add, edit, or remove knowledge sources, click **Retrain** to rebuild the knowledge base. The button is enabled when training is required. Training status is shown as a badge (e.g. In progress, Trained, Training required, Failed). ### Avatar, Name, and Status * **Avatar** – The employee’s avatar is shown next to the name. You can change it (e.g. refresh seed) from the card; changes save automatically. * **Name** and **Role** – Displayed under the avatar. Edit them in the **Goals and personality** tab. * **Knowledge usage** – Shows how much of the knowledge base quota is used (e.g. X MB / Y MB). The limit depends on your plan. * **Status badge** – **Active** (live) or **Inactive**. * **Training status badge** – In progress, Trained, Training required, Failed, or Untrained. ### Tabs The card has four tabs: * **Goals and personality** – Name, role, model, instructions (persona, principles, constraints), and danger zone (Retire). * **Knowledge** – Links and documents (knowledge base). * **Tools and integrations** – Actions the AI employee can perform (e.g. read contact, update contact, trigger workflow, custom API). * **Performance** – Reserved for future analytics (e.g. response quality, usage). This tab is **coming soon**. *** ## Goals and Personality Tab Use this tab to define **who** the AI employee is and **how** it should respond. ### Name and Role * **Name** – Edit the display name. Changes save when you finish editing (e.g. on blur). * **Role** – Choose from the role list (Customer support, Sales agent, Technical support, Life coach, Personal trainer, Travel agent, Recruiter, Financial advisor, Nutritionist, Real estate agent). Selecting a role can replace the **Instructions** field with a template for that role (persona, tone, principles, constraints). You can edit the instructions after that. ### Model * **Model** – Select which AI model powers the employee (e.g. Gemini 2.5 Flash, GPT-4o Mini). The list includes Gemini and GPT options; your plan may restrict which models are available. Changing the model saves automatically. ### Instructions * **Instructions** – A markdown editor for the employee’s **persona**, **core principles**, and **constraints**. Templates for each role pre-fill this; you can adjust tone (e.g. professional, friendly, solution-oriented), what the employee should and shouldn’t do, and whether to use emojis or avoid speculation. Changes save when you finish editing (e.g. on blur). Every change here affects how the AI employee behaves in the Playground and in automations. ### Danger Zone – Retire * **Retire** – Permanently retire this AI employee. Retired employees are removed from the list and can no longer be used in automations. This action cannot be undone. Use it when an employee is no longer needed. *** ## Knowledge Tab Use this tab to give your AI employee **knowledge** it can use to answer questions. Knowledge is stored as **links** (websites) and **documents** (uploaded files). ### Links * **Add link** – Add a website URL as a knowledge source. In the dialog you can choose to crawl **a single page** or **the whole website**. Submit the URL; the system crawls and indexes the content. The employee can then use this information in replies. * **List** – All link sources are listed. Each item can be **edited** (e.g. change URL or crawl type) or **deleted**. Crawl status (e.g. in progress, done) may be shown. If you have many links, the list may be scrollable or paginated. * **Bulk delete** – Select multiple link or document items and use the contextual action bar to delete them in one go. Use verified, well-structured sources so the AI employee gives accurate and useful answers. After adding or removing sources, click **Retrain** in the header to rebuild the knowledge base. ### Documents * **Add document** – Upload files (e.g. PDF, TXT, DOC, DOCX) or paste **plain text**. Supported formats typically include text files, PDFs, and common office documents. The content is parsed and added to the knowledge base. * **List** – All document sources are listed. Each item can be **edited** (e.g. change name or content) or **deleted**. Bulk delete works the same as for links. Knowledge usage (size) is shown in the card header and counts toward your plan’s knowledge limit. *** ## Tools and Integrations (Actions) Tab Use this tab to define **actions** the AI employee can perform beyond replying—for example reading or updating contact data, triggering a workflow, or calling a custom API. ### Action Types * **Read contact** – Let the employee read contact attributes (e.g. name, email, custom attributes) during a conversation. * **Update contact** – Let the employee update contact attributes (e.g. set a label, update a custom field). * **Trigger workflow** – Let the employee start an [Automation](/quick-start/automations/triggers) (e.g. assign chat, send notification). * **Custom** – Define a custom action (e.g. call an external API, check order status). You configure the request and how the response is used. ### Adding and Managing Actions * **Add action** – Click **Add action** (or the trigger button in the Actions section). Choose the action type, configure parameters (e.g. which workflow to trigger, which contact fields to read or update), and save. The new action appears in the list. * **List** – Each action is shown with its name/type. Click an action to **edit** it (e.g. change parameters). Use the **⋮** menu to **edit** or **delete**. * Changes save when you confirm the dialog. The AI employee can use these actions when it’s used in an automation (e.g. [AI Employee action](/quick-start/automations/ai-actions)). *** ## Performance Tab The **Performance** tab is reserved for future analytics. You’ll be able to track response quality, usage, and conversation trends. This feature is **coming soon**. *** ## Playground (Right Panel) When an AI employee is selected, the **Playground** appears on the right (on large screens). Use it to **test** the employee before or after going live. If no contact is selected in the Playground, the AI employee’s **knowledge base** and **actions** (e.g. Read contact, Update contact, Trigger workflow) will not work. Select a contact from the dropdown so the employee can use its knowledge and actions during the test conversation. ### Contact and Chat * **Contact** – Choose a contact from your [Contacts](/quick-start/contacts) so the conversation is run in the context of that contact (e.g. the employee can use contact attributes if you’ve added **Read contact** or **Update contact** actions). * **Chat** – Type a message and send. The AI employee replies using its **Goals and personality** (instructions) and **Knowledge**. You can send several messages to see how it behaves, then adjust instructions or knowledge and try again. The Playground does not send real messages to the contact’s channels; it’s for testing only. When you’re satisfied, click **Set live** so the employee can be used in automations. *** ## Set Live, Set Inactive, and Retrain * **Set live** – Activates the AI employee. Once live, you can use it in [Automations](/quick-start/automations/ai-actions) (e.g. as the **AI Employee** action in a workflow). Only live employees appear as options there. * **Set inactive** – Deactivates the employee. It stays in your list but no longer runs in automations. Use this to pause an employee without retiring it. * **Retrain** – After you add, edit, or remove knowledge sources, the system may mark the employee as **Training required**. Click **Retrain** to rebuild the knowledge base. While training is **In progress**, wait until it finishes. If status is **Failed**, check the knowledge sources and try again or contact support. *** ## Key Benefits of AI Employees * **Centralized hub** – All AI employees in one list; switch between them from the left sidebar. * **Goals and personality** – Set name, role, model, and instructions (persona, principles, constraints) so each employee behaves consistently and on-brand. * **Knowledge base** – Add links (single page or full site) and documents so employees answer from your content; retrain after changes. * **Actions** – Extend employees with read/update contact, trigger workflow, or custom API actions and use them in [Automations](/quick-start/automations/ai-actions). * **Playground** – Test conversations with a chosen contact before going live. * **Live / Inactive** – Control which employees are available in automations without deleting them. *** ## Getting Started Tips * Start by clicking **Hire AI Employee** to create your first employee; you’ll land on their card to set name, role, and instructions. * Pick a **role** that fits the use case (e.g. Customer support, Sales agent); the instructions template will give you a starting point. * Add **Knowledge** (links and documents) so the employee can answer from your docs, FAQs, or site; then click **Retrain**. * Use the **Playground** to test replies, then click **Set live** when you’re happy. * Add **Actions** (e.g. read contact, trigger workflow) in the **Tools and integrations** tab, then use the employee in an [Automation](/quick-start/automations/ai-actions) so it can run in real conversations. * Use **Set inactive** to pause an employee without retiring it; use **Retire** in the danger zone when you no longer need that employee. # AI Actions Source: https://docs.heyy.io/quick-start/automations/ai-actions ## AI Employee AI employee action Hands the conversation over to an AI employee you choose. The AI replies in the chat until one of your exit conditions is met or the reply timeout expires. Use this to automate first-line support, qualify leads, or collect information before an agent takes over. ### Fields * **Channel** (required): Select the channel where the AI employee will reply. * **AI Agent** (required): Choose which AI employee handles the conversation. * **Context** (optional): Extra instructions or context for the AI (e.g. product info, policies). * **Exit conditions** (optional): Define when the AI should stop and hand off (e.g. when the contact asks for an agent or says “goodbye”). * **Reply timeout** (optional): Toggle and set a duration after which the AI stops waiting for a reply and the automation can continue. ### Use cases * **First-line support:** Use the action to hand the chat to an AI employee that answers FAQs and collects info; add exit conditions (e.g. “ask for agent”) so the automation continues to Assign chat or Move chat when the contact wants a human. * **Lead qualification:** Let the AI ask qualifying questions in the chat; use exit conditions and reply timeout so the flow continues to Set attribute, Add label, or Assign chat based on the AI’s conversation. * **Collect info before handoff:** Use Context to give the AI product or policy details; when the AI finishes or times out, use the next steps to assign the chat and optionally send a summary or Set attribute with what was collected. *** ## AI Intention Recognition AI intention action Uses AI to classify the contact’s intent into one of the options you define, and stores the result in a workflow variable or contact attribute. Use this to route conversations, tag contacts, or branch your automation based on what the contact wants (e.g. “support”, “sales”, “complaint”). ### Fields * **Context** (optional): Description or instructions so the AI understands the conversation (e.g. “Customer support chat”). * **Field** (required): The workflow variable or contact attribute where the matched option will be saved. * **Options** (required): List of possible intents (one per line). The AI picks the best-matching option; you can add up to 20. ### Use cases * **Route by intent:** Use the action to classify the contact’s message (e.g. “support”, “sales”, “complaint”) and save to a variable; add a Condition right after to Assign chat, Move chat, or send different messages based on the stored value. * **Tag contacts for campaigns:** Save the matched option to a contact attribute (e.g. “intention”) so you can segment or target contacts in campaigns and views based on what they wanted. * **Branch without full AI chat:** When you only need to detect intent (not hold a long conversation), use AI Intention Recognition after “Save text reply to” and branch the automation on the result (e.g. support vs. sales flow). *** ## AI Transform AI transform action Uses AI to transform text from a workflow variable or contact attribute according to your instructions, and writes the result to another variable or attribute. Use this to summarize messages, translate, extract key info, or reformat text for downstream steps. ### Fields * **Input** (required): The workflow variable or contact attribute that contains the source text. * **Instructions** (required): What you want the AI to do (e.g. “Summarize in one sentence”, “Extract the email address”). * **Output** (required): The workflow variable or contact attribute where the transformed text will be saved. ### Use cases * **Summarize or extract from the reply:** Use the action with Input = the variable where you saved the contact’s reply (e.g. from “Save text reply to”); set Instructions to “Summarize in one sentence” or “Extract the order number”, then use the Output in the next message or Condition. * **Translate for internal use:** Set Input to the contact’s message (variable or attribute) and Instructions to “Translate to \[language]”; save Output to a variable or attribute so agents or later steps see the translation. * **Reformat for downstream steps:** Use AI Transform to clean or structure text (e.g. “Extract only the email address”, “Convert to bullet points”) and save to a variable or attribute for use in an API call, template, or contact record. # Apps Actions Source: https://docs.heyy.io/quick-start/automations/apps-actions ## API Apps actions Calls an external HTTP API when the automation runs. You set the URL, method, optional headers and body, and optionally map parts of the response to workflow variables or contact attributes. Use this to integrate with your own systems (e.g. CRM, ticketing, webhooks) or to fetch data for use in later steps. ### Fields * **URL** (required): The full URL of the API endpoint. You can use workflow variables and contact fields/attributes in the URL via the dropdown. * **Headers** (optional): One or more HTTP headers (key–value pairs). You can use workflow variables and contact fields/attributes in values. * **Method** (required): The HTTP method (e.g. GET, POST, PUT, PATCH, DELETE). * **Body** (optional): The request body (e.g. JSON). Shown for methods that support a body. You can use workflow variables and contact fields/attributes. * **Response mapping** (optional): Map parts of the API response to workflow variables or contact attributes. For each mapping, set a [JSON path](https://www.rfc-editor.org/rfc/rfc9535.html) (e.g. `$.data.id`) and the variable or attribute to save the value to. ### Use cases * **Store API results:** Use response mapping to save parts of the response (e.g. order ID, ticket number) to workflow variables or contact attributes so you can use them in conditions, the next message, or Set Attribute. * **Integrate with external systems:** Call your CRM, ticketing system, or webhooks from the automation (e.g. create a ticket when a chat is created, sync contact data) and optionally map the response for use in later steps. * **Fetch data for later steps:** Call an API to get data (e.g. product info, inventory), map the response with [JSON path](https://www.rfc-editor.org/rfc/rfc9535.html) (e.g. `$.data.id`), and use the variables or attributes in the next action (e.g. Condition, message body). Use [JSONPath Online Evaluator](https://jsonpath.com/) to test your response mapping. # Campaigns Actions Source: https://docs.heyy.io/quick-start/automations/campaigns-actions ## Add to Campaign Add to campaign action Adds the contact in the current chat to a campaign you choose. The contact will then receive the campaign’s messages according to the campaign’s schedule and rules. Use this when the contact has opted in or qualified (e.g. after they reply “Yes” or complete a form) so they are included in the campaign audience. ### Fields * **Campaign** (required): Select the campaign to add the contact to. You can search by campaign name. ### Use cases * **After explicit opt-in:** Use Add to Campaign after the contact confirms (e.g. replies “Yes” to a consent question or taps a subscribe button); add a Condition before so it runs only when the reply matches your criteria. * **After qualification:** After AI Intention Recognition or a Condition (e.g. “intention = sales”), use Add to Campaign so the contact receives the campaign’s messages according to its schedule and rules. * **With Subscribe:** Combine Add to Campaign with Subscribe when the contact must be subscribed to receive campaign messages (e.g. after they opt in or complete a form). *** ## Remove from Campaign Remove from campaign action Removes the contact in the current chat from a campaign you choose. The contact will no longer receive that campaign’s messages. Use this when the contact opts out of a campaign (e.g. replies “Stop”) or when they no longer belong in the audience (e.g. they’ve already converted). ### Fields * **Campaign** (required): Select the campaign to remove the contact from. You can search by campaign name. ### Use cases * **Opt-out keywords:** In a “New incoming message” automation, add a Condition that checks for opt-out keywords (e.g. “stop”, “unsubscribe”), then use Remove from Campaign so the contact no longer receives that campaign’s messages. * **Explicit opt-out:** When the contact explicitly opts out of a campaign (e.g. replies “Stop” or taps “Unsubscribe”), use Remove from Campaign in the branch that handles that request. * **Logic-based removal:** When your logic determines the contact should no longer receive the campaign (e.g. they’ve converted, churned, or no longer fit the audience), use Remove from Campaign so they are excluded from future messages. # Chats Actions Source: https://docs.heyy.io/quick-start/automations/chats-actions ## Mark Chat As Read Mark chat as read action Marks the chat’s messages as read in the current conversation. Use this to clear the unread state after an automation has handled the chat or before handing off to an agent, so the inbox shows the chat as read. ### Fields * **Channel** (required): Select the channel where the chat lives. ### Use cases * **After sending a reply:** Use Mark Chat As Read after a message action so the inbox shows the chat as read and agents know the automation has already responded. * **Before assigning:** Use it before Assign Chat so the agent sees the chat as already read and doesn’t treat it as new. * **After handling in automation:** Use it when the automation has fully handled the conversation so the unread badge is cleared and the thread is tidy. *** ## Open Chat Open chat action Reopens a closed chat so the contact can send messages again and agents can see it in the inbox. Use this when you want to bring a previously closed conversation back (e.g. after a follow-up campaign or when the contact replies again). ### Fields * **Channel** (required): Select the channel where the chat lives. * **Trigger workflows** (optional): When enabled, workflows that listen for “New & reopened chat” or “Reopened chat” can run when the chat is opened. ### Use cases * **Welcome-back flow:** Turn on “Trigger workflows” so a “Reopened chat” or “New & reopened chat” automation runs when the chat is opened (e.g. send a welcome-back message or reassign). * **Re-engagement after campaign:** Use Open Chat after a campaign or manual trigger to bring the conversation back, then let a trigger automation handle the first message. * **Reopen after resolution:** Use Open Chat when you want to bring a previously closed chat back into the inbox without the contact sending a new message (e.g. follow-up from your side). *** ## Snooze Chat Snooze chat action Snoozes the chat so it is hidden from the active inbox until it is unsnoozed or the contact sends a new message. Use this to temporarily set a chat aside (e.g. waiting for the contact to reply or for an external step) without closing it. ### Fields * **Channel** (required): Select the channel where the chat lives. ### Use cases * **Waiting on the contact:** Use Snooze when you’ve asked a question or sent a link and are waiting for a reply; the chat reappears when they message again or when it is unsnoozed. * **Waiting on an external step:** Use Snooze when the flow depends on an API call, delay, or manual step so the chat is out of the way until the next action runs. * **Temporary set-aside:** Use Snooze to hide the chat from the active inbox without closing it, so it doesn’t clutter the queue until it’s ready to be handled again. *** ## Close Chat Close chat action Closes the current conversation. The chat moves out of the active inbox; the contact can reopen it by sending a new message. Use this to end a conversation after resolution, or before a delayed follow-up (e.g. with a “Chat closed” trigger). ### Fields * **Channel** (required): Select the channel where the chat lives. * **Trigger workflows** (optional): When enabled, workflows that listen for “Chat closed” will run when this chat is closed. ### Use cases * **Run a “Chat closed” automation:** Enable “Trigger workflows” so a workflow listening for “Chat closed” runs when this action closes the chat (e.g. send a survey or start a follow-up campaign). * **After resolution:** Use Close Chat when the conversation is resolved so the chat leaves the active inbox and the contact can reopen by sending a new message. * **Before delayed follow-up:** Close the chat after resolution and use a “Chat closed” trigger with a Delay to start a follow-up flow (e.g. NPS or re-engagement) later. *** ## Assign Chat Assign chat action Assigns the chat to a specific user, to a pool of users (auto-assign), or clears the assignment. Use this to route the conversation to the right agent or team after qualification, or to reset assignment so the chat can be reassigned. ### Fields * **Channel** (required): Select the channel where the chat lives. * **Type** (required): Choose how to assign: assign to a specific user, auto-assign to one of several users (e.g. least open chats), or reset assignment. * **User** (required if type is “Specific user”): Select the user to assign the chat to. * **Users** (required if type is “Auto assign”): Select the users in the pool; the system assigns to one of them (e.g. by least open chats). * **Trigger workflows** (optional): When enabled, workflows that listen for “Chat assigned” will run when this assignment is applied. ### Use cases * **Load balancing:** Use “Auto assign” with a pool of users so the system assigns the chat to one of them (e.g. by least open chats) for even distribution. * **Route by qualification:** Use “Specific user” when a Condition or AI Intention has already determined who should handle the chat (e.g. assign to a specialist). * **Run “Chat assigned” automations:** Enable “Trigger workflows” so workflows listening for “Chat assigned” run when this assignment is applied (e.g. notify the agent or log the assignment). *** ## Move Chat Move chat action Moves the chat to a specific inbox, to one of several inboxes (auto-assign), or clears inbox assignment. Use this to route the conversation to the right queue or team (e.g. sales vs support) or to reset which inbox the chat is in. ### Fields * **Channel** (required): Select the channel where the chat lives. * **Type** (required): Choose how to move: to a specific inbox, auto-assign to one of several inboxes, or reset inbox assignment. * **Inbox** (required if type is “Specific inbox”): Select the inbox to move the chat to. * **Inboxes** (required if type is “Auto assign”): Select the inboxes in the pool; the system moves to one of them (e.g. by least open chats). * **Trigger workflows** (optional): When enabled, workflows that listen for “Chat moved” will run when this move is applied. ### Use cases * **Route by team or queue:** Use Move Chat to send the conversation to the right inbox (e.g. Support, Sales) so the right team sees it; use Assign Chat when routing by person. * **Load balance across inboxes:** Use “Auto assign” with a pool of inboxes so the system moves the chat to one of them (e.g. by least open chats) for even distribution. * **Move then assign:** Use Move Chat and Assign Chat in sequence (e.g. move to Support inbox, then assign to a specific agent) when you need both queue and person routing. # Contacts Actions Source: https://docs.heyy.io/quick-start/automations/contacts-actions ## Subscribe Subscribe action Marks the contact as subscribed so they can receive messages (e.g. campaigns, notifications). Use this when the contact has opted in—for example, after they confirm in chat or complete a form—so they are eligible for outbound messaging. ### Fields This action has no configurable fields. Adding it to your automation is enough to subscribe the contact. ### Use cases * **After explicit opt-in:** Use the action after the contact replies “Yes” to a consent question or taps a subscribe button; add a Condition before Subscribe so it runs only when the reply matches your consent criteria. * **Post-qualification subscribe:** After AI Intention Recognition or a Condition (e.g. “intention = sales”), use Subscribe so the contact is eligible for sales campaigns or follow-up messages. * **Form or campaign completion:** In an automation triggered by a campaign or manual trigger, use Subscribe after the contact has completed a form or confirmed interest so they receive future messages. *** ## Unsubscribe Unsubscribe action Marks the contact as unsubscribed so they no longer receive outbound messages (e.g. campaigns). Use this when the contact opts out—for example, when they reply “Stop” or ask to be removed—so they are excluded from future messaging. ### Fields This action has no configurable fields. Adding it to your automation is enough to unsubscribe the contact. ### Use cases * **Opt-out keywords in chat:** In a “New incoming message” automation, add a Condition that checks for opt-out keywords (e.g. “stop”, “unsubscribe”, “remove me”), then use Unsubscribe so the contact no longer receives campaigns. * **After contact requests removal:** When the contact explicitly asks to be removed from a list or to stop messages, use Unsubscribe in the branch that handles that request (e.g. after AI employee or a Condition). * **Campaign or flow opt-out:** In a campaign or follow-up flow, when the contact taps “Unsubscribe” or replies with an opt-out, use the Unsubscribe action so they are excluded from future outbound messaging. *** ## Set Attribute Set attribute action Sets one or more contact attributes (or built-in fields like first name, last name, email, phone) to values you choose. Values can be fixed text or built from workflow variables, contact fields, and attributes. Use this to store data on the contact (e.g. preference, order ID, last interaction) for later use in conditions, messages, or campaigns. ### Fields * **Attributes** (required): Add one or more attribute–value pairs. For each pair, pick the attribute (or built-in field) to set and the value. You can use workflow variables, contact fields, and attributes via the dropdown or by typing placeholders. ### Use cases * **Store the contact’s reply on their profile:** After a trigger or message action that has “Save text reply to” or “Save file reply to”, use Set Attribute to write that value (or a transformed value) to a contact attribute so it appears on their profile and in campaigns/views. * **Save qualification or preference:** After AI Intention Recognition or a Condition, use Set Attribute to store the result (e.g. “intention”, “preference”, “language”) on the contact so later automations, conditions, or campaigns can use it. * **Persist data from an API or step:** After an API action or AI Transform, use Set Attribute to save the result to a contact attribute (e.g. order ID, ticket number) so agents or other flows can see it. *** ## Clear Attribute Clear attribute action Clears one or more contact attributes (or built-in fields like first name, last name) so they no longer hold a value. Use this when you want to reset data on the contact—for example, before collecting it again or when the contact has requested removal of stored data. ### Fields * **Attributes** (required): Select the attributes (or built-in fields) to clear. You can select multiple. ### Use cases * **Re-ask for information:** Before a message action that asks a question and saves the reply to an attribute, use Clear Attribute on that attribute so you don’t reuse an old value (e.g. clear “preference” before asking again). * **Contact requests data removal:** When the contact opts out of having certain data stored (e.g. GDPR or preference), use Clear Attribute in the branch that handles the request so the selected attributes are cleared. * **Reset built-in or custom fields:** Clear built-in fields (e.g. first name, last name) or custom attributes when your process requires a clean slate (e.g. re-onboarding, data correction flow). *** ## Add Label Add label action Adds one or more labels to the contact. Labels help you organize and filter contacts (e.g. “VIP”, “Support”, “Campaign X”). Use this to tag the contact based on behavior, qualification, or segment so you can target them in campaigns or route them in the inbox. ### Fields * **Labels** (required): Select the labels to add to the contact. You can select multiple. ### Use cases * **Tag after qualification:** After AI Intention Recognition or a Condition (e.g. “intention = support”), use Add Label to tag the contact (e.g. “Support”, “VIP”) so they appear in the right views or receive the right campaigns. * **Segment by behavior or source:** Use Add Label after another action (e.g. campaign entry, form submit, or Set attribute) to tag the contact (e.g. “Campaign X”, “Lead”) for segmentation and targeting. * **Multiple labels in one step:** Add several labels in one action (e.g. “Support” + “Urgent”) so the contact is categorized for routing, reporting, or campaign filters. *** ## Remove Label Remove label action Removes one or more labels from the contact. Use this when the contact no longer fits a segment (e.g. they’ve churned, completed a campaign, or asked to be removed from a list) so they are no longer targeted or filtered by those labels. ### Fields * **Labels** (required): Select the labels to remove from the contact. You can select multiple. ### Use cases * **After unsubscribe or topic opt-out:** When the contact unsubscribes or opts out of a topic, use Remove Label so they are no longer targeted by campaigns or views that filter on that label (e.g. remove “Newsletter”). * **Campaign or flow completion:** After a contact completes a campaign or a specific flow, use Remove Label to remove the campaign or segment label so they don’t receive duplicate or irrelevant messaging. * **Status or segment change:** When the contact’s status changes (e.g. churned, upgraded), use Remove Label to update how they are categorized; the contact remains, only the label is removed. # Facebook Actions Source: https://docs.heyy.io/quick-start/automations/facebook-actions ## Send Message Messenger message action Sends a Facebook Messenger text message to the contact in the current chat. You can add optional quick-reply buttons and choose to wait for a reply, with optional timeout and saving the reply to a variable or attribute. Use this for simple replies, follow-ups, or guided choices in Messenger conversations. ### Fields * **Channel** (required): Select the Facebook Messenger channel to send from. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Quick replies** (optional): Add quick-reply buttons the contact can tap. Optional labels and optional payloads. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Save text reply to** (optional): Save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Reply in the current chat:** Use the action to send a text message in the Messenger conversation (e.g. after a trigger or another action). The body can use variables and attributes; add quick replies if you want the contact to tap a choice. * **Ask and branch on the reply:** Use “Wait for reply” and “Save text reply to”, then add a Condition or AI action to branch the automation (e.g. qualification, routing) based on what the contact replied or tapped. * **Confirm or follow up after another action:** After another step (e.g. Assign chat, Set attribute), use Send Message to confirm or ask a follow-up question in Messenger. *** ## Send Media Messenger media action Sends a Facebook Messenger message with a media header (image, video, or document). You upload a file or paste a URL. You can optionally wait for a reply, set a reply timeout, and save the contact’s reply to a variable or attribute. Use this to send images, videos, or documents in Messenger from an automation. ### Fields * **Channel** (required): Select the Facebook Messenger channel to send from. * **Header** (required): Choose image, video, or document and upload a file or paste a URL. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Save text reply to** (optional): Save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Share a visual or file in Messenger:** Use the action to send an image, video, or document in the Facebook Messenger chat (e.g. brochure, how-to video, form) as part of a support or sales flow. * **Ask and branch after sending media:** Use “Wait for reply” and “Save text reply to” so the next steps (e.g. Condition, Assign) can use the contact’s response to the media you sent. * **Follow up with context:** After another action (e.g. AI employee, Set attribute), use Send Media to deliver a relevant document or visual and optionally wait for the contact’s reply. *** ## Send Buttons Messenger buttons action Sends a Facebook Messenger message with interactive buttons (e.g. postback or URL). You set the body text and add one or more buttons; you can optionally wait for a reply, set a reply timeout, and save the contact’s reply to a variable or attribute. Use this to present clear choices (e.g. “Book now”, “More info”) in Messenger. ### Fields * **Channel** (required): Select the Facebook Messenger channel to send from. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Buttons** (required): Add one or more buttons. Each button has a label and type (e.g. postback, URL). * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t tap a button or reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact taps a button or sends a message. * **Save text reply to** (optional): Save the contact’s reply (button tap or text) to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Present clear choices in Messenger:** Use the action to send a message with buttons (e.g. “Book now”, “More info”, “Talk to sales”) so the contact can tap a choice; use “Save text reply to” to branch the automation on their selection. * **Confirm or collect consent:** After another step (e.g. AI, Set attribute), send a message with “Confirm” and “Cancel” (or similar) and branch the flow based on which button the contact taps. * **Store the choice on the contact:** Save the button label or reply to a contact attribute so you can use it later in the same automation or in campaigns and views. # Instagram Actions Source: https://docs.heyy.io/quick-start/automations/instagram-actions ## Send Message Instagram message action Sends an Instagram Direct message to the contact in the current chat. You can add optional quick-reply buttons and choose to wait for a reply, with optional timeout and saving the reply to a variable or attribute. Use this for replies in Instagram DMs, follow-ups after a comment, or guided choices. ### Fields * **Channel** (required): Select the Instagram channel to send from. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Quick replies** (optional): Add quick-reply buttons the contact can tap. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Save text reply to** (optional): Save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Reply in the current chat:** Use the action to send a text message in the Instagram DM (e.g. after a trigger or another action). The body can use variables and attributes; add quick replies if you want the contact to tap a choice. * **Ask and branch on the reply:** Use “Wait for reply” and “Save text reply to”, then add a Condition or AI action to branch the automation (e.g. qualification, routing) based on what the contact replied or tapped. * **Confirm or follow up after another action:** After another step (e.g. New Instagram comment flow, Set attribute), use Send Message to confirm or ask a follow-up question in the DM. *** ## Send Media Instagram media action Sends an Instagram Direct message with a media attachment (image, video, or document). You upload a file or paste a URL. You can optionally wait for a reply, set a reply timeout, and save the contact’s reply to a variable or attribute. Use this to send images, videos, or documents in Instagram DMs from an automation. ### Fields * **Channel** (required): Select the Instagram channel to send from. * **Media** (required): Choose image, video, or document and upload a file or paste a URL. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Save text reply to** (optional): Save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Share a visual or file in the DM:** Use the action to send an image, video, or document in the Instagram chat (e.g. after inviting a commenter into DMs, or as part of a product or support flow). * **Ask and branch after sending media:** Use “Wait for reply” and “Save text reply to” so the next steps (e.g. Condition, Assign) can use the contact’s response to the media you sent. * **Follow up a comment with media:** In an automation triggered by “New Instagram comment”, use Send Media to deliver a visual or document in the DM (e.g. brochure, link to reel). *** ## Send Buttons Instagram buttons action Sends an Instagram Direct message with interactive buttons. You set the body text and add one or more buttons; you can optionally wait for a reply, set a reply timeout, and save the contact’s reply to a variable or attribute. Use this to present clear choices (e.g. “Book now”, “More info”) in Instagram DMs. ### Fields * **Channel** (required): Select the Instagram channel to send from. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Buttons** (required): Add one or more buttons. Each button has a label and type (e.g. postback, URL). * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t tap a button or reply. * **Wait for reply** (optional): When enabled, the automation pauses until the contact taps a button or sends a message. * **Save text reply to** (optional): Save the contact’s reply (button tap or text) to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Present clear choices in the DM:** Use the action to send a message with buttons (e.g. “Book now”, “More info”, “Talk to sales”) so the contact can tap a choice; use “Save text reply to” to branch the automation on their selection. * **Confirm or collect consent:** After another step (e.g. AI, Set attribute), send a message with “Confirm” and “Cancel” (or similar) and branch the flow based on which button the contact taps. * **Store the choice on the contact:** Save the button label or reply to a contact attribute so you can use it later in the same automation or in campaigns and views. # Live Chat Actions Source: https://docs.heyy.io/quick-start/automations/live-chat-actions ## Send Message Live chat message action Sends a Live Chat message to the contact in the current chat. The body can include workflow variables and contact attributes. You can optionally wait for a reply, set a reply timeout, and save the contact’s text or file reply to a variable or attribute. Use this for replies and follow-ups in Live Chat from an automation. #### Fields * **Channel** (required): Select the Live Chat channel to send from. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Reply timeout** (optional): If “Wait for reply” is on, set a duration after which the automation continues without a reply. * **Save text reply to** (optional): When waiting for reply, save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): When waiting for reply, save the contact’s file reply to a variable. ### Use cases * **Reply in the current chat:** Use the action to send a message in the Live Chat (e.g. after a trigger or another action). The body can include variables and attributes so the message is personalized. * **Ask and branch on the reply:** Use “Wait for reply” and “Save text reply to”, then add a [Condition](/quick-start/automations/logic-actions#condition) or [AI Intention Recognition](/quick-start/automations/ai-actions#ai-intention-recognition) to branch the automation (e.g. route to sales vs. support) based on what the contact replied. * **Confirm or follow up after another action:** After an [Assign Chat](/quick-start/automations/chats-actions#assign-chat), [Set Attribute](/quick-start/automations/contacts-actions#set-attribute), or other step, use Send Message to tell the contact what happens next (e.g. “We’ve assigned your chat to Sarah” or “Please share your order number”). # Logic Actions Source: https://docs.heyy.io/quick-start/automations/logic-actions ## Set Variable Set variable action Sets one or more workflow variables to values you choose. Values can be fixed text or built from workflow variables, contact fields (e.g. first name, email), and contact attributes. Use this to store data for later steps (e.g. after a contact reply or an API call) or to prepare values for conditions and message templates. ### Fields * **Variables** (required): Add one or more variable–value pairs. For each pair, pick the workflow variable to set and the value (you can use workflow variables, contact fields, and attributes via the dropdown or by typing placeholders). ### Use cases * **Store the contact’s reply for later:** After a trigger or message action that has “Save text reply to” or “Save file reply to”, use Set Variable to copy that value into a named variable so you can reference it in a Condition, AI action, or the next message. * **Prepare values after an API call:** After an API action, use Set Variable to map response fields (via the API’s response mapping) into workflow variables, then use those variables in conditions or message templates. * **Build a value for templates or attributes:** Combine workflow variables, contact fields, and fixed text into one variable, then use it in a message body or in Set Attribute so the contact or your CRM sees the formatted value. *** ## Clear Variable Clear variable action Clears one or more workflow variables so they no longer hold a value. Use this when you want to reset data before reusing a variable, or when you no longer need the stored value for the rest of the automation. ### Fields * **Variables** (required): Select the workflow variables to clear. You can select multiple. ### Use cases * **Reset before asking again:** Before a message action that asks a question and saves the reply to a variable, use Clear Variable on that variable so you don’t reuse an old answer from a previous run or step. * **Clean up after a branch:** When different branches set the same variable, clear it at the start of a shared path so the rest of the automation doesn’t use a value from the wrong branch. * **Free up variables you no longer need:** Clear one or more variables in one action when the automation no longer needs them, so you avoid leaking stale data into later steps or attributes. *** ## Condition Condition action Splits the flow based on rules you define. You add one or more condition groups; each group has conditions combined with AND/OR. The automation follows the branch where the first matching group evaluates to true. Use this to route by contact data, message content, variables, or attributes (e.g. “if intention = support, assign to support”). ### Fields * **Condition groups** (required): Add one or more groups (up to 10). Each group has a logical operator (AND or OR) and a list of conditions. Each condition compares a left operand (variable, attribute, contact field, etc.) to a right value using an operator (equals, contains, etc.). The first group that evaluates to true determines which branch runs. ### Use cases * **Route by intent or attribute:** After AI Intention Recognition or “Save text reply to”, add a Condition that checks the variable or attribute (e.g. “intention equals support”); use different branches to Assign chat, Move chat, or send different messages per branch. * **Branch on contact data:** Use conditions on contact fields or attributes (e.g. “language equals Spanish”, “segment equals VIP”) to send localized messages, assign to the right team, or add to different campaigns. * **Keyword or content checks:** Use a condition on the saved message (e.g. “body contains refund”) to branch to a dedicated flow (e.g. refund path vs. general support); order groups from most specific to least specific so the right branch runs first. *** ## Start Other Automation Start other automation action Starts another automation that has a “Manual trigger.” You choose the workflow and optionally map variables from the current automation to the target workflow’s parameters. Use this to reuse common flows (e.g. send survey, add to campaign) from multiple places or to chain automations. ### Fields * **Workflow** (required): Select the automation to start. Only workflows with a “Manual trigger” appear. * **Variables mapping** (optional): Map variables from the current workflow to the target workflow’s parameters. For each target parameter, set the value (e.g. a workflow variable, contact field, or attribute) that the started workflow will receive. ### Use cases * **Reuse a common sub-flow:** Build one workflow (e.g. send survey, add to campaign, run a checklist) with a Manual trigger, then start it from multiple automations via Start Other Automation; use variable mapping to pass in context (e.g. reason, source). * **Chain automations:** After one automation has done its job (e.g. qualified the lead), use Start Other Automation to run another workflow (e.g. add to campaign, notify sales) and pass variables so the second workflow has the data it needs. * **Same flow from different entry points:** Trigger the same “sub” workflow from a campaign, from the Inbox, or from different parent automations; mapping ensures the sub-flow receives the right parameters (e.g. campaign ID, contact attribute) no matter who started it. *** ## Delay Delay action Pauses the automation for a set time before continuing. You can use a fixed duration or a random range (e.g. 5–10 minutes). Optionally, restrict the delay to certain days and a time window (e.g. weekdays 9–17) so the automation continues only during those hours. Use this for follow-ups, reminders, or staggered actions. ### Fields * **Type** (required): Choose “Fixed” for a single duration or “Random” for a range. * **Delay** (required): The duration to wait (e.g. 5 minutes). For random, this is the minimum. * **Max delay** (required if type is “Random”): The maximum duration (e.g. 10 minutes). The actual delay is between the minimum and this value. * **Continue time limit** (optional): When enabled, the automation continues only during the specified days and time window (e.g. weekdays 9:00–17:00). Outside that window, the delay effectively pauses until the next allowed time. ### Use cases * **Follow-up after a delay:** After a trigger (e.g. Chat closed) or another action, add a Delay (e.g. 2 hours) so the next step (e.g. Send message, Add to campaign) runs later; use “Continue time limit” so it only runs during business hours. * **Stagger actions:** Use a random delay (e.g. 1–5 minutes) so many automations don’t fire at the same second (e.g. after a campaign or bulk trigger), reducing spikes and making flows feel more natural. * **Reminder or re-engagement:** Delay for a set period (e.g. 24 hours), then send a message or add the contact to a campaign if they haven’t replied; combine with conditions or Clear variable so you only act when appropriate. *** ## Randomizer Randomizer action Sends the automation down one of several paths at random, according to percentages you set. You define up to six paths (e.g. A, B, C) and assign each a percentage; the percentages must add up to 100. Use this for A/B tests, load balancing between flows, or random branching (e.g. 70% path A, 30% path B). ### Fields * **Paths** (required): Add one or more paths (up to 6). For each path, set a percentage (0–100). The sum of all percentages must equal 100. ### Use cases * **A/B test two flows:** Use two paths (e.g. 50% / 50%) to send contacts down different message or assignment flows and compare outcomes (e.g. different welcome messages or AI vs. human first). * **Weighted routing:** Use the randomizer to split traffic by percentage (e.g. 80% path A, 20% path B) so most contacts get the standard flow and a smaller group gets a premium or experimental flow. * **Load balance across options:** When you have several valid paths (e.g. multiple teams or message variants), use the randomizer to distribute contacts across them by percentage so no single path is overloaded. # Notifications Actions Source: https://docs.heyy.io/quick-start/automations/notifications-actions ## Email Notification Email notification action Sends an email to one or more recipients (up to 5) when the automation runs. The body can include workflow variables and contact attributes. Use this to notify your team (e.g. when a high-priority chat is created, when a form is submitted) or to send internal alerts from an automation. ### Fields * **Emails** (required): Add one or more email addresses (up to 5). Each address is validated before it can be added. * **Body** (required): The email content. You can use workflow variables and contact attributes in the text. ### Use cases * **Internal alerts:** Notify your team (e.g. support@) when a high-priority event occurs (e.g. VIP contacts you, escalation, form submitted); use workflow variables and contact attributes in the body for context. * **Team notification on event:** Trigger Email Notification from a “New incoming chat” or “Chat assigned” automation so the right people get an email when a lead is created or a chat is assigned. * **Context in the email:** Reference the contact’s name, attributes, or workflow variables in the body so recipients see who the alert is about; for customer-facing emails, use your email provider or a dedicated email action. *** ## WhatsApp Notification WhatsApp notification action Sends a WhatsApp message to one or more phone numbers (up to 5) when the automation runs. The body can include workflow variables and contact attributes. Use this to notify your team on WhatsApp (e.g. when a new lead is assigned, when an escalation occurs) or to send internal alerts from an automation. ### Fields * **Phone numbers** (required): Add one or more phone numbers (up to 5) in international format. Each number is validated before it can be added. * **Body** (required): The message content. You can use workflow variables and contact attributes in the text. ### Use cases * **Internal alerts on WhatsApp:** Notify your team (e.g. a sales rep) when an event occurs (e.g. lead assigned, escalation) by sending a WhatsApp message to one or more phone numbers; use variables and contact attributes in the body for context. * **Team notification on event:** Trigger WhatsApp Notification from a “Chat assigned” or “New incoming chat” automation so the assigned agent or team gets a WhatsApp alert when a lead is created or a chat is assigned. * **Internal vs customer:** Use WhatsApp Notification for internal alerts only; for messages to the contact in the chat, use the WhatsApp actions (Send Message, Send Template, etc.) in the same automation. # Triggers Source: https://docs.heyy.io/quick-start/automations/triggers Triggers decide **when** an automation starts. Choose the trigger that matches the moment you want Heyy to respond, then add actions to define what happens next. ## New & reopened chat New or reopened chat trigger Runs whenever a chat is opened, whether it’s the first time a contact messages you or they’re reopening a previously closed conversation. Use this when you want one automation to handle both new and returning contacts without distinguishing between them. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When to trigger** (optional): Add a condition to narrow the audience based on specific conditions. * **Save text reply to** (optional): Save the contact’s text reply to an automation variable. * **Save file reply to** (optional): Save the contact’s file reply to an automation variable. ### Use cases * **Single welcome flow for all opens:** Send one greeting and qualification flow whether the contact is new or returning, without maintaining two separate automations. * **Unified triage:** Route or assign every opened chat the same way (e.g. AI first, then handoff) regardless of first-time vs. reopened. * **Always capture the first message:** Use “Save text reply to” so you can store what the contact said when they opened the chat and use it in later steps. *** ## New incoming chat New incoming chat trigger Runs only when a contact messages you for the first time and a new chat is created. It does not run when an existing chat is reopened. Use this for welcome flows, onboarding, or any logic that should run exclusively for first-time conversations. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When to trigger** (optional): Add a condition group to narrow the audience based on specific conditions. * **Save text reply to** (optional): Save the contact’s text reply to an automation variable. * **Save file reply to** (optional): Save the contact’s file reply to an automation variable. ### Use cases * **First-time welcome and onboarding:** Send a welcome message, collect basic info, or run a qualification flow only when someone messages you for the first time. * **New-lead handling:** Trigger lead scoring, CRM creation, or assignment rules only for brand-new conversations, not when an existing chat is reopened. * **Channel-specific first contact:** Use “When to trigger” to run different first-time flows by channel (e.g. WhatsApp vs. Live Chat) or by attribute. *** ## Reopened chat Reopened chat trigger Runs when a contact sends a message in a chat that had been closed. Use this when you want different behavior for returning customers, for example, a “welcome back” message or to reassign the chat without triggering the same flow as brand new chats. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When to trigger** (optional): Add a condition group to narrow the audience based on specific conditions. * **Save text reply to** (optional): Save the contact’s text reply to an automation variable. * **Save file reply to** (optional): Save the contact’s file reply to an automation variable. ### Use cases * **Welcome-back message:** Send a “We’re here to help again” or “Your case is still open” message when a contact reopens a closed chat. * **Reassign without full welcome:** Route or assign returning chats to the right team or agent without repeating the first-time welcome flow. * **Returning-customer logic:** Run different flows (e.g. loyalty, win-back) only when someone comes back after a closed conversation. *** ## Chat closed Chat closed trigger Runs as soon as a conversation is closed by an agent or by the system. Use this for post-conversation steps such as sending a satisfaction survey, logging outcomes, or triggering follow-up campaigns after a defined delay. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When to trigger** (optional): Add a condition group to narrow the audience based on specific conditions. ### Use cases * **Post-conversation survey:** Send a satisfaction or NPS survey (e.g. via email or another channel) as soon as the chat is closed. * **Delayed follow-up campaign:** Start a delay, then add the contact to a campaign or send a follow-up message after the conversation has ended. * **Logging and reporting:** Trigger an API call or internal notification when a chat is closed to update your CRM or analytics. *** ## Chat assigned Chat assigned trigger Runs when a chat is assigned to one or more team members you select. Use this to run automations only when certain users receive the chat, for example, notifying a specialist, updating internal tools, or applying role-specific workflows. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **Users** (required): Select the users for whom to fire this trigger. ### Use cases * **Notify the assigned agent:** Send an email or internal notification to the user who received the chat so they know a new conversation was assigned to them. * **Role-specific workflows:** Run different automations when a chat is assigned to support vs. sales (e.g. different templates or next steps). * **Update external systems:** When a specialist is assigned, call an API to update your ticketing system or CRM with the assignee. *** ## Chat moved Chat moved trigger Runs when a chat is moved into one or more of the inboxes you select. Use this to react to routing changes, for example, triggering different handling when a chat lands in a sales vs. support inbox or notifying the right team when a chat is moved to their queue. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **Inboxes** (required): Select the inboxes for whom to fire this trigger. ### Use cases * **Inbox-specific handling:** When a chat is moved to Sales, send a sales-focused message or assign to a sales rep; when moved to Support, run a support triage flow. * **Notify the team whose inbox received the chat:** Send an internal alert or assign a default agent when a chat lands in a specific team’s inbox. * **Sync with routing rules:** Trigger an API or update attributes when a chat is moved so your external routing or reporting stays in sync. *** ## New incoming message New incoming message trigger Runs on every new message from a contact in an existing conversation. Use this when you want to react to each message—for example, to run keyword-based logic, save replies to variables, or trigger AI or routing only when new content arrives. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When to trigger** (optional): Add a condition group to narrow the audience based on specific conditions. * **Save text reply to** (optional): Save the contact’s text reply to an automation variable. * **Save file reply to** (optional): Save the contact’s file reply to an automation variable. ### Use cases * **Keyword-based routing:** Run only when the message contains specific words (e.g. “refund”, “cancel”) and then route, assign, or reply accordingly. * **Save and reuse the reply:** Use “Save text reply to” or “Save file reply to” so the next steps (e.g. AI Transform, Condition, or a template) can use what the contact just said. * **Per-message AI or logic:** Trigger an AI employee or intention recognition on every new message so you can respond or branch based on the latest content. *** ## New Instagram comment New Instagram comment trigger Runs when someone comments on your Instagram content. You can scope it to all posts and reels or to specific media. Use this to auto-reply to comments, route commenters into DMs, or run contests and engagement flows tied to particular posts or reels. #### Fields * **Channel** (required): Select the channel where this trigger will run. * **When someone comments on** (required): Select between "All posts & reels" or "Specific posts/reels" and then select the posts/reels. * **When to trigger** (optional): Add a condition group to narrow the audience based on specific conditions. ### Use cases * **Campaign-specific comment reply:** Use “Specific posts/reels” to auto-reply to comments on a single post or reel (e.g. contest, product launch) and optionally invite commenters into DMs. * **General comment-to-DM flow:** Use “All posts & reels” to reply to comments across your account and invite people into a DM conversation with a consistent message. * **Conditional handling:** Use “When to trigger” to reply only when the comment contains certain words or to route high-intent commenters differently. *** ## Contact created Contact created trigger Runs when a new contact is created in Heyy. Use this to enrich or route contacts as soon as they enter your system—before any chat exists. #### Fields * **When to trigger** (optional): Add a condition group to narrow which contacts should start this automation (e.g. only contacts from a specific source or with certain attributes). ### Use cases * **Enrichment on create:** Call an API to enrich the contact (company, location, lead score) and store results in attributes. * **Auto-label new contacts:** Add labels such as “new”, “lead”, or “needs\_enrichment” immediately after creation. * **Kick off lifecycle:** Subscribe the contact to a journey or campaign the moment they’re created. *** ## Contact attribute updated Contact attribute updated trigger Runs when one or more selected contact attributes change. Use this to react to changes in profile data (e.g. lead status, plan, region) and trigger follow-ups or routing when the data becomes available. #### Fields * **Attributes** (required): Select which contact attributes should trigger this automation when they’re updated. * **When to trigger** (optional): Add a condition group to narrow which updates should start the automation (e.g. only when status becomes “qualified”). ### Use cases * **React to qualification:** When `lead_status` becomes “qualified”, notify sales or start a sales outreach flow. * **Keep systems in sync:** When key attributes change, call an API to update your CRM or data warehouse. * **Progression-based automation:** When `onboarding_step` changes, send the next message or subscribe the contact to the next journey stage. *** ## Label added Label added trigger Runs when one or more selected labels are added to a contact. Use this to trigger workflows based on segmentation and tagging. #### Fields * **Labels** (required): Select the labels that should trigger this automation when added. * **When to trigger** (optional): Add a condition group to narrow which labeled contacts should start the automation. ### Use cases * **Start segmented flows:** When “VIP” is added, start a priority handling automation or notify a manager. * **Ops handoff:** When “needs\_follow\_up” is added, assign a task, send a reminder, or add the contact to a follow-up campaign. * **Qualification tags:** When “high\_intent” is added, start an AI or routing flow to get them to the right team faster. *** ## Label removed Label removed trigger Runs when one or more selected labels are removed from a contact. Use this when removing a tag should end, change, or reverse part of a workflow. #### Fields * **Labels** (required): Select the labels that should trigger this automation when removed. * **When to trigger** (optional): Add a condition group to narrow which contacts should start the automation. ### Use cases * **End a lifecycle:** When “trial” is removed, subscribe to a post-trial journey or update the contact’s status in external systems. * **Reverse segmentation:** When a label is removed (e.g. “needs\_follow\_up”), clear reminders, stop related automations, or update CRM flags. * **Clean up attributes:** When a temporary label is removed, clear temporary automation variables or attributes tied to that segment. *** ## Webhook received Webhook received trigger Runs when Heyy receives a webhook event from one of your webhook endpoints. Use this to start automations from external systems (e.g. Stripe, Shopify, internal tools), map payload data into attributes/variables, and optionally identify which contact the webhook belongs to. #### Fields * **Webhook endpoint** (required): Choose the webhook endpoint that should trigger this automation. * **Search contact by** (optional): Configure how Heyy should find the contact in the webhook payload (e.g. by contact ID, email, or phone number). * **Data mapping** (optional): Map values from the webhook JSON payload into contact attributes or automation variables. ### Use cases * **External events → messaging:** When a payment succeeds or an order ships, start an automation that sends an update to the customer. * **Sync enrichment data:** When your backend posts enrichment results, map fields into contact attributes and branch based on them. * **Unified automation entry point:** Trigger the same automation from multiple systems by posting to the endpoint and mapping fields into variables. *** ## Manual trigger Manual trigger Runs only when started by you or by another automation—from the Inbox, a campaign, an API call, or a [Start Other Automation](/quick-start/automations/logic-actions#start-other-automation) action. Use this for flows that should not start from customer activity, such as scheduled follow-ups, bulk actions, or sub-flows called by other automations. #### Fields * **Channel** (required): Select the channel where this trigger will run. ### Use cases * **Reusable sub-flows:** Build one automation (e.g. send survey, add to campaign) and start it from multiple places—other automations, campaigns, or the Inbox—using the [Start Other Automation](/quick-start/automations/logic-actions#start-other-automation) action and variable mapping. * **API- or campaign-driven flows:** Start the automation via API or when a contact enters a campaign, so the flow runs only when you or an external system decides, not on every new message. * **Scheduled or bulk actions:** Use manual trigger for flows that run on a schedule, from a bulk action, or when an agent clicks “Run automation” in the Inbox. # WhatsApp Actions Source: https://docs.heyy.io/quick-start/automations/whatsapp-actions ## Send Message WhatsApp message action Sends a WhatsApp message to the contact in the current chat. You can add an optional header (image, video, or document) and a body with variables. Use this for simple replies, follow-ups, or sending media and documents within an automation. #### Fields * **Channel** (required): Select the WhatsApp channel to send from. * **Header** (optional): Choose image, video, or document and upload a file or paste a URL. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Wait for reply** (optional): When enabled, the automation pauses until the contact replies. * **Reply timeout** (optional): If “Wait for reply” is on, set a duration after which the automation continues without a reply. * **Save text reply to** (optional): When waiting for reply, save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): When waiting for reply, save the contact’s file reply to a variable. ### Use cases * **Reply in the current chat:** Use the action to send a text or media message in the WhatsApp chat (e.g. after a trigger or another action). The body and optional header can use variables and attributes. * **Ask and branch on the reply:** Use “Wait for reply” and “Save text reply to”, then add a Condition or AI action to branch the automation (e.g. qualification, routing) based on what the contact replied. * **Send a document or media:** Use the optional header to attach an image, video, or document (e.g. brochure, form) in the same message as the body text. *** ## Send Buttons WhatsApp buttons action Sends a WhatsApp message with up to three quick-reply buttons. You can add an optional header (text, image, video, or document), body, and footer. Use this to guide the contact with clear choices (e.g. “Yes / No”, “Option A / B / C”) and capture their selection in a variable or attribute. #### Fields * **Channel** (required): Select the WhatsApp channel to send from. * **Header** (optional): Text or media (image, video, document). For media, upload a file or paste a URL. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **Footer** (optional): Short text shown below the body (e.g. disclaimer). * **Buttons** (required): Add up to three quick-reply buttons; each has a label. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t tap a button. * **Wait for reply** (optional): When enabled, the automation waits for the contact to tap a button or send a message. * **Save text reply to** (optional): Save the contact’s reply (button label or text) to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Present clear choices:** Use the action to send a message with up to three quick-reply buttons (e.g. “Yes / No”, “Book / Cancel”) so the contact can tap a choice; use “Save text reply to” to branch the automation on their selection. * **Confirm or collect consent:** After another step (e.g. AI or Set attribute), send a message with “Confirm” and “Cancel” (or similar) and branch the flow based on which button the contact taps. * **Store the choice on the contact:** Save the button label or reply to a contact attribute so you can use it later in the same automation or in campaigns and views. *** ## Send List WhatsApp list action Sends a WhatsApp interactive list: a button that opens a list of sections and rows. You define the list title (button text), optional header and body, and one or more sections with rows (title and optional description). Use this when you have many options (e.g. product list, menu, categories) and want a compact, structured message. #### Fields * **Channel** (required): Select the WhatsApp channel to send from. * **Header** (optional): Short text at the top of the message. * **Body** (required): The message text. You can use workflow variables and contact attributes. * **List** (required): List button label and sections. Each section has a title and rows (up to 10 rows total); each row has a title and optional description. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t select an option. * **Wait for reply** (optional): When enabled, the automation waits for the contact to select a row or send a message. * **Save text reply to** (optional): Save the contact’s selection (or text reply) to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Product or menu selection:** Use the action to send a list of options (e.g. products, services, categories) in a compact format; use “Save text reply to” to branch the automation or pass the selected row to the next step. * **Multi-step choice with many options:** When you have more than three options and want a structured list (sections and rows), use Send List instead of multiple buttons; then branch or assign based on the saved selection. * **Collect a choice for later use:** Save the selected row to a contact attribute so you can use it in follow-up messages, conditions, or campaigns (e.g. “Preferred product”, “Department”). *** ## Send Template WhatsApp template action Sends a pre-approved WhatsApp template message. You pick a template from your account and map its variables to workflow variables, contact fields, or attributes. Use this for outbound or follow-up messages that must use approved templates (e.g. order updates, appointment reminders). #### Fields * **Channel** (required): Select the WhatsApp channel to send from. * **Message template** (required): Choose an active WhatsApp template. * **Variables mapping** (required if the template has variables): Map each template variable to a workflow variable, contact field (e.g. first name, phone), or attribute. * **Reply timeout** (optional): Duration after which the automation continues if the contact doesn’t reply. * **Wait for reply** (optional): When enabled, the automation waits for the contact’s reply. * **Save text reply to** (optional): Save the contact’s text reply to a variable or attribute. * **Save file reply to** (optional): Save the contact’s file reply to a variable. ### Use cases * **Outbound or follow-up within 24h window:** Use the action to send a pre-approved template when you need to message the contact outside the 24-hour session (e.g. order confirmation, appointment reminder). Map variables to workflow variables or contact attributes. * **Campaign or bulk flow:** In an automation started by a campaign or manual trigger, use Send Template to deliver the approved message and optionally “Wait for reply” to continue the flow based on the contact’s response. * **Personalized template with live data:** Use variables mapping to fill the template with the contact’s name, order number, or other attributes so the message is personalized while staying within WhatsApp’s template rules. # Campaigns Source: https://docs.heyy.io/quick-start/campaigns The **Campaigns** page is where you create, manage, and track your outreach campaigns. It gives you a clear overview of past and ongoing campaigns, their performance, and the audiences they target. Campaigns ## Left Sidebar The left sidebar helps you filter and organize your campaigns: * **All Campaigns** – Shows all the campaigns in your workspace. * **Scheduled** – Shows all the scheduled campaigns. * **Recurring** - Shows all the recurring campaigns. ## Campaign List The campaign list displays each campaign along with its key details: * **Name** – The label you gave the campaign when creating it. * **Type** – Whether it’s scheduled, recurring, or one time. * **Latest Execution Status** – The most recent result (e.g., completed, in progress, failed). * **Total Recipients** – Number of contacts included in the campaign. * **Created At** – The date the campaign was first created. Click on any campaign in this list to open the **campaign view**. ## Campaign View Inside a campaign, you can see performance and delivery details, including: * **Total** – How many contacts were in the latest campaign execution. * **Sent** – The number of messages in the "sent" status. * **Delivered** – The number of messages with successful deliveries. * **Read** – The number of messages that were read. * **Failed** – The number of messages that failed to deliver. You need to run the campaign at least once to see its performance and delivery details. Click on the status summary to filter the execution results. ### Toolbar actions At the top of the campaign view, you can access key actions: * **Edit (pencil icon)** – Update the campaign name, linked automation, scheduling, and recurrence settings. * **Preview automation (eye icon)** – Open a read-only preview of the connected automation to review the flow before running the campaign. * **Manage recipients** – Add or remove recipients from the campaign audience without changing the underlying automation. * **Start campaign** – Open a final preview of the automation and audience before sending the campaign. If the campaign is configured as **Scheduled** or **Recurring**, the **Start campaign** button is disabled because the campaign will run automatically according to its schedule. ## Creating a New Campaign