HAL

List projects available to this MCP key. Call this first, then get_email_capabilities_overview for email features.

Takes no parameters.

List conversations with filters (status, spam, limit, offset). Each result says whether it is marked as spam.

Get a conversation with its messages and attachment metadata. agents_typing lists teammates drafting a reply right now; if someone is, let them answer instead of replying over them. replied_to_email is set when the conversation started as a reply to a campaign, workflow or broadcast email. Call get_conversation_image with an image attachment ID to inspect its visual content. To incorporate HAL's own evidence-backed AI draft into your final answer, call generate_ai_response_suggestion next.

Get an image attached to a conversation message as MCP image content so the AI client can inspect it. Images over 2 MB are resized and compressed before delivery. Use an attachment ID returned by get_conversation.

Show the visitor and your teammates in the dashboard that a reply is being written. Call it right before you draft a reply the visitor will read, so a live agent sees the conversation is being handled. Do not call it for internal notes, for reading or summarizing, or when you are not going to reply. reply_to_conversation clears it; call again with is_typing false if you decide not to reply.

Send an agent message to a conversation. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only. To walk the visitor through a flow, pass `offer_guide_id` instead of writing guide markup. To send files, pass `attachments`; they are delivered with the message in the widget and in email replies.

Update conversation status, assignment, snooze state, or spam. is_spam true does what "Mark as spam" does in the inbox: the conversation leaves the inbox, is marked read, and the same sender's next conversations in this project go straight to spam; is_spam false undoes it and lets the sender back in. The change is recorded in the conversation's activity as done via MCP. Use list_conversations with spam "only" to review spam.

Generate an advisory-only HAL AI reply suggestion for the latest visitor message. Call this after get_conversation, then combine HAL's draft, evidence, and confidence with the conversation messages when composing your final answer. This tool never sends a message to the visitor, even when project auto-send or AI deflection is enabled.

List all article groups

Create a new article group

Update an article group

List articles, optionally filtered by group or to published ones. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only.

Find published help articles that fit a conversation, in the visitor's language and limited to ones this visitor may see. Matches the visitor's latest message, or `query` when given. Returns up to 6, best match first; weaker results can be only loosely related, so check the title and excerpt before sharing one. Read-only; uses no AI quota. Each result has `insert`, the exact markup to put in the reply. To show a help article to the visitor, write `[label](hal-article:<article id or slug>)` into the `content` of reply_to_conversation. The widget renders it as a clickable card at that spot, on its own line (it is not an inline link inside a sentence), so put it between sentences or paragraphs, e.g. "Refunds take 5 days.\n[Refund policy](hal-article:refund-policy)\nAnything else?". The label is the card title, so use the article title. Several cards in one reply are fine. Only published articles the visitor may see are accepted; each reference is checked and rewritten to the slug for the visitor's language. Find the right article with find_relevant_articles (matched to the conversation, or to your own query), or list_articles with published_only.

Get an article with translations

Create an article with an initial translation

Update article properties or upsert a translation

List contacts with optional search

Get a contact with full details, recent activity and the deals they are on

Create a new contact

Update a contact

List CRM pipeline stages

List companies with optional search and stage filter. Includes companies with no linked contacts. Paginated.

Read-only CRM board: list ALL companies grouped by pipeline stage, including companies with no linked contacts and unstaged companies. Returns per-stage deal totals so agents can reconcile Won totals with company rows. Company stage and deal value mirror the company primary deal; use list_deals to see every deal, including expansions and renewals.

Get a company with contacts, details and its deals. The company stage and deal_value mirror its primary deal.

Link an existing contact to an existing company. The operation is idempotent and both records must belong to the selected project.

Create a new company

Update a company

Merge a duplicate company into a keeper. Contacts, tracked events, and CRM timeline move to the keeper; the source company is deleted. Use when the same org has a HAL-generated row and a later source-system (e.g. Apollo) id row. Refuses to merge companies that already have different external ids.

List deals (sales opportunities). A company can have several deals: new business, expansion, renewal. Each deal has a stage, amount, expected close date, owner, next step and contacts. Filter by company, contact, stage, owner or status.

Summarize the sales pipeline: per stage the number of deals, total and probability-weighted amount, plus open/won/lost totals, win rate and open deals whose expected close date has passed. Use list_deals for the deals themselves.

Get a deal with its company, stage, contacts and stage/amount history

Create a deal for a company. The company's own stage and value follow its primary deal (its newest open new-business deal).

Update a deal. Moving it to a 100% stage marks it won and a 0% stage marks it lost (pass lost_reason); moving it back to an open stage reopens it.

Add a contact to a deal, or change their role on it

Remove a contact from a deal

Delete a deal. A company with no deals left drops out of the pipeline.

Orientation for HAL email features: campaigns vs workflows vs broadcasts, templates vs project defaults vs inline design, sender domains, images, test sending, track_event, and unsubscribe/suppression. Call this before creating any campaign, workflow, broadcast, or template.

Takes no parameters.

List reusable workflow email templates for a project.

Get a reusable workflow email template.

New to HAL email? Call get_email_capabilities_overview first. Create a reusable workflow email template.

Update a reusable workflow email template.

Delete a reusable workflow email template. Existing campaigns keep their embedded copy.

Render an email template preview as subject, preheader, HTML, and plain text.

Validate an email template and return AI-client-friendly errors.

Send a workflow email template test to an account user email address only.

Send a test email for an existing email campaign to an account user email address only.

List email addresses suppressed for lifecycle email campaigns in a project.

Suppress an email address so lifecycle email campaigns skip it. Defaults to category "all" (blocks everything); pass a specific category key (see list_email_categories) to block only that category.

Remove an email address from the lifecycle email suppression list. Omit category to lift every suppression on the address (bounce/complaint rows are never removed); pass category to lift only that one.

Check whether an email address is currently suppressed for lifecycle email campaigns, for a given category (default "all").

List email campaigns backed by visitor workflows.

Get email campaign details.

List tracked lifecycle event names seen in a project.

List visitor custom properties and sampled metadata keys available for campaign predicates and conditions.

New to HAL email? Call get_email_capabilities_overview first. Create an email campaign using campaign language instead of workflow graph internals.

Update an email campaign.

Enable an email campaign.

Disable an email campaign.

Delete an email campaign. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.

List email campaign runs with delivery, open, and click data.

Get one email campaign run with clicked URLs.

List a project's email categories used for per-category unsubscribe/preferences (marketing, product updates, transactional, ...). A project with no customized categories returns the built-in defaults.

Replace the full set of email categories for a project (upserts by key, removes any key not included). Refused with the referencing suppressions/broadcasts/workflows if a key still in use would be removed.

List images in a project’s email image library, newest first. Use these for lifecycle/workflow email `image` blocks.

Upload an image to a project's email image library so it can be used in lifecycle/workflow email `image` blocks (email_block_types.image.url must be an absolute URL — external hosting is no longer required). Provide exactly one of data_base64 (with mime_type) or source_url. Use email_url in email image blocks (image.url).

Delete an image from a project’s email image library. Remove it from any email templates first, or the image block will break.

List one-off email broadcasts for a project.

Get a single email broadcast, including delivery/open/click counts. With an A/B test, `ab_test` has its settings, `phase` (testing, waiting, winner_sending, done, skipped, cancelled), `ends_at` (automatic winner pick), the `winner`, and `results` (test-group sent/opens/clicks/rates per variant plus a confidence score).

New to HAL email? Call get_email_capabilities_overview first. Create a draft (or scheduled, if scheduled_at is set) one-off email broadcast. Does not send anything.

Update a draft or scheduled broadcast (name, email content, audience, schedule, list-hygiene or tracking options, A/B test).

Delete a broadcast. Refused while it is actively sending.

Preview who a broadcast (or a candidate audience) would reach: match count, suppressed count, contacts left out by list hygiene (invalid/disposable/role addresses, unengaged, recently emailed) per reason, and a sample.

List the fields available for building a broadcast audience (contact/company builtins, sampled metadata keys, valid operators per type).

Send a test of a broadcast email to an account user email address only (never to real contacts).

Schedule a draft (or reschedule a scheduled) broadcast to send at a future time.

IMMEDIATELY sends this broadcast to its whole live audience - a real, irreversible email blast to real contacts, not a test. You MUST call preview_broadcast_audience first and pass its exact `count` as confirm_recipient_count; a mismatch is refused. Call get_broadcast_readiness first too: sends with blocking deliverability checks are refused. Only call this after the user has explicitly confirmed they want to send to that many recipients right now.

Cancel a scheduled, in-progress, or paused broadcast. Recipients not yet sent to are marked cancelled.

List the per-recipient delivery status for a broadcast.

Deliverability checklist for a broadcast before sending: sender authentication (custom domain, DMARC, MAIL FROM/SPF), postal address, project bounce/complaint health, warm-up capacity (how many days the send will be spread over), and content lint (size, image-heavy, subject, spam phrases, link shorteners). `error` checks block sending; share warnings with the user.

Resume a paused broadcast. Broadcasts auto-pause when their bounce or spam-complaint rate is too high, or when a scheduled send hits a blocking deliverability check; `pause_reason` says why. Only resume after the user understands the reason and has addressed it (e.g. removed bad addresses). The remaining recipients are sent to, and it pauses again if rates stay high.

End a broadcast's A/B test early and send the winner to the rest of the audience now, instead of waiting for the automatic pick. `ab_test.results` on get_broadcast shows each variant's open/click rates. Pass `variant` to choose it; omit it to send the current leader. This sends real email to the remaining recipients: confirm with the user first.

Project email reporting. Always returns: health (last 30 days across every campaign, workflow and broadcast: sent, sent_last_24h, delivered, hard bounces (bounced), soft bounces, complaints and their rates, plus the status that blocks broadcasts, and reset_at when a list-cleanup reset restarted the window), sources (the same window broken down per workflow/broadcast with delivered, hard/soft bounces, unique opens, clicks and replies), warm-up progress (only broadcasts count toward it), and the footer postal address. Pass workflow_id or broadcast_id (optionally with days; omitted = all time) to also get stats for that one campaign. Opens and clicks exclude automatic ones from security scanners and Apple Mail Privacy Protection, which are reported as automatic_opens/automatic_clicks. Replies count recipients who answered the email (auto-replies are ignored). Delivered counts only cover emails sent after delivery tracking was enabled.

Set the physical mailing address shown in the footer of every marketing/lifecycle email (required by CAN-SPAM). Pass null or an empty string to remove it. Confirm the exact address with the user first.

Start a fresh 30-day health window for a project that is blocked from sending broadcasts by old bounces or complaints. ONLY use this after the bounced and complained addresses have been suppressed (list_email_suppressions / suppress_email_recipient) so the same list cannot bounce again. HAL enforces this: the reset is refused, and nothing changes, if any recipient that bounced or complained in the current window is not suppressed (by a project-wide or platform-wide suppression), and a project can be reset at most once per 30 days. Once it succeeds, sends before the reset stop counting toward the project's bounce and complaint rate, and any new bounces after it count normally and can block the project again. This only resets HAL's own project health window; it does not change the Amazon SES account reputation or review status. Per-broadcast auto-pause is not affected. Cannot be undone and is logged: get explicit user confirmation, then pass confirm: true and a reason describing the cleanup (3-500 characters). Returns the updated health (including reset_at).

New to HAL email? Call get_email_capabilities_overview first. Static reference for building visitor workflows through create_workflow/update_workflow/validate_workflow: trigger shapes, node types, graph rules, condition/predicate operators, email block types, and variable syntax.

Takes no parameters.

List visitor workflows for a project (trigger + branching graph automations), ordered by priority.

Get a visitor workflow including its full node/edge graph definition.

Validate a visitor workflow definition without saving it. Same input as create_workflow.

New to HAL email? Call get_email_capabilities_overview first. Create a visitor workflow: a trigger plus a branching graph of condition/send_widget_message/send_email/trigger_campaign/end nodes. Call get_workflow_builder_reference first.

Update a visitor workflow. Partial: only provided fields change. If trigger fields change without a new definition, the existing trigger node is synced in place.

Delete a visitor workflow. Refuses if another workflow in the project still chains into it via trigger_campaign or next_campaign_id.

Enable or disable a visitor workflow.

Reorder visitor workflows by priority; the first id in the list gets the highest priority.

List execution history for a visitor workflow.

Get one visitor workflow execution.

Get the project default email design used to seed new send_email nodes.

Update the project default email design (subject/preheader/theme/template_document) used to seed new send_email nodes. Merges into the project config without touching other settings.

Send a real test email for one send_email node in a workflow to an account user email address only.

List account user emails allowed as workflow/email test recipients.

Takes no parameters.

Track a lifecycle event exactly like the public track-event API. THIS CAN SEND REAL EMAILS: matching enabled api_trigger workflows fire immediately for real contacts. Use dry_run to preview matches without tracking or sending anything. Workflows only fire for events that resolve to a visitor (via user_id or email); company-only events never trigger workflows.

List all automations for this project

Get automation details

Create a new automation

Update an automation

Enable or disable an automation

List all guides for this project

Get guide details

Create a new guide

Update a guide

Enable or disable a guide

Permanently delete a guide and its execution history

Per-guide analytics: triggers, completions, completion rate, per-step drop-off, selector misses

Which guides had steps fail to anchor recently — the signal that a selector rotted in the target app

Validate a guide's start location and step selectors against the live pages the developer is logged into. Results are recorded by the widget's authoring mode (?hal_guide_debug=1 on any page where the widget runs); this tool returns the newest snapshot per page, so a guide that spans pages reports each of them.

Add tags to a message. Merges with existing tags (deduplicates). If Damper integration is enabled and a tag matches tags_to_sync, pushes the conversation to Damper as feedback.

Remove specific tags from a message

List all tags defined for this project

Get all project tags with their usage counts

List all teams for this project with member and conversation counts

Get a team with its members

List shared macros (available to all team members)

Get a single shared macro by ID

List all webhooks for this project

Create a new webhook

Update an existing webhook

Delete a webhook

Get project statistics including responsiveness, conversation volume, and per-agent metrics. Defaults to last 30 days.

Get the custom sender domain (Starter plan and above) configured for this project, including DNS records, verification status, and any Reply-To override (`sender_domain.reply_to`, alongside the top-level `reply_to` this project's emails actually use).

Configure a custom sender domain for visitor-facing email on this project (Starter plan and above). Returns DNS records (DKIM CNAMEs, and MX/TXT if a mail-from subdomain is set) that the user must add themselves at their DNS provider before the domain can verify. Reply-To stays on the HAL inbound address so inbound routing keeps working, unless a Reply-To override is set afterwards with update_sender_identity.

Re-check the project's custom sender domain verification status against Amazon SES.

Update the local part, display sender name, and/or Reply-To override of the configured sender domain, without changing the domain itself. By default, Reply-To stays on the HAL inbound address so inbound routing/threading keep working. Setting `reply_to` overrides that with the given address - it must already forward into the project's HAL inbound address, or replies will be lost. Pass an empty string or omit `reply_to` as `null` to clear an existing override and revert to the HAL address.

Remove the project's custom sender domain. Visitor-facing email reverts to the default Hal address.

Import a single historical conversation silently (no webhooks, no notifications). Use for migrating data from other chat platforms.

Import multiple historical conversations in batch (max 100). Each conversation is imported independently — one failure does not affect others. Silent: no webhooks, no notifications.