# 10DLC Registration
Source: https://docs.usehatchapp.com/academy/account-setup/10dlc-registration

10DLC (10-Digit Long Code) is a system in the U.S. that allows businesses to send SMS messages using standard 10-digit phone numbers. It improves message deliverability and reduces spam by requiring registration and carrier vetting for business text messaging.

<div>
  <iframe />
</div>

### Steps

1. Open the invitation from your email, and set up your account by entering your first and last name, phone number, and finalizing the setup
2. In the **Compliance** tab, click **Add Business**
3. Enter your **9-digit Business EIN or Tax ID**
4. If entered correctly, other fields may auto-fill
5. Once all required fields are filled in, click **Save Draft**
6. Click **Submit**

Within 2 business days, you'll get an update: approved or rejected. If you get rejected, reach out to your Account Manager and they'll walk you through exactly what to fix.

### Lesson links

* [10DLC Compliance Knowledge Base Article](https://www.usehatchapp.com/knowledge/10dlc-requirements)

### Related docs

[10DLC Registration & TCPA Compliance](/getting-started/compliance/10dlc-registration-tcpa-compliance)


# Create Workspaces
Source: https://docs.usehatchapp.com/academy/account-setup/create-workspaces

Organize your Hatch account by creating workspaces for different teams, locations, or business lines.

<div>
  <iframe />
</div>

### Related docs

[Managing Workspaces](/how-to-use-hatch/account-settings/managing-workspaces)

[Add a Workspace](/how-to-use-hatch/account-settings/add-a-workspace)


# Invite Your Team
Source: https://docs.usehatchapp.com/academy/account-setup/invite-your-team

Inviting your team is one of the first steps to getting everyone collaborating and closing more deals quickly.

<div>
  <iframe />
</div>

### Step 1: Go to Settings

1. From your Hatch account, click the **Settings** icon at the bottom left corner of your screen
2. Select **Settings page** from the menu

### Step 2: Open the Team Section

1. Click **Team** in the left-hand menu
2. Select **Add Member**

### Step 3: Add Team Members

1. Enter their **name and email address**
2. Make sure the email address is correct — each person you invite will receive an email to set up their Hatch account

### Step 4: Assign Workspaces (Optional)

After your Hatch workspaces are created, you can assign each team member to one or more of them. If you don't have workspaces set up yet, you'll be able to assign them later.

### Related docs

[Managing Users](/how-to-use-hatch/account-settings/managing-users)

[Add or Remove a Member from a Workspace](/how-to-use-hatch/account-settings/add-or-remove-member-from-workspace)


# Business Profile
Source: https://docs.usehatchapp.com/academy/ai-agents/business-profile

Configure your AI agent's business profile — the foundational information it uses to represent your company.

<div>
  <iframe />
</div>

### Related docs

[Hatch AI Agent Setup Guide](/getting-started/hatch-assistant/hatch-assistant-setup-guide)


# Decision Tree
Source: https://docs.usehatchapp.com/academy/ai-agents/decision-tree

Your Decision Tree is the roadmap behind your AI agent's conversations — it tells your agent what to say, when to say it, and how to handle every possible outcome.

<div>
  <iframe />
</div>

### Step 1: Choose and assign campaigns

1. From your Hatch workspace, go to the **Campaigns** section
2. Select the campaign you want your AI agent to handle (e.g. Speed to Lead, Estimate Follow-Ups, Nurture)
3. Assign your AI agent to the chosen campaign

<Tip>Assigning campaigns ensures your agent only manages the right types of conversations, keeping interactions organized and efficient.</Tip>

### Step 2: Create your script

Each AI script includes four key sections:

1. **Persona** — defines who your AI is (tone, personality, communication style)
2. **Goal** — clarifies what the conversation is trying to achieve
3. **Instructions** — outlines how your AI should guide the conversation
4. **Additional considerations** — specifies any unique cases or exceptions

### Step 3: Generate script instructions automatically

1. Click the 💬 icon at the bottom-right of your screen
2. Select **Generate Instructions**
3. Type your prompt — for example: *"Give me an AI agent script for a speed-to-lead campaign with the goal of engaging leads about their project request and getting them set up with a booked appointment."*
4. Hatch will automatically generate a script template
5. Review, edit, and customize the template to fit your business and tone

### Step 4: Add outcome commands

Every script must include commands that tell your AI what to do when a conversation reaches an outcome.

**The three required commands:**

* **Success** — the conversation achieved its goal (e.g. appointment booked)
* **Bailout** — a human CSR should take over (e.g. customer asks for a call or specific pricing)
* **Discard** — the lead opted out or is no longer interested

**Examples:**

* If a customer requests a phone call → your AI responds "Someone from our team will reach out soon!" and ends with a bailout
* If a customer reports an emergency → use the bailout command to ensure immediate human follow-up

### Step 5: Use commands to reference knowledge data

Commands allow your AI to access stored knowledge and personalize conversations.

1. Type a **backslash (`\`)** inside your script
2. Choose a **knowledge command** from the dropdown
3. For example, to reference a customer's first name: type `\` → select **Knowledge → Customer Data → First Name**
4. Click **Save** to apply changes

This enables your AI to use existing customer data naturally — without asking for information you already have.

### Step 6: Test your decision tree

1. Open your AI agent environment
2. Run test conversations to simulate real interactions
3. Observe how your AI responds to different outcomes
4. Continue testing until it behaves exactly how you want

Everything you add saves automatically, so you can safely test and refine in real time.

### Step 7: Add additional considerations

Use this section to handle edge cases such as:

* Handling urgent requests differently
* Escalating messages based on keywords
* Customizing responses by service type

### Related docs

[Hatch AI Agent Setup Guide](/getting-started/hatch-assistant/hatch-assistant-setup-guide)


# Persona & Knowledge
Source: https://docs.usehatchapp.com/academy/ai-agents/persona-and-knowledge

Define your AI agent's name, personality, and the knowledge base it draws from when responding to customers.

<div>
  <iframe />
</div>

### Related docs

[Hatch AI Agent Setup Guide](/getting-started/hatch-assistant/hatch-assistant-setup-guide)


# Voice AI
Source: https://docs.usehatchapp.com/academy/ai-agents/voice-ai

Create and customize a fully functional Voice AI agent capable of handling customer calls, booking appointments, answering FAQs, and handing off to your team when needed.

<video>
  <source type="video/mp4" />
</video>

### Step 1: Create a new AI agent

1. From your **Voice AI dashboard**, click **Create a New AI Agent**
2. Choose your **use case** (e.g. inbound calls) and your **industry** (e.g. Home Services → HVAC)
3. Give your agent a **name** and click **Create Agent**

<Tip>Each industry and use case combination comes with a preloaded template including common questions and responses tailored to your field. You can edit all of these anytime.</Tip>

### Step 2: Customize the conversation template

Once your agent is created, you'll see a prebuilt conversation flow with prompts and responses designed for your use case. You can:

* Update the company name and greeting
* Adjust phrasing and tone
* Add or remove questions based on your business needs

### Step 3: Add knowledge and FAQs

Your **Knowledge** section is where you teach your bot company-specific information:

* Add frequently asked questions (e.g. "What's your minimum service fee?")
* Drag and drop any existing company FAQ or pricing documents
* Uploading a file automatically adds it to your **Knowledge Tree**, saving you from manual entry

<Tip>Keep your knowledge base updated — your bot learns directly from these materials.</Tip>

### Step 4: Define your agent's persona

In the **Persona** tab:

* **Name** your agent
* **Select a voice** from a list of natural-sounding options
* **Test conversations** instantly with one click to hear how your agent sounds

Choose a tone and personality that best matches your brand — whether that's friendly, professional, or conversational.

### Related docs

[Voice AI: Live Transfers](/getting-started/hatch-assistant/voice-at-live-transfers)

[Voice AI: After-Hours Bot](/getting-started/hatch-assistant/voice-ai-after-hours-bot)

[Outbound Voice AI](/getting-started/hatch-assistant/outbound-voice-ai)


# AI Column Setup
Source: https://docs.usehatchapp.com/academy/core-functionality/ai-column-setup

Setting up AI Conversation Outcomes ensures your AI assistant knows exactly how to handle each type of customer response — keeping conversations moving toward booked appointments and closed jobs.

<div>
  <iframe />
</div>

### The three outcome types

Your AI can sort each conversation into one of three outcomes:

1. **Success** — when a lead reaches the goal of your campaign (e.g. booking an appointment)
2. **Bailout** — when a human needs to step in
3. **Discard** — when a lead opts out or is no longer interested

### Step 1: Access your inbox

1. Log in to your Hatch account
2. Go to your **Inbox**, where incoming replies from leads appear
3. Select a conversation to view how the AI agent interacts with the lead

### Step 2: Configure the Success outcome

A Success occurs when the lead achieves your campaign goal — such as booking an appointment or scheduling a job.

1. Go to your **AI Settings** or **Campaign Settings** panel
2. Locate the **Conversation Outcomes** section
3. Under **Success**, define what actions should trigger this outcome
4. Name your success column (e.g. "Set Appointments" or "Schedule Follow-up")

<Tip>Contacts in the Success column should be quickly reviewed to confirm that all appointments are booked and logged in your CRM.</Tip>

### Step 3: Configure the Bailout outcome

A Bailout is when your AI recognizes a real person should take over — for example when the customer asks for a call, requests pricing, or has a question requiring a human touch.

1. Under **Conversation Outcomes**, open the **Bailout** tab
2. Define your bailout triggers (e.g. customer requests call, complex inquiry)
3. Assign the conversation to your CSR or team queue

<Tip>Set up notifications so your team is instantly alerted when a bailout occurs. Your CSR should review this column daily and prioritize outreach to these contacts.</Tip>

### Step 4: Configure the Discard outcome

A Discard is for leads who are not interested, have opted out, or are otherwise unqualified.

1. Under **Conversation Outcomes**, open the **Discard** section
2. Define what messages should trigger this outcome (e.g. "Stop," "Not interested")
3. Move these contacts automatically into your discard column

<Tip>It's often worth giving these contacts a quick phone call to confirm their opt-out — some may prefer to talk rather than text.</Tip>

### Step 5: Review and test your setup

1. Send yourself a test campaign message
2. Reply in ways that should trigger each outcome (success, bailout, discard)
3. Verify that the AI moves conversations to the correct columns
4. Adjust triggers or messages if needed

### Step 6: Keep your team aligned

Ensure your team knows how to:

* Check the **Success** column to finalize appointments
* Review **Bailout** conversations daily
* Confirm **Discard** leads are properly closed


# Audiences
Source: https://docs.usehatchapp.com/academy/core-functionality/audiences

Build dynamic contact lists using Audience Builder to target the right people with the right campaigns.

<div>
  <iframe />
</div>

### Related docs

[Audience Builder Overview](/how-to-use-hatch/audience-builder-v2/audience-builder-v2-field-picker)

[Audience Templates](/getting-started/audience-builder/audience-templates)


# Campaigns
Source: https://docs.usehatchapp.com/academy/core-functionality/campaigns

Build campaigns that automatically send messages to contacts via text, email, voice, and voicemail drop.

<div>
  <iframe />
</div>

### Related docs

[Campaign Basics](/how-to-use-hatch/campaigns/campaign-basics)

[Create a Campaign](/how-to-use-hatch/campaigns/create-a-campaign)


# Removal Rules
Source: https://docs.usehatchapp.com/academy/core-functionality/removal-rules

Set up removal rules to automatically stop messaging contacts when they reach key milestones or statuses.

<div>
  <iframe />
</div>

### Related docs

[Removal Rules & Templates](/how-to-use-hatch/removal-rules-templates)


# Salesboard
Source: https://docs.usehatchapp.com/academy/core-functionality/salesboard

Use the Salesboard to manage active conversations, track contact status, and take action from one view.

<div>
  <iframe />
</div>

### Related docs

[Salesboard Basics](/how-to-use-hatch/board-contact-card/salesboard-basics)


# Workflows
Source: https://docs.usehatchapp.com/academy/core-functionality/workflows

Automate how contacts move between campaigns using Workflows triggered by CRM events and contact activity.

<div>
  <iframe />
</div>

### Related docs

[Workflows Overview](/how-to-use-hatch/workflows/workflows-overview)


# A Day in the Life
Source: https://docs.usehatchapp.com/academy/csr-training/a-day-in-the-life

Walk through a typical day for a CSR using Hatch — from handling inbound replies to following up on open conversations.

<div>
  <iframe />
</div>


# Contact Card Functionality
Source: https://docs.usehatchapp.com/academy/csr-training/contact-card-functionality

Learn how to use the contact card to view history, send messages, update statuses, and manage conversations.

<div>
  <iframe />
</div>

### Related docs

[Contact Card Basics](/how-to-use-hatch/board-contact-card/contact-card-basics)


# Salesboard Filters
Source: https://docs.usehatchapp.com/academy/csr-training/salesboard-filters

Use Salesboard filters to focus on the right contacts and conversations at the right time.

<div>
  <iframe />
</div>

### Related docs

[Salesboard Basics](/how-to-use-hatch/board-contact-card/salesboard-basics)


# Workspace Settings
Source: https://docs.usehatchapp.com/academy/csr-training/workspace-settings

Configure workspace-level settings including call forwarding, recording, and business hours.

<div>
  <iframe />
</div>

### Related docs

[Call Forwarding Setup](/how-to-use-hatch/workspace-settings/how-to-setup-call-forwarding-for-your-workspace)

[Recording Calls in Hatch](/how-to-use-hatch/workspace-settings/recording-calls-in-hatch)


# CRM Integrations
Source: https://docs.usehatchapp.com/academy/integrations/crm-integrations

Integrating your CRM with Hatch ensures your leads, contacts, and customer data flow seamlessly into your workspace — keeping your outreach automated, personalized, and powerful.

<video>
  <source type="video/mp4" />
</video>

### Step 1: Open the Integrations Menu

1. In your Hatch workspace, open any workspace dropdown (e.g. **Speed to Lead**)
2. Click **Integrations** from the dropdown menu

### Step 2: Welcome to the Hatch Marketplace

You'll now be in the Hatch Marketplace, where you can connect both native and non-native tools directly to Hatch.

### Step 3: Click the CRM Tab

At the top of the Marketplace, click **CRM** to view all available integrations.

### Step 4: Connect Your CRM

All CRMs listed are natively integrated with Hatch and sync automatically every 15 minutes. Find your CRM and click **Connect**.

#### Example: Connecting ServiceTitan

1. Find **ServiceTitan** and click **Connect**, then **Configure**
2. Open a new browser tab and log in to your **ServiceTitan** account
3. Go to **Settings → Integrations → API Application Access**
4. Copy your **Tenant ID**, paste it into Hatch, and send it to your Hatch Account Manager for activation
5. Once your Account Manager confirms, click **Connect New App** (top-right in ServiceTitan)
6. Select **Hatch (Official)** from the app list
7. Copy the **Client ID** and paste it into the Hatch integration page
8. Click **Generate** to create your **Client Secret**, then copy and paste it into Hatch — click **Next**
9. Select your data sync options. Recommended: Appointments, Appointment Assignments, Technicians & Employees, Tag Types, Memberships, Membership Tags, Recurring Services, Equipment (for install campaigns)
10. Set data return destinations — choose from Job Notes, Customer Notes, and/or Location Notes
11. Click through remaining setup prompts keeping the same settings
12. Toggle **Calendar Integration** to ON so Hatch can publish appointments directly into ServiceTitan
13. Click **Finish**

### Step 5: Complete the Integration Flow

Follow the step-by-step instructions in the left-hand sidebar. Once complete, click outside the setup window to return to your dashboard. Your integration should now show as **Active**. Give Hatch about 15 minutes to pull in your CRM contacts.

### Step 6: For Non-Native CRMs

If your CRM isn't listed, click **Other** to open the **CRM Authorization Form**. This allows Hatch to securely connect to your CRM reports and upload data automatically each day. Depending on your CRM, you can either provide login credentials or create an admin-level user for Hatch.

### Step 7: Wait for Data Team Setup

Once submitted, give the Hatch Data Team **2–3 business days** to complete setup. After that, your CRM reports will automatically sync — no manual uploads required.

### Related docs

[Integration Overview](/integrations/general/integration-overview)

[Understanding Your Integration](/integrations/general/understanding-your-integration)


# Lead Sources
Source: https://docs.usehatchapp.com/academy/integrations/lead-sources

Connect your lead sources to Hatch so new leads are automatically enrolled in the right campaigns.

<div>
  <iframe />
</div>

### Related docs

[Lead Sources Overview](/integrations/lead-sources/activeprospect-integration)

[Zapier + Hatch: Integrate with Lead Sources](/integrations/lead-sources/zapier-hatch-integrate-with-lead-sources)


# Hatch Academy
Source: https://docs.usehatchapp.com/academy/overview

Step-by-step video lessons to get your Hatch account live — from first login to a fully trained team.

Welcome to Hatch Academy. Each lesson is a short video walkthrough covering everything you need to go live — account setup, integrations, AI configuration, and CSR training.

Work through the sections in order, or jump to the one you need.

<CardGroup>
  <Card title="Account Setup" icon="circle-user" href="/academy/account-setup/10dlc-registration">
    Register for 10DLC, invite your team, and create workspaces.
  </Card>

  <Card title="Integrations" icon="plug" href="/academy/integrations/crm-integrations">
    Connect your CRM and lead sources so data flows into Hatch automatically.
  </Card>

  <Card title="Core Functionality" icon="sliders" href="/academy/core-functionality/ai-column-setup">
    Set up AI columns, campaigns, audiences, workflows, and removal rules.
  </Card>

  <Card title="AI Agents" icon="robot" href="/academy/ai-agents/business-profile">
    Configure your AI agent's business profile, persona, decision tree, and Voice AI.
  </Card>

  <Card title="CSR Training" icon="graduation-cap" href="/academy/csr-training/a-day-in-the-life">
    Train your team on the Salesboard, contact cards, and day-to-day Hatch workflows.
  </Card>
</CardGroup>


# Audience Templates
Source: https://docs.usehatchapp.com/getting-started/audience-builder/audience-templates

Pre-built Audience Builder queries covering popular use cases

### What are audience templates?

Audience templates are pre-built Audience Builder queries covering our most popular use cases and CRMs. Currently the template gallery covers ServiceTitan, LeadPerfection, and improveit360 with more to come.

### How do I use an audience template?

<img alt="" />

Create a new audience from the audiences page. You'll be taken to the audience templates page.

<img alt="" />

Select the relevant CRM (e.g. "LeadPerfection) on the left and desired use case (for example, "Past Customers Nurture"), and hit the View Template button.

You will then see a dialogue box that tells you what to customize (for example, the timeline and campaign history) for this templated audience.

### <img alt="audience template explanation example" />

You'll then get taken to the Audience Builder page, and the fields you can customize will be outlined in blue. All other fields will be filled in for you.

<img alt="audience template example" />

### What is audience targeting and why is it important?

The key to sending effective messages to leads and customers is in making them personalized and accurate. But the broader your audience, the more generalized (and impersonal) they have to be in order to stay accurate. When you target specific audiences, you create smaller segments that share certain characteristics so you can achieve the personalized piece as well.

### What is an Audience in Hatch?

Your Audience is who you are targeting with your Campaigns. You cannot launch a Campaign unless it has people to receive those messages!

For example, the Audience for a Speed to Lead campaign is new leads. For a Sales Follow-Up Campaign, it’s recently quoted leads. For a Nurture or Rehash campaign, it’s aged leads. And the Audience Builder helps you to refine those segments (for example, which lead source? Exactly how recent or how aged?).

But you don’t have to go into your CRM, create the list, then download it and upload it to Hatch. Because Hatch integrates with your CRM and lead sources, you define the Audience right within Hatch and it will automatically add and remove contacts from that Audience list as they meet the criteria.

### How do I build an Audience in Hatch?

To access the Audience Builder in Hatch, select the audience icon in the left-hand panel of your Hatch dashboard. Then hit 'Create Audience' once you've reached the Audiences page.

<img alt="" />

You can then build an audience from scratch, or choose from a template. For help with creating an Audience, refer to the [Audience Builder section of our Knowledge Base](/how-to-use-hatch/audience-builder-v2/audience-builder-v2-glossary-and-faq)


# 10DLC Registration (TCPA Compliance)
Source: https://docs.usehatchapp.com/getting-started/compliance/10dlc-registration-tcpa-compliance

What it is, why you need it for TCPA compliance, and how to get approved

### What is 10DLC registration?

10DLC, or 10-digit long code, refers to standard 10-digit phone numbers sanctioned for high-volume Application-to-Person (A2P) messaging (Hatch is the application you're using). These numbers enable businesses to send SMS and MMS messages to customers using local, recognizable phone numbers. To utilize 10DLC numbers for business messaging, companies must complete a registration process with The Campaign Registry (TCR), the organization that manages this system.

### Why 10DLC registration?

The primary goal of 10DLC registration is to reduce spam and fraudulent messaging by verifying the legitimacy of businesses and their messaging use cases. This verification process helps ensure that consumers receive messages from trusted sources, maintaining the integrity of business messaging channels.

### How much does 10DLC registration cost?

10DLC registration requires a one-time setup fee, a one-time A2P campaign use case registration fee, and then monthly campaign fees (generally \$10/month). Please view [TCR's website](https://www.campaignregistry.com/) as well as your mobile carrier's website for the most up-to-date fees.

### Benefits of 10DLC registration

**A 10DLC registration is required to send text messages in Hatch.** Failure to register for 10DLC will result in your messages being blocked or marked as spam by carriers. You may also be fined for sending messages from unregistered numbers.

* **Improved Deliverability:** Registered 10DLC numbers are recognized by carriers, leading to higher message delivery rates.
* **Increased Throughput:** Businesses can send messages at higher volumes and speeds compared to traditional long codes.
* **Compliance Assurance:** Registration ensures adherence to industry standards and carrier requirements, reducing the risk of message filtering or blocking.

### How to get 10DLC approved: Master list

In order to get your 10DLC registration application accepted, your campaigns must adhere to the [Telephone Consumer Protection Act (TCPA)](https://www.fcc.gov/sites/default/files/tcpa-rules.pdf) as well as the [CTIA Messaging Principles & Best Practices](https://www.ctia.org/the-wireless-industry/industry-commitments/messaging-interoperability-sms-mms). This includes four main things:

<Steps>
  <Step title="Create your SMS terms & conditions">
    This is your responsibility—we provide templates below to help you get started.
  </Step>

  <Step title="Create your SMS privacy policy">
    This is your responsibility—we provide templates below to help you.
  </Step>

  <Step title="Add consent verbiage to your website forms">
    This is your responsibility—we provide templates below as guidance.
  </Step>

  <Step title="Include an opt out and company name in the first text">
    This step is taken care of by Hatch—it's built into the app.
  </Step>

  <Step title="Submit your application">
    Hatch submits the application on your behalf after you supply some basic company information.
  </Step>
</Steps>

#### 1. Create your SMS terms and conditions

Your website forms must contain a link to your SMS terms and conditions. This means you either need to:

* Add a terms and conditions page specifically for SMS.
* Add an SMS section to your current terms and conditions page.

Note that this is not legal advice. Please consult your legal counsel. Your SMS terms and conditions must include the following:

1. **Program description:** (Insert program description here; this is simply a brief description of the kinds of messages users can expect to receive when they opt in.)
2. **Frequency:** You will receive (message frequency). **\_\_<u>it's important that this is a specific number; and not a "it varies" type of message.</u> \_\_If you're new to Hatch, and have no idea, "5-10 messages a month based on your project needs." is a great place to start. See the below example for more details**
3. **Opt-out:** You can cancel the SMS service at any time. **Just reply back with \[OPT OUT KEYWORD].** After you send the SMS message **\[**OPT OUT KEYWORD**]** to us, we will send you an SMS message to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time and we will start sending SMS messages to you again.
4. **Help** : If you are experiencing issues with the messaging program you can reply with the keyword HELP for more assistance, or you can get help directly at (support email address or toll-free number).
5. **Interruption:** Carriers are not liable for delayed or undelivered messages
6. **Cost:** As always, message and data rates may apply for any messages sent to you from us and to us from you. If you have any questions about your text plan or data plan, it is best to contact your wireless provider.
7. **Privacy:** If you have any questions regarding privacy, please read our privacy policy: (link to privacy policy)

**SMS terms and conditions example**

**\[Company] SMS/MMS Program Terms & Conditions**

1. **Program description:** When opted-in, you will receive text messages (SMS/MMS) to your mobile number. These kinds of messages may include **\[**response to a quote, estimate, or service inquiry, real-time texts to ask and answer questions about our services and pricing, appointment scheduling and confirmations, feedback requests, project updates, follow up**]**.
2. **Program frequency:** You can expect to receive **\[**number**]** messages per month from us.
3. **Opt out:** You can opt out of this service at any time. Just text “STOP” to the phone number. After you text “STOP” to us, we will send you an SMS reply to confirm that you have been unsubscribed. After this, you will no longer receive SMS messages from us. If you want to join again, just sign up as you did the first time or text “START,” and we will start sending SMS messages to you again.
4. **Help:** If you are experiencing any issues, you can reply with the keyword HELP. Or, you can get help directly from us at **\[**link to your contact page on your website**]**.
5. **Interruption:** Carriers, such as AT\&T, are not liable for delayed or undelivered messages.
6. **Costs:** Message and data rates may apply for any messages sent to you from us and to us from you. If you have any questions about your text plan or data plan, please contact your wireless provider.
7. **Privacy:** If you have any questions regarding privacy, please read our privacy policy **\[**link to privacy policy**]**.

#### **2. Create your SMS privacy policy**

Your SMS privacy policy, discloses how you gather, use, disclose, and manage any personal data or information you collect on your website as it relates to your SMS program.

Just as with your terms and conditions page, you either need to:

* Create a separate page for your SMS privacy policy, or
* Add an SMS section to your existing privacy policy page.

It is not possible to provide a blanket list or template for privacy policies, as these are highly specific to your business. According to [Twilio](https://support.twilio.com/hc/en-us/articles/11847054539547-A2P-10DLC-Campaign-Approval-Best-Practices) and [Constant Contact](https://knowledgebase.constantcontact.com/articles/KnowledgeBase/46730-Example-template-Privacy-Policy-for-SMS?originalUrl=%2Farticles%2FKnowledgeBase%2F45560-Privacy-policies-and-terms-of-service-for-SMS%3Flang%3Den_US\&lang=en_US), your SMS privacy policy must:

* Provide an accurate description of the SMS service, including when and what type of messages users will receive.
* List the kind of personal information you're collecting (name, email address, phone numbers etc).
* List the methods you use to collect personal data (a form, cookies, etc).
* Explain how you're using the personal data you collect (sending emails or text messaging, etc).
* Explain how you store, maintain, and safeguard the personal information you're collecting.
* Explain if, how and why you share personal data with third parties.
  * It's recommend that you call out "**We will never share your contact information for marketing purposes.**", just so it's clear you're not sharing beyond what is required and for marketing.
* Provide a method for correcting, verifying, changing, or removing personal information.

But again, the full list may include other components for your specific business, so please consult your legal representative.

**SMS privacy policy template**

Again, only your legal counsel can lay out for you a fully compliant privacy policy. For a starting point, we recommend using [Constant Contact’s privacy policy template](https://knowledgebase.constantcontact.com/articles/KnowledgeBase/46730-Example-template-Privacy-Policy-for-SMS?originalUrl=%2Farticles%2FKnowledgeBase%2F45560-Privacy-policies-and-terms-of-service-for-SMS%3Flang%3Den_US\&lang=en_US).

Important notes from Constant Contact:

* You must customize this template according to your actual data collection, usage, and disclosure practices. Review each section carefully and add/remove information as necessary.
* Be sure to fill in the yellow/highlighted sections with your own information, and remove all brackets and drafting notes before publishing.
* Their sample privacy policy is not legal advice

#### 3. Add consent verbiage to your website forms

The forms you use to capture leads on your website must contain specific verbiage.

<img alt="10dlc-compliant opt in form example" />

<img alt="10dlc-compliant opt in form example" />

This includes:

* **The telephone number** of the person who is giving permission to receive texts or calls *Aka the form field where the user provides their number*.
  * TCPA requirements say this field needs to be optional for SMS, but it can be required if you outline that on submission that you will contact the individual. (see our example form above)
* A checkbox to allow opt-in for each use case that you intend to send to your customers.
  * An example would be on checkbox for marketing SMS, one checkbox for non-marketing SMS.
  * These checkboxes must **not be checked by default**.
* **The following disclosures:**
  * By checking the SMS opt-in box on the form, the user is opting in to receive text messages. (we’ll provide verbiage on this in a bit)
    * Wrapping in other medians (ie. voice, email) into this statement *may* cause a rejection.
  * *"We will never share your personal information with third parties for marketing purposes."*
    * Translation: customers will only be contacted for the reason they opted-in
  * *"Messaging frequency varies."*
    * Translation: informs customers that the amount of texts they receive can fluctuate based on their needs and interactions
    * **Note**: This language is okay on your opt-in statement, but in your SMS Terms and Conditions, there ***must***\_ \_be a number or range of numbers of intended volume outlined.
  * *“Message and data rates apply.”*
    * Translation: customers may be charged by their cellular service provider for receiving or sending text messages from their devices
  * *“Consent is not a condition of purchase.”*
    * Translation: giving consent to text does not mean the consumer then has to make a purchase
* \*\*The purpose of your campaign \*\**Aka the type of messages customers will receive*
* **Text message frequency** E.g. frequency may vary
* **Link to SMS terms and conditions:** See below
* **Link to SMS privacy policy:** See below

Here is a template you can use. Note that this is not legal advice. Please check with your legal counsel to make sure you have the right verbiage.

> *By checking, you authorize **\[**company**]** to reach out to you via text for information about appointment setting and any other project needs. We will never share your personal information with third parties for marketing purposes. Messaging frequency varies based on your project needs. You can opt out at any time by replying STOP. Reply HELP if you are experiencing issues. Message/data rates apply. Consent is not a condition of purchase.*
>
> *<u>Terms and conditions</u> | <u>Privacy Policy</u>*

Do keep in mind, if you plan on sending **marketing** outreach to your end customers, to closely follow the example image provided above.

#### 4. Make sure your text messages meet the requirements

This is taken care of by Hatch, but for your information:

* Every automated text you send prior to getting a response from the customer must include your company name.

For example:

* Hi Tom, this is Jen from Window Planet.
* Hi Tom, Window Planet here
* Hi Tom, this is the Window Planet team.
* Hi Tom **\[**insert message here**]** -Jen from Window Planet

This is built-in with Hatch, so you won't be able to launch a campaign without it.

2. Provide opt out instructions.

This is also built right into Hatch. The requirement is that the first text of any campaign must include a clear instruction on what word the customer can text back to opt out.

For example:

* Reply STOP to unsubscribe.
* Reply STOP to end messages.
* Opt out any time by replying END.
* Reply UNSUBSCRIBE to stop messages.

This word MUST be in all caps in your text. And it must be one of the following words:

* STOP, UNSUBSCRIBE, END, CANCEL, QUIT, STOPALL, ARRETT, ARRET, ARRETE
  * \*\*This IS an exhaustive list of official terms, you cannot use synonyms.

#### 5. Submit your application

Your Campaign Service Provider (aka Hatch) must submit your application on your behalf. Hatch customers can provide this information to us by [filling out this form](https://app.usehatchapp.com/account/compliance?__hstc=169681061.a43102117fc969827251b96b81f26528.1731694289835.1734541920006.1734563168962.98&__hssc=169681061.6.1734563168962&__hsfp=336580338). You will need:

* Employee identification number (EIN) or Tax ID
* Legal business name
* Brand Name / DBA
* Business type (LLC, sole proprietor, or corporation)
* Company type (public vs. private)
* Business Industry
* Website URL (where your customer fills out the form, ie. [www.usehatchapp.com/contact-us](http://www.usehatchapp.com/contact-us))
* Business address
* Contact information
* Outbound calling statistics (approximations are totally fine)

We'll take care of the rest.

Please take a minute to submit your registration information to us as soon as possible to ensure the highest success with your text messaging campaigns.

#### **What happens if my registration or campaign is rejected?**

If your 10DLC registration is rejected due to missing opt-in requirements, we’ll notify you automatically via email. This will, in most cases, include specifically what needs fixed. Once the fixes are made, we will resubmit your application for 10DLC registration. Registrations are currently taking about four to five business days to complete; depending on how far along you were in the registration process.

### **Additional resources**

From the FCC (Federal Communications Commission)

* The [TCPA privacy section](https://www.fdic.gov/resources/supervision-and-examinations/consumer-compliance-examination-manual/documents/8/viii-5-1.pdf) that documents the company identifier requirement (which can be found via the FDIC's [Consumer Compliance Examination Manual).](https://www.fdic.gov/resources/supervision-and-examinations/consumer-compliance-examination-manual/)
* [2015 Omnibus Declaratory Ruling and Order](https://www.fcc.gov/document/tcpa-omnibus-declaratory-ruling-and-order) that text messages are subject to the same TCPA restrictions as phone calls.
* [FCC Fact Sheet](https://docs.fcc.gov/public/attachments/DOC-391239A1.pdf)
* [FCC TCPA Summary](https://www.fdic.gov/resources/supervision-and-examinations/consumer-compliance-examination-manual/documents/8/viii-5-1.pdf)
* [CTIA's Messaging Principles and Best Practices](https://www.ctia.org/the-wireless-industry/industry-commitments/messaging-interoperability-sms-mms)
* [Twilio’s 10DLC Campaign Approval Best Practices](https://support.twilio.com/hc/en-us/articles/11847054539547-A2P-10DLC-Campaign-Approval-Best-Practices)


# With all these new compliance rules, how can I make sure my messages get delivered?
Source: https://docs.usehatchapp.com/getting-started/compliance/with-all-these-new-compliance-rules-how-can-i-make-sure-my-messages-get-delivered

Use this guide to create text campaigns that not only get delivered, but that also get responses. 

### [>> Hatch Messaging Best Practices Guide](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/HATCH%20GUIDE%20TO%20TEXTING.pdf)

Compliance has ramped up over the past couple of months — and we get it — it has been a major pain in the neck.

Not just because you’ve had to jump through hoops, but also because failure to comply with all these new rules can negatively impact your revenue, your reputation, and how much ROI you get from Hatch.

So that’s why we’ve created this guide. It contains exactly what you need to ensure success with compliance, which ensures success with your business as a whole.

It contains:

* The exact TCPA and technical messaging requirements to ensure your texts get delivered (with examples)
* Best practices to ensure the highest response rates and ROI with Hatch (also with examples)
* Legal documentation verbiage and templates
* All of your compliance FAQs and a glossary of terms to know

### **[Click here to access the guide](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/HATCH%20GUIDE%20TO%20TEXTING.pdf)**


# Calendar
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/commands-calendar

Book appointments on your ServiceTitan calendar

With the Hatch AI + ServiceTitan integration, your AI agent (text or voice) can provide customers with available time slots on your calendar, and once the customer picks the best one for them, actually book it on your calendar.

Use it for qualifying and scheduling new leads directly from your AI conversations.

## How It Works

1. Your AI agent qualifies the contact for an appointment
2. The agent consults your ServiceTitan calendar and presents available time slots
3. Once the contact picks a time, the agent confirms the appointment
4. The appointment is created on your ServiceTitan calendar
5. The contact card moves to your configured disposition in Hatch (if set up)

## Setting Up Calendar Integration

<Info>
  Before setting up calendar integration, you need to have ServiceTitan integrated with Hatch. See the [ServiceTitan Integration](/integrations/crm-field-management-systems/servicetitan-integration) setup guide.
</Info>

### Adding the Calendar Command

In your AI Agent Instructions, type `/calendar` to insert the calendar command. Place it in your instructions where you want the bot to book the appointment.

```markdown theme={null}
## Schedule Appointment

Once the customer is ready to book, use /calendar to schedule the appointment. Use any customer data you already have (name, address, phone) and collect any missing information as needed.
```

When you insert the `/calendar` command, it appears as an inline button in your instructions. Click the button to configure your calendar settings.

### Configuring the Calendar Command

After inserting the command, you'll configure:

1. **Calendar Type** - Choose Bookings or Dispatch calendar
2. **Sales Board Column** - Where to move conversations after booking
3. **Disposition** - What disposition to assign after booking
4. **Business Units & Job Types** - Select which business units and their associated job types the bot can book
5. **Additional settings** - Lookup period, arrival windows, and more

## Business Units & Job Types

Business units are organizational groupings in ServiceTitan, and each business unit contains its own set of job types. When configuring the calendar command, you'll select:

1. **Business Units** - Choose which business units the bot can book appointments for
2. **Job Types** - For each business unit, select which job types are available for booking

### Job Types Configuration

For each job type within a business unit, you can add descriptions and set priority settings.

<Frame>
  <img alt="Job Types configuration with High Priority toggle" />
</Frame>

* **Description**: Add a description for each job type to help your AI agent understand when to use it
* **High Priority**: Enable this toggle to ignore capacity limits for this job type

<Note>
  Use High Priority for urgent or high-value jobs where you want to allow same-day booking. When enabled, the bot will ignore capacity limits but still respects Lead Time and Workspace Business Hours.
</Note>

## ServiceTitan Configuration Settings

The ServiceTitan Configuration section provides additional settings for how your bot interacts with your calendar.

<Frame>
  <img alt="ServiceTitan Configuration settings" />
</Frame>

| Setting                                 | Description                                                                                                                                                                                                                               |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Capacity Source**                     | Choose whether Hatch reads Adjustable or Adaptive Capacity from ServiceTitan. Must match your ServiceTitan setup — see [Calendar: ServiceTitan Adaptive Capacity](/getting-started/hatch-assistant/commands-calendar-servicetitan-ad-cap) |
| **Priority Bookings Minimum Lead Time** | Set the minimum time before an appointment can be booked                                                                                                                                                                                  |
| **Assign Technician**                   | Automatically assign a technician to the job (Dispatch calendar only)                                                                                                                                                                     |
| **Use Skill-Based Availability**        | Use technician skills to determine availability                                                                                                                                                                                           |
| **Arrival Windows**                     | Enable arrival window time slots (must match your ServiceTitan settings)                                                                                                                                                                  |
| **Transfer without availability**       | Allow the bot to transfer calls even when no calendar availability exists                                                                                                                                                                 |
| **Lookup Period**                       | Configure the date range for checking availability                                                                                                                                                                                        |

<Warning>
  If you enable Arrival Windows, make sure this matches your ServiceTitan settings or appointments will NOT schedule on your calendar.
</Warning>

## Bookings vs Dispatch

ServiceTitan offers two different calendars. When setting up your bot, you choose which calendar you want the bot to auto-book appointments on.

### Bookings Calendar

The Bookings calendar is for setting the appointment with the customer.

**What it looks like in ServiceTitan:**

* A booking is created on the Bookings calendar
* No job is created yet - someone on your team will need to convert the booking to a job and assign a technician

### Dispatch Calendar

The Dispatch calendar is for identifying which tech to send out and other operational purposes.

**What it looks like in ServiceTitan:**

| Scenario                                          | What Happens                                                                                                                                                                                                                        |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **With Assign Technician enabled**                | Job appears on the Dispatch board with a technician already assigned                                                                                                                                                                |
| **With Dispatch Pro (no technician assigned)**    | Job appears in the unassigned tray at the bottom of the Dispatch board, then gets auto-assigned based on your Dispatch Pro settings (business unit, job type, skills, technician availability, time window, service location, etc.) |
| **Without Dispatch Pro (no technician assigned)** | Job appears in the unassigned tray at the bottom of the Dispatch board, where someone will need to manually assign it to a technician                                                                                               |

## Time Zones

ServiceTitan uses Coordinated Universal Time (UTC), while Hatch uses North American time zones. Hatch converts the UTC times to your workspace's timezone before presenting them to customers.

<Note>
  Make sure your workspace time zone matches the location it corresponds to.
</Note>

## Multiple Time Zones

If you have a workspace that covers multiple time zones, it's best to assign each time zone its own workspace so your bot can keep times accurate.

Note that time zones can't be assigned per business unit in ServiceTitan. For more help, refer to [ServiceTitan's Time Zone Help Article](https://community.servicetitan.com/t5/Call-Booking/Time-Zone-Selection-from-Call-Booking-Screen/td-p/24159).


# Calendar: ServiceTitan Adaptive Capacity
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/commands-calendar-servicetitan-ad-cap

Connect your Adaptive Capacity rules so your AI agent books appointments that follow them

If your business runs Adaptive Capacity in ServiceTitan, your Hatch AI agent can book against it directly. The agent asks ServiceTitan for availability, ServiceTitan applies the rules you've configured, and the agent only offers times that are bookable under those rules.

This article covers how to turn it on and how to confirm it's working. If you're on Adjustable Capacity, no action is needed — Adjustable is fully supported and nothing here applies to you.

## Before you start

You'll need:

* **Adaptive Capacity enabled in ServiceTitan**: This is a ServiceTitan feature. Hatch connects to it but can't enable it for you.
* **Capacity assigned in ServiceTitan**: Adaptive Capacity doesn't create availability on its own. Your technicians, business units, and job types still need capacity configured.
* **Access to ServiceTitan settings**: Some steps require the Settings area. If you don't have access, loop in whoever administers your ServiceTitan account.
* **Manager role in Hatch**: Required to edit your AI agent's commands.

## Step 1: Confirm you're on Adaptive Capacity

In ServiceTitan, open **Settings** (the gear icon) and search for `cap`.

* **If an Adaptive Capacity section appears**: You're on Adaptive. Continue to Step 2.
* **If it doesn't appear**: You're on Adjustable Capacity, and no changes are needed.

<Note>
  ServiceTitan recommends against running Adjustable and Adaptive at the same time. If you've recently moved to Adaptive, confirm that Adjustable has been turned off.
</Note>

## Step 2: Update your ServiceTitan API access

Adaptive Capacity uses a newer set of ServiceTitan API permissions. Until you approve them, Hatch can't read your Adaptive rules.

Follow the steps in [How to upgrade the ServiceTitan app](/integrations/crm-field-management-systems/servicetitan-integration#how-to-upgrade-the-servicetitan-app). In short: open **Settings** → **API Application Access** in ServiceTitan, and if the **Hatch (Official)** app shows an **Update to the New Version** option, select it and click **Allow Access**.

<Warning>
  This is the most common reason Adaptive Capacity doesn't work after setup. If Hatch reports that ServiceTitan denied the request, start here.
</Warning>

## Step 3: Set your capacity source in Hatch

In Hatch, open your AI agent's **Decision Tree** → **Agent Instructions**, then open your [Calendar command](/getting-started/hatch-assistant/commands-calendar). If you don't have one yet, create it with `/Calendar`.

1. Choose the **Advanced — Dispatch** calendar type.
2. Go to **Calendar** → **ServiceTitan Configuration**.
3. Scroll to **Capacity Source** and select **Adaptive**.

<Info>
  This setting has to match how your ServiceTitan account is actually configured. Hatch can't detect your capacity type automatically. If the two don't match, your agent will keep booking appointments successfully but won't apply your Adaptive rules.
</Info>

## Step 4: Test the connection

In your Calendar command, click **Test Configuration**, choose a business unit and job type you know are set up in ServiceTitan, then click **Fetch Availability**.

The test runs in three numbered steps — **Availability**, **Book**, then **Cancel** — and reports each capacity type separately.

### Reading your results

Two rows come back, one per capacity type:

* **Adaptive Capacity** *(Hatch Dispatch slots)* — the Adaptive connection
* **Legacy / Adjustable** *(ServiceTitan capacity)* — the older connection

Each row shows either a slot summary (for example `12 slots · Mar 3 – Mar 7`), **Empty**, or **Error**.

| What you see                                                            | What it means                                                                                                                                                                              |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Adaptive Capacity** with a slot count                                 | Working. Your agent will book against your Adaptive rules.                                                                                                                                 |
| **Adaptive Capacity: Empty**                                            | Connected, but ServiceTitan returned no availability for that business unit and job type. Check that a technician has capacity for it and that no Adaptive rule is removing that capacity. |
| **Adaptive Capacity: Error** — "ServiceTitan denied the request"        | Your API access hasn't been updated. Return to [Step 2](#step-2-update-your-servicetitan-api-access).                                                                                      |
| **Legacy / Adjustable** returns slots even though you only run Adaptive | Expected. The two connections report independently. What matters is that your Capacity Source setting matches your real setup.                                                             |
| Both rows show **Error**                                                | Start with [Step 2](#step-2-update-your-servicetitan-api-access). If it persists, contact Hatch support.                                                                                   |

### Booking a test appointment

After fetching availability you can optionally click **Book test appointment**. This places a real appointment on your ServiceTitan dispatch board using a default Hatch test customer, which confirms the full path works rather than just the availability lookup. Hatch shows the customer, business unit, job type, appointment ID, and status so you can match it against ServiceTitan.

If the button is disabled, the message reads *"Disabled — the configured capacity source returned no slots"* — there's nothing available to book, so resolve the Empty result first.

To remove the test appointment, pick a **cancel reason**, then click **Cancel appointment**. The status changes to *Canceled*. You don't need to leave Hatch.

## What your agent follows

With Capacity Source set to Adaptive, Hatch asks ServiceTitan to apply your account's own Adaptive Capacity configuration — your **Basic Settings**, **Advanced Settings**, and **Strategic Rules**. That covers rules targeting specific technicians, job types, skills, tags, and business unit groups, whether they run continuously or only on certain days, times, or date ranges, along with one-off overrides.

One thing to know about how times reach your customers:

* **Your agent offers arrival windows, not exact start times**: If you use arrival windows in ServiceTitan, callers hear the window — "someone will arrive between 8am and 12pm."

<Note>
  Hatch draws from the same capacity pool your team does. When your agent books an appointment, that slot is consumed exactly as if a CSR had booked it. Hatch doesn't rearrange your dispatch board or change your capacity rules.
</Note>

## Troubleshooting

### My agent isn't offering any times

Run **Test Configuration** for the business unit and job type in question. If it returns Empty or 0 slots, the issue is capacity in ServiceTitan rather than the Hatch connection. Confirm a technician has capacity for that combination and that no Adaptive rule is removing it.

### I switched to Adaptive but nothing changed

Check two things, in order: that you completed [Step 2](#step-2-update-your-servicetitan-api-access) in ServiceTitan, and that **Capacity Source** in your Calendar command is set to Adaptive. Both are required.

### The times my agent offers don't match what I see in ServiceTitan

Your agent may offer fewer options than a manual ServiceTitan lookup shows. Times are grouped into arrival windows, and your workspace may have additional rules restricting which windows the agent can offer. This is expected.

### We changed our capacity setup in ServiceTitan

Tell your Hatch account team. The Capacity Source setting doesn't update on its own, and if it no longer matches ServiceTitan your agent will keep booking successfully without applying your current rules.

## Related articles

* [Calendar command](/getting-started/hatch-assistant/commands-calendar)
* [ServiceTitan integration](/integrations/crm-field-management-systems/servicetitan-integration)
* [How to switch to the Hatch application of ServiceTitan](/integrations/crm-field-management-systems/how-to-switch-to-the-hatch-application-of-servicetitan)
* [Prepare for Adaptive Capacity](https://help.servicetitan.com/how-to/set-up-adaptive-capacity) (ServiceTitan)


# Calendar: LeadPerfection
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/commands-leadperfection-calendar

Book appointments on your LeadPerfection calendar

With the Hatch AI + LeadPerfection integration, your AI agent (text or voice) can provide customers with available appointment times from LeadPerfection, and once the customer picks the best one for them, actually book it in LeadPerfection.

## How It Works

1. Your AI agent qualifies the contact for an appointment
2. The agent looks up the contact in LeadPerfection and collects the product interest and service address
3. The agent consults LeadPerfection availability and presents available appointment times
4. Once the contact picks a time, the agent confirms the appointment
5. The appointment is created in LeadPerfection
6. The contact card moves to your configured Sales Board column and disposition in Hatch
7. If enabled, the conversation summary is posted to the prospect's Notes in LeadPerfection

## Setting Up Calendar Integration

<Info>
  Before setting up calendar integration, you need to have LeadPerfection integrated with Hatch. See the [LeadPerfection Integration](/integrations/crm-field-management-systems/leadperfection) setup guide.
</Info>

<Warning>
  The LeadPerfection user that authorizes the integration must have API access. In LeadPerfection, go to *Security -> User Access*, select *Assign* for the user, open the *Function Level Security* tab, choose *APISecurity* from the dropdown, select *Check All*, and click *Save*. Without these permissions, calendar lookups and bookings will fail.
</Warning>

### Enabling the Calendar Command

First, navigate to your LeadPerfection integration in Hatch. Select "Reconfigure" in the integration configuration, and enable the toggle that says "Enable Calendar Integration" on the second page.

### Adding the Calendar Command

In your AI Agent Instructions, type `/calendar` to insert the calendar command. Place it in your instructions where you want the bot to book the appointment.

When you insert the /calendar command, it appears as an inline button in your instructions. Click the button to configure your calendar settings.

### Configuring the Calendar Command

After selecting LeadPerfection as your calendar source, you'll configure:

1. Product Types - Which LeadPerfection products the bot can book, and a description for each
2. LeadPerfection Settings - Attribution user, default note, lookup period, and additional settings
3. Hatch Assignment Settings - Sales Board column, disposition, and assignee applied after booking
4. Message Sent After Appointment Booked - An optional message sent to the contact after the appointment is created

#### Product Types

Product types come from your LeadPerfection product list. When configuring the calendar command, you'll select which products the bot is allowed to book, then add a description for each one.

* Product Type: Select one or more products from your LeadPerfection catalog
* Description: Describe when this product should be used

<Note>
  When adding a product type, it's required to add descriptions on each item. This will help ensure the best possible performance from the agent — the description is what the agent uses to decide which product a customer's request maps to, and it's also what the customer hears when the agent offers options.
</Note>

At least one product type is required. If the customer's request doesn't map to a configured product type, the bot will not be able to check availability.

#### LeadPerfection Configuration Settings

| Setting                       | Description                                                                                                                                                                                                                     |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attribution User              | Required. The LeadPerfection employee credited as the source of appointments booked by this assistant. Populated from your active LeadPerfection employees. Note, this will only populate if the lead exists in LeadPerfection. |
| Product Types (Multiple)      | Required. The products the bot can book, each with a description                                                                                                                                                                |
| Default Note                  | Standard note added to appointments or leads, and will display in the Inbound Queue                                                                                                                                             |
| Lookup Period                 | The window when appointments can be booked, from your selected start through 14 days from today                                                                                                                                 |
| Starts on                     | When the lookup period starts: Immediate, 1–4 days from now, or 1 week from now                                                                                                                                                 |
| Transfer Without Availability | When enabled, the assistant transfers the conversation to a live agent even if no calendar availability is found                                                                                                                |
| Add summary to prospect       | When enabled, the conversation summary will be added to the Notes section of the matched prospect after the conversation completes. On by default                                                                               |
| Update customer address       | When enabled, Hatch will update the address of an existing lead if the address is incomplete/different than what is in LeadPerfection. Off by default                                                                           |

<Note>
  The lookup window is always 14 days from today. **Starts on** only moves the front edge of that window — it does not extend it. For example, setting Starts on to "3 days from now" gives the bot days 3 through 14.
</Note>

<Info>
  If your Attribution User list is empty, Hatch could not retrieve employees from LeadPerfection. Check the API security permissions on the integration user, then enter the LeadPerfection employee ID manually.
</Info>

#### Conversation Summary

With Add summary to prospect enabled, Hatch posts the AI conversation summary to the prospect's Notes in LeadPerfection after the conversation ends. The note includes a Hatch Summary header, a link back to the Hatch conversation, and the summary itself.

For appointments booked as new leads that are detected as duplicates, the prospect record doesn't exist in LeadPerfection until someone processes it out of the Inbound Queue. Hatch will keep retrying the summary for up to 3 days while it waits for the prospect to be created.

#### Test Configuration

Before finishing setup, use the Run test button in the LeadPerfection settings step to verify Hatch can access the calendar endpoints it needs.

The test checks the API permissions on your integration user for the endpoints Hatch uses to read employees, products, availability, customers, prospects, notes, and the sales schedule.

<Warning>
  If the test reports a permissions error, go back to *Security -> User Access -> Function Level Security -> APISecurity* in LeadPerfection and select *Check All* for the integration user. A failed test does not block you from saving, but the bot will not be able to book until the permissions are corrected.
</Warning>

#### Hatch Assignment Settings

These settings control what happens on the Hatch side once an appointment is booked.

| Setting            | Description                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| Sales Board Column | Required. The column where conversations with appointments booked by this command will be placed       |
| Disposition type   | Required. The disposition assigned to conversations with appointments booked by this command           |
| Assignee           | Who should be assigned conversations with appointments booked by this command, to help with follow-ups |

## How Appointments Land in LeadPerfection

What the bot creates depends on whether it found a matching prospect with a settable lead.

| Scenario                                | What Happens                                                                                                                                                                                                |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Existing prospect with an open lead     | The appointment is set directly on that lead, so it appears on the sales schedule right away                                                                                                                |
| New prospect                            | A new lead and appointment are created together. If lead is not detected as a duplicate, the appointment will be set. If a duplicate lead is detected, it will end up in your inbound queue to be reviewed. |
| Existing prospect with no settable lead | Handled the same as a new prospect                                                                                                                                                                          |

## Customer Matching

The bot searches LeadPerfection by first name, last name, and phone. Email can be used to narrow things down when more than one prospect matches. If the search returns multiple possible matches, the bot asks the customer for additional details.

## Service Address

The bot collects and validates the customer's service address, and uses the ZIP code to scope availability to the right branch. After a booking, Hatch reconciles the validated address back onto the prospect record in LeadPerfection so the appointment goes to the right place.

## Appointment Times

LeadPerfection availability is returned as appointment slots defined by your LeadPerfection scheduling configuration. Hatch only offers times that match your configured slots in your "Time Slots" settings in LeadPerfection.

<Note>
  LeadPerfection slots are appointment start times, not arrival windows. The bot presents only the start time (for example, "we have 9:00 AM, 1:00 PM, or 5:00 PM available") and confirms the booking with the date and start time only.
</Note>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Where do the offered appointment times come from?">
    The appointment times offered are based off of the Time Slots configured in LeadPerfection. To see these in LeadPerfection, navigate to Setup -> Customer -> Time Slots.
  </Accordion>

  <Accordion title="Why is the bot saying the customer is outside our service area?">
    The bot utilizes your LeadPerfection markets to determine if a customer is in your service area. Please ensure your specified markets in LeadPerfection have all Zip Codes you service.
  </Accordion>
</AccordionGroup>


# Service Area
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/commands-service-area

Validate that a customer's location is within your service area

The Service Area command allows your bot to validate whether a customer's location falls within your defined service areas before proceeding with booking or other actions.

## Adding the Service Area Command

In your AI Agent Instructions, type `/servicearea` to insert the command. Place it where you want the bot to check the customer's location.

```markdown theme={null}
## Qualify the Customer

1. Ask for the customer's address or zip code
2. Use /servicearea to verify they're in your coverage area
3. If they're outside your service area, politely let them know
4. If they're in your service area, proceed with scheduling
```

## Configuring Service Areas

When you create a service area, you choose the type:

* **Zipcode** - Define coverage by zip codes
* **City-State** - Define coverage by city and state pairs

### Zipcode Format

Enter zip codes separated by commas:

```
90210, 90211, 90212, 90213
```

**Supported formats:**

* US 5-digit: `90210`
* US ZIP+4: `90210-1234` (the base 5-digit code is used for matching)
* Canadian: `A1A1A1`

### Using Wildcards

You can use wildcards (`*`) to match multiple zip codes with the same prefix:

**US Zipcodes:**

```
902*
```

This matches all zip codes starting with 902 (90210, 90211, 90212, etc.)

**Canadian Postal Codes:**

```
M5V*
```

This matches all postal codes starting with M5V (M5V1A1, M5V2B2, etc.)

<Note>
  Wildcards can save time when you serve entire regions. Instead of listing every zip code individually, use a prefix with `*` to cover them all.
</Note>

### City-State Format

Enter city-state pairs separated by newlines:

```
New York, NY
Los Angeles, CA
Chicago, IL
```

City-state matching is case-insensitive.


# Setup Guide
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/hatch-assistant-setup-guide

Get a walkthrough of all the steps you need to set up your first AI agent in Hatch.

### What are Hatch AI Agents?

Hatch AI Agents allow you to create custom AI bots that converse with your leads, prospects, and customers over text or voice, then take the appropriate action in Hatch based on the conversation outcome.

Hatch AI doesn't simply recommend responses or provide coaching for your agents; it actually converses with leads and customers just as a human agent would - and according to the instructions and prompts you create.

### AI Agent Playground

The AI Agent playground is where you configure and test your bot. It has four main tabs:

* **Persona**: Configure your bot's name, voice, and personality
* **Knowledge**: Set up your business profile, FAQs, documents, and customer data
* **Decision Tree**: Configure triggers, greeting messages, and AI agent instructions

<Frame>
  <img alt="AI Agent Playground showing the Persona tab" />
</Frame>

***

## Persona Tab

The Persona tab is where you define your bot's identity and behavior settings.

<Frame>
  <img alt="Persona tab with AI Agent Name, Voice, and Spam Call Filter settings" />
</Frame>

### AI Agent Name

Give your bot a name that will be used when introducing itself to customers. Choose a name that fits your brand and feels natural in conversation.

### Voice

For Voice AI agents, select the voice your bot will use when speaking to callers. You can preview different voices to find one that matches your brand personality.

### Spam Call Filter

Configure how your bot handles potential spam or abandoned calls.

**How spam calls are detected:**

A call is classified as spam/abandoned when the caller:

* Immediately hangs up after connecting, OR
* Doesn't speak within 10 seconds of the greeting

The detection works in two phases:

1. Your bot greets the caller and waits 5 seconds for a response
2. If no response, the bot repeats the greeting and waits another 5 seconds
3. If still no response after 10 total seconds, the call is marked as spam/abandoned

**What happens when spam is detected:**

When you enable the Spam Call Filter, you can configure:

* **Column**: Which salesboard column to move the conversation to
* **Disposition**: What disposition to assign to the call

The bot will politely end the call and the conversation will be routed according to your settings, keeping your inbox clean from abandoned calls.

***

## Knowledge Tab

The Knowledge tab is your bot's brain - it's where you provide all the information your bot needs to answer customer questions accurately.

<Frame>
  <img alt="Knowledge tab showing Business profile, FAQs, Documents, and Customer Data" />
</Frame>

### Business Profile

Select or create a Business Profile that contains key information about your company. Your bot will reference this information when answering customer questions.

Business profiles can include:

* Business name and category
* Services offered
* Business hours
* Service areas
* Pricing information
* Policies and procedures

### Frequently Asked Questions

Add common questions and their answers. When customers ask these questions, your bot can provide accurate, consistent responses.

Click **+ Add Item** to add new FAQ entries.

### Documents

Upload documents (PDF, TXT, or TIFF formats, up to 5 MB) that contain information your bot should know. This could include:

* Service guides
* Product catalogs
* Policy documents
* Training materials

### Customer Data

Link customer data fields from your CRM so your bot can personalize conversations. For example, you can connect:

* Hatch Contact: firstName
* Hatch Contact: lastName
* Custom fields from your integrations

This allows your bot to greet customers by name and reference their specific information.

***

## Decision Tree Tab

The Decision Tree tab is where you configure how your bot handles conversations - from the initial trigger to the AI instructions that guide every interaction.

<Frame>
  <img alt="Decision Tree tab showing Set Trigger and AI Agent Instructions" />
</Frame>

### Set Trigger

Configure what triggers your bot to start a conversation:

* **Select Trigger**: Choose the trigger type (e.g., Inbound Phone Call, Campaign message)
* **Workspace**: The phone number/workspace associated with this bot
* **After Hours Agent**: Toggle to enable after-hours mode (see [Voice AI: After Hours Bot](/getting-started/hatch-assistant/voice-ai-after-hours-bot))
* **Greeting Message**: The first message your bot says when a conversation starts

### AI Agent Instructions

This is the core of your bot - a single comprehensive prompt that tells your bot how to handle conversations.

<Frame>
  <img alt="AI Agent Instructions showing Background and Core Instructions" />
</Frame>

Your AI Agent Instructions typically include:

#### Background

Provide context about who the bot is and what company it represents:

> *You are a highly trained customer service representative with years of experience assisting customers on behalf of **Hatch Heating & Cooling**, a family-owned business providing efficient and affordable comfort systems in New York, NY.*

#### Core Instructions

Define the conversation flow and what information to gather:

> **Initial Contact & Issue Identification**
>
> When a customer calls, warmly greet them and figure out why they are calling.
>
> We support heating systems and HVAC. This includes:
>
> * Gas boilers
> * Heat pumps (split systems and air-to-water)
> * Furnaces
> * Water heaters

#### Decision Logic

Include conditions and branching logic directly in your instructions:

* If the customer's answer is vague, request additional details
* If the customer mentions an emergency, prioritize accordingly
* If the customer asks about pricing, reference your service rates

#### Formatting Tools

Use the toolbar at the bottom of the instructions panel:

* **Generate**: Use AI to help write or improve your instructions
* **Format**: Convert your script into an AI-friendly format
* **Extract**: Pull structured information from your instructions

### Commands

Commands are special actions your bot can take during conversations. Click within your AI Agent Instructions to insert commands.

<Frame>
  <img alt="Commands menu showing End Conversation, Calendar, Transfer, Knowledge, Service Area, and Unmask Masked Leads" />
</Frame>

Available commands include:

| Command                 | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| **End Conversation**    | End the conversation with a configured disposition, column, and assignee   |
| **Calendar**            | Book appointments on your calendar                                         |
| **Transfer**            | Assign the conversation to a team member or transfer a call                |
| **Knowledge**           | Retrieve specific information from a Knowledge Source                      |
| **Service Area**        | Check that an address is in your service area                              |
| **Unmask Masked Leads** | Extract and update real contact information from masked lead conversations |

***

## Compliance Note for Voice AI

If your AI agent makes outbound voice calls, your greeting or instructions must include:

* Your company name (via the `[[Details Company Name]]` snippet)
* A disclosure that the call is automated (e.g., "This is an automated call," "I'm a virtual assistant," or similar language)

This is required by TCPA regulations for automated calls.

***

## Testing Your Bot

### Sandbox

The right side of the playground is your Sandbox - a testing environment where you can interact with your bot before publishing.

**For text bots:** Type messages to simulate customer conversations.

**For voice bots:** Click **Start Session** to have a voice conversation with your bot using your microphone.

#### What to test:

* The "happy path" - a successful conversation
* Missing or incomplete information
* Bailout scenarios (customer wants to talk to a human)
* Discard scenarios (unqualified leads)
* Vague or confusing responses
* Edge cases specific to your business

### Publishing Your Bot

Once you're satisfied with your bot's performance:

1. Click the **Publish** button in the top right
2. Review the summary of your bot configuration
3. Confirm to make your bot live

<Warning>
  After publishing, your bot will immediately start handling real conversations. Make sure you've thoroughly tested all scenarios.
</Warning>

### Editing a Published Bot

To make changes to a published bot:

1. Click **Edit** to enter editing mode
2. Make your changes to the configuration
3. Test the changes in the Sandbox
4. Click **Publish Changes** to apply updates

Your bot stays live while you make edits - changes only take effect when you publish them.

***

## Creating a New Bot

1. Navigate to the **AI Agents** section in your workspace
2. Click **Create and configure**
3. Click the **+** button to create a new bot
4. Choose to create from a **template** or start **from scratch**

### Bot Templates

Templates come with pre-configured instructions for common use cases:

**Industries:**

* HVAC, Plumbing, Electrician
* Roofing
* Windows and Doors
* Solar
* And more...

**Use Cases:**

* Speed to Lead
* Appointment Scheduler
* Appointment Confirmations
* Sales Follow Up

### Duplicating a Bot

If you have a well-configured bot and want to use similar settings for another campaign, you can duplicate it. The duplicate will copy all instructions and settings to a new bot that you can customize.


# Outbound Voice AI
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/outbound-voice-ai



Hatch’s voice agent can make outbound phone calls! With all the capabilities of an inbound voice agent, Hatch’s outbound agent can automate some of the repetitive calls required to keep in close contact with your customers. Learn more about how to set up an outbound voice AI agent below.

[**Important compliance reminder:** Federal and state laws impose restrictions on the use of outbound voice AI technology, including requiring consent from call recipients before making such calls.](https://docs.usehatchapp.com/getting-started/hatch-assistant/outbound-voice-ai#how-can-i-use-outbound-voice-ai) The type of consent needed will depend on whether the call is made for marketing purposes or transactional purposes.

### *How does it work?*

Outbound voice AI calls are **fully compatible with existing outbound SMS and email campaigns**—they're a 'step' like any other.

Before integrating an outbound AI call step into campaigns, an outbound voice AI bot needs to be configured in the AI playground. Create a new agent using an existing template, or build from scratch and select 'outbound phone call' as the agent's trigger. Some tips on prompting:

* State the purpose of the call clearly in the prompt (e.g. "You are calling a customer to confirm their upcoming appointment")
* Unlike an inbound agent, which has one greeting message for all calls, the outbound agent's greeting message is **configured in the campaign builder**. This allows one outbound agent to handle multiple use-cases (e.g. both 'thanks for submitting your webform' and 'we received your Yelp inquiry').
  * Experiment with different greeting messages and hone your prompt by chatting to your agent on the persona tab
* The outbound agent is otherwise identical to the inbound agent! It can make appointments, transfer calls, and handle customer questions.
  <Frame>
    <img alt="Ezgif 539dc60a428e6a4c" />
  </Frame>

Once the outbound voice AI agent is published, you can put it to work in an outbound campaign. Simply select a 'phone call' step in the campaign editor, and configure the following:

* **AI Agent** - which outbound voice bot should make this call
* **Greeting Message** - what the bot should say when the contact picks up the phone. Notes on this step:
  * This message is compatible with [snippets](https://docs.usehatchapp.com/how-to-use-hatch/campaigns/snippets#snippets)—the bot will first fill in any values associated with the contact for the snippet fields (e.g. using a 'first name' snippet in the example below, the bot will say "*Hi John, this is an automated*..."). This lets you tailor each conversation to a specific contact!
  * Once these values are filled in, the bot will say them word-for-word. If values are formatted oddly in a CRM, they will be read out oddly (e.g. "your appointment at 20:00 GMT minus five")
  * Federal guidelines mandate that an automated outbound call proactively identifies the business responsible for the call, and discloses that the call is automated. You'll need to use the \[\[Details Company Name]] snippet, as well as words such as ai, automated, bot, digital or virtual to ensure compliance.

<Frame>
  <img alt="Screenshot 2026 03 02 At 3 27 47 PM" />
</Frame>

* **Custom voicemail (or hang up)** - Instruct the bot on how to handle instances where a call is not picked up by the contact. The bot will either leave a custom voicemail (compatible with snippet values, will use the voice configurations in the playground), or just hang up the call. Each of these calls are billed differently:
  * A picked up call qualifies as a 'Voice AI conversation'
  * A custom voicemail has a 20 cent fee by default
  * An attempted call (that is simply hung up) has a 10 cent fee by default

Once a contact [meets the criteria for a workflow](https://docs.usehatchapp.com/how-to-use-hatch/workflows/workflows-overview) associated with your outbound voice AI campaign, they'll receive the outbound phone call as scheduled. You can add prior and subsequent steps to a campaign with an outbound voice AI step—e.g. an email that says 'we'll call you shortly to ask some questions about your job' could be followed by a call, or a call could be followed by a text that says 'we just tried calling—prefer to book online? Go to [www.website.com/booking](http://www.website.com/booking)'.

A few points worth noting:

* When an outbound voice AI call is picked up, the contact is **removed from the campaign** and marked as 'replied'. Subsequent steps in the campaign will not reach the contact—so a text that says 'we tried calling!' won't reach a contact that already spoke to the outbound agent.
* Outbound voice AI calls will only ever go out between the hours of 8am to 9pm, in line with federal guidelines on telemarketing calls. If a call is scheduled after hours, it will remain queued until the 8am the next day. Subsequent text / human call steps may be triggered in this period.
* You can find recordings of completed outbound voice AI calls on the contact card, and track the results of outbound voice AI campaigns on the reporting page.

### *How can I use outbound voice AI?*

We strongly recommend consulting with **your legal counsel** before using outbound voice AI to ensure your compliance with all applicable laws, including the Telephone Consumer Protection Act (TCPA), a federal law that governs use of AI calls and generally requires that call recipients expressly consent to such calls.

The TCPA imposes especially **strict limits** on outbound voice AI calls, and various states may also have laws that impose similar or additional limits. **Unless you have prior <u>express written consent</u> from a call recipient to receive outbound voice AI calls**, you should not use outbound voice AI for marketing calls, including:

* Contacting inactive leads
* Promotional or marketing calls (even if combined with transactional calls)
* Unsolicited cold calling

Can I use Outbound Voice AI for Transactional Calls?

Consent is also required for use of outbound voice AI calls made for transactional purposes, although such consent need not be in writing. Generally, you may use outbound voice AI for **transactional or operational purposes** when:

* You have prior express consent to make such calls using voice AI, such as a customer providing their phone number through a webform, or over the phone, after being informed of the use of outbound voice AI; or
* The transactional calls are made to landlines (not cell phones). 

**Examples of transactional calls may include:**

* Appointment reminders
* Follow-ups to requests for estimates
* Recurring service notifications
* Responding to leads with specifically requested information, for example requests sent through a webform

Note: There may be additional restrictions around outbound calls, for example, the timing and frequency of calls.


# Review your new AI Agent
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/review-your-new-ai-agent

Where to find and review the calls and conversations your new AI agent is handling.

Your AI agent is live. Now you need to see what it's actually doing.

Every call your Voice AI agent takes, and every conversation your AI text agents handle, lands on the [Conversations page](/how-to-use-hatch/conversations/conversations) — a real-time log of all customer interactions across your organization. That page is where you review your agent's work, spot what it's getting wrong, and tell us about it.

<img alt="Conversations" />

## A first review pass

For a newly launched Voice AI agent, this is a good half hour:

<Steps>
  <Step title="Open the Voice tab and filter to your agent">
    Set the **Agent Type** filter to **Chatbot**, pick your agent, and set a date range covering since it went live. See [Using the filters](/how-to-use-hatch/conversations/conversations#using-the-filters).
  </Step>

  <Step title="Start with the calls that should have booked">
    Filter **Booking Status** to **Not booked** — bookable calls where no booking was made. These are your missed opportunities, and the fastest route to improving the agent.
  </Step>

  <Step title="Check what it handed off">
    Filter **Handling** to **Transferred** to see which calls the agent passed to a person, and decide whether it should have handled them itself. See [Live Transfers](/getting-started/hatch-assistant/voice-at-live-transfers).
  </Step>

  <Step title="Listen to a few in full">
    Click into a conversation to play the recording, read the transcript, and check the **Context** tab. See [How to Review Conversations](/how-to-use-hatch/conversations/reviewing-conversations).
  </Step>

  <Step title="Flag anything that went wrong">
    If a call didn't go the way it should, flag it from the side drawer with a note. Your Hatch team picks it up and works it through to resolution. See [Flagging a Call](/how-to-use-hatch/conversations/flagging-a-call).
  </Step>
</Steps>

<Tip>
  Reviewing calls regularly in the first few weeks is the single biggest thing you can do to improve a new agent. The metrics tell you which calls to listen to; flagging tells us what to fix.
</Tip>

## Related Articles

* [Conversations Page](/how-to-use-hatch/conversations/conversations): the log itself, its columns, and its filters.
* [Glossary](/how-to-use-hatch/conversations/glossary): what each metric means and how it's calculated.
* [How to Review Conversations](/how-to-use-hatch/conversations/reviewing-conversations): opening a call, listening to it, and flagging an issue.
* [Hatch Assistant Setup Guide](/getting-started/hatch-assistant/hatch-assistant-setup-guide): building and tuning the agent itself.


# After Hours Bot
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/voice-ai-after-hours-bot

Learn how to create and publish a separate Voice AI agent for after hours calls

With the After Hours Bot feature, you can create a completely separate Voice AI agent to handle inbound calls outside of your business hours. This allows you to provide different experiences for callers depending on when they call.

### How It Works

You can publish up to two Voice AI agents per workspace:

* **Business Hours Bot**: Handles calls during your published workspace business hours
* **After Hours Bot**: Handles calls outside of your business hours

When a call comes in, Hatch automatically routes it to the appropriate bot based on the current time and your workspace's business hours settings.

### Setting Up an After Hours Bot

#### Step 1: Create a New Voice AI Agent

1. Navigate to the Hatch AI Agent playground
2. Create a new Voice AI agent (or duplicate an existing one)
3. Configure the agent with instructions appropriate for after-hours scenarios

#### Step 2: Enable After Hours Mode

1. In your bot's configuration, locate the **After Hours Agent** toggle in the Set Trigger panel
2. Enable the toggle to mark this agent as an after-hours bot
3. Click the settings gear icon to configure business hours

<Frame>
  <img alt="After Hours Agent toggle in the Set Trigger panel" />
</Frame>

<Warning>
  You cannot change the after-hours setting on a published agent. If you need to change it, you must unpublish the agent first.
</Warning>

#### Step 3: Configure Business Hours

Your after-hours bot uses your workspace's business hours to determine when to activate. Click the settings gear icon next to the After Hours Agent toggle to open the business hours configuration:

<Frame>
  <img alt="Customize Business Hours modal showing daily schedule settings" />
</Frame>

1. Toggle each day to **Open** or closed
2. Set the start and end times for each day
3. Use the **+** button to add multiple time ranges per day (e.g., for lunch breaks)
4. Click **Save** to apply your changes

<Note>
  Modifying the business hours here modifies them for the entire workspace. This can impact other features such as SMS campaign automations.
</Note>

The after-hours bot will handle all calls that come in outside of these configured hours.

### Publishing Requirements

There are specific requirements for publishing after-hours bots:

<Info>
  **You must publish a Business Hours bot before you can publish an After Hours bot.** This ensures that calls during business hours are always handled appropriately.
</Info>

| Scenario                                         | Allowed? |
| ------------------------------------------------ | -------- |
| Publish only a Business Hours bot                | Yes      |
| Publish only an After Hours bot                  | No       |
| Publish both Business Hours and After Hours bots | Yes      |

When you publish an after-hours bot, the system verifies that a business hours bot is already published for that workspace. If not, you'll see an error message asking you to publish a business hours bot first.

### Unpublishing Behavior

When you unpublish your **Business Hours bot**, your **After Hours bot will automatically be unpublished** as well. This cascade behavior ensures that your workspace always has proper coverage during business hours.

<Warning>
  If you unpublish your business hours bot, be aware that your after hours bot will also be unpublished. You'll need to republish both if you want to restore after-hours coverage.
</Warning>

### Call Routing Logic

Here's how Hatch determines which bot handles an incoming call:

1. **During business hours**: The Business Hours bot handles the call
2. **Outside business hours**: The After Hours bot handles the call (if published)
3. **Outside business hours with no After Hours bot**: The Business Hours bot handles the call as a fallback
4. **No business hours configured**: The Business Hours bot always handles calls

This fallback behavior ensures that calls are never dropped, even if you haven't set up an after-hours bot.

### Best Practices

#### When to Use an After Hours Bot

Consider creating a separate after-hours bot when you want to:

* Provide different booking options (e.g., next-day appointments only)
* Set different expectations for response times
* Offer emergency-only services after hours
* Use a different tone or persona for evening/weekend callers
* Route calls differently (e.g., only transfer emergencies)

#### Configuring Your After Hours Bot

When setting up your after-hours bot, consider these tips:

1. **Set clear expectations**: Let callers know they're reaching you after hours and when they can expect a callback
2. **Handle emergencies**: Configure transfer rules for urgent situations that need immediate attention
3. **Simplify options**: After-hours callers may prefer faster, simpler interactions
4. **Adjust scheduling**: If your bot books appointments, consider limiting available slots to business hours

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I have different after-hours bots for different days?">
    No, you can only have one after-hours bot per workspace. However, you can configure your business hours to have different hours for different days of the week, and the after-hours bot will activate accordingly.
  </Accordion>

  <Accordion title="What happens if I only want an after-hours bot?">
    You cannot publish only an after-hours bot. A business hours bot must be published first. If you want all calls to go to the same bot regardless of time, simply use a business hours bot without enabling an after-hours bot.
  </Accordion>

  <Accordion title="Can I test my after-hours bot before publishing?">
    Yes! You can test your after-hours bot in the playground just like any other bot. The playground allows you to simulate conversations regardless of the current time.
  </Accordion>

  <Accordion title="How do I know which bot handled a call?">
    The contact card and call records will show which bot handled the conversation. You can also see this information in your reporting dashboard.
  </Accordion>

  <Accordion title="What if I haven't configured business hours for my workspace?">
    If no business hours are configured, the system defaults to using your business hours bot for all calls. The after-hours bot will never activate until you configure business hours.
  </Accordion>
</AccordionGroup>


# Live Transfers
Source: https://docs.usehatchapp.com/getting-started/hatch-assistant/voice-at-live-transfers

How Hatch's Voice AI agent can connect callers to human users

Hatch's Voice AI agent can book appointments and answer customers' questions about your business, but you might have calls where you'd prefer to get some human expertise. Maybe:

* When a customer requests emergency service, you'd like to forward the call to a personal number
* When a customer requests to speak to a specific employee or department, you'd like to direct that call to the relevant party
* If the Voice AI agent can't answer a question, or gets the sense a customer only wants to speak to a human, you'd prefer to get an operator involved
* Once the Voice AI agent qualifies that a caller meets some criteria, you'd like to forward them to a specific line

Of course, you'd prefer to  *keep the customer on the line* while this happens—these situations are where live transfers come in handy!

In the Hatch Assistant playground, Voice AI subscribers can set up a live transfer using the `/transfer` command.

* Ensure the 'trigger' for your bot is an inbound phone call to the Hatch workspace of your choice
* In your chatbot instructions, add a line for the situation in which you'd like the Voice AI agent to transfer the call
  * For example:  `if the caller requests emergency service /transfer`

Once you add this command into your AI Agent Instructions, you'll be able to choose one of two live transfer types: to the external phone number of your choosing, or a live transfer within Hatch.

#### External Phone Transfer

<Frame>
  <img alt="Screenshot 2026 03 09 At 12 57 53 PM" />
</Frame>

There are three things to configure in the playground for an external phone transfer:

* The phone number to which a call should be transferred
* Decide whether to have the bot provide a summary of a call
  * *Yes -* the customer will be placed on hold, and the bot will read a summary of the first leg of the call (e.g. 'the customer requested to be escalated to a manager') to the transfer recipient
  * *No -* the customer will be connected to the external phone number directly. When the transfer recipient picks up, they will be connected to the customer immediately.
* Instructions for the AI Agent, i.e. "what should the agent say when they transfer the caller?"

<img alt="" />

In cases where a bot will read out a summary, you may want the instructions to reflect that there may be a period where the customer will be on hold (e.g. *"Please hold while I connect you to someone who can help"*)

Once the command is configured, a live external transfer has three steps:

* **Step one:** The customer (either a caller or an outbound call recipient) triggers the `/transfer` command in the instructions. The situation you've told the Voice AI agent to look out for and transfer the call, occurs in this first leg of the call. Whatever transfer instructions have been added for the agent occurs now—the agent will tell the customer to "please hold" or similar.
* **Step two:** A call will go out to the external phone number specified in the command, and will retain the customer's caller ID (for inbound voice AI) or will appear to be from the Hatch workspace number (for [outbound voice AI](https://docs.usehatchapp.com/getting-started/hatch-assistant/outbound-voice-ai) calls). The customer is either placed on hold while a summary is read to the transfer recipient, or is connected immediately.
* **Step three (if summary is active):** The summary is read to the transfer recipient, while the contact remains on hold. Then, the transfer recipient is connected to the contact *"This is a transfer from your Hatch AI assistant. Customer John Smith requested emergency service as his hot water is off. Connecting you now\..."*

That's it!

*What happens if I don't pick up the call when the transfer happens?*

* The transferred call behaves just like a normal inbound call to the external number, so the original caller will be connected to the voicemail box of the external phone number, or however the external phone number is configured

*How will I know which of my Hatch contacts were transferred?*

* All transferred conversations are saved with a disposition of 'transferred', which you can see in your reporting dashboard, and all calls to your Hatch workspace will appear at the top of the Inbox column of your salesboard.

<Frame>
  <img alt="Screenshot 2026 03 11 At 7 30 04 AM" />
</Frame>

*Can I do this for multiple phone numbers?*

* Yes! If you want to say "if the caller asks for Sally, transfer to Sally" as well as "if the caller ask for Bob, transfer to Bob", that all works as expected.

#### Live Transfers within Hatch

<Frame>
  <img alt="Screenshot 2026 03 11 At 7 31 22 AM" />
</Frame>

If the live transfer should occur within Hatch, two things need to be configured:

* Which Hatch workspace the call should be transferred to
* Instructions for the AI Agent, i.e. "what should the agent say when they transfer the caller?"

You can set up live transfers to any Hatch workspace that shares contacts with your Voice AI agent, including the workspace where the agent is configured! Just like an external transfer, Hatch will track that a caller called one workspace, and the contact was transferred to a second workspace on the contact card.

For a live transfer within Hatch, there are two steps:

<Frame>
  <img alt="Screenshot 2026 03 11 At 7 32 00 AM" />
</Frame>

* **Step one:** A customer calls your Hatch phone number, and triggers the `/transfer` command. The situation you've told the Voice AI to look out for and transfer the call, occurs in this first leg of the call. Whatever transfer instructions have been added for the agent occurs now—the agent will say "I'll transfer you now" or similar, as instructed.
* **Step two:** An inbound call notification appears in whichever Hatch workspace has been designated as the one to receive the transfer. You'll see a short summary of what happened on the first leg of the call, and can pick up the call to start speaking to the contact immediately.

*What happens if no one picks up the transfer?*

* The customer will be prompted to leave a voicemail to your Hatch number, the call behaves just like a normal inbound call.

*What if I have call forwarding set up for the workspace in question?*

* The transfer will respect call forwarding preferences within Hatch! So the forwarded call will be forwarded onto the number specified (with the caller's caller ID shown), but there will be no summary either read by the bot nor shown on a modal.

*How will I know which contacts were transferred?*

* The contact card will appear at the top of the inbox column, and will show a record of which bot transferred the contact, as well as which workspace the contact was transferred from (if relevant). A recording of the first leg of the conversation will also be available in the side bar.

<Frame>
  <img alt="Screenshot 2026 03 11 At 7 30 04 AM" />
</Frame>


# Core Campaigns and Use Cases 
Source: https://docs.usehatchapp.com/getting-started/intro-to-hatch/core-campaigns



Hatch supports several campaign types designed to cover the full customer journey. These campaigns help ensure the right message goes out at the right time — without manual effort.

### **Speed to Lead**

Automatically reach out to new leads the moment they submit a form or request information.

### **Missed Call Follow-Up**

Automatically follow up with contacts who called but didn’t connect, helping you recover missed opportunities.

### **Estimate Follow-Up**

Stay in touch with customers after an estimate is sent to answer questions and keep the conversation moving.

### **Lead Nurture**

Re-engage older leads that didn’t book, went cold, or paused their project.

### **Customer Care**

Send updates, reminders, and check-ins throughout the customer lifecycle, including installs and project milestones.

### **Customer Recontact**

Reconnect with past customers who may be ready for additional work or follow-up.

### **Marketing Blasts**

Send one-time messages to a targeted audience, such as announcements or promotions.

### **24/7 Call Handling**

Hatch also supports 24/7 call handling to answer and route inbound calls, whether for after-hours, overflow, or full-time coverage. Unlike the campaigns above, this isn’t automated outreach; it’s always-on handling that ensures your customers always reach someone.


# Hatch Glossary
Source: https://docs.usehatchapp.com/getting-started/intro-to-hatch/hatch-glossary

This glossary covers the core building blocks of Hatch. Understanding these terms will make the rest of the Help Center easier to follow.

### **Contact**

A contact is a person you communicate with in Hatch. Contacts usually come from lead sources, your CRM, or manual uploads.

### **Conversation Card**

A conversation card represents an ongoing conversation with a contact. It shows messages, call history, contact details, and status — all in one place.

### **Campaign**

A campaign is a sequence of messages (SMS, email, voice) sent automatically over time. Campaigns are used for things like speed to lead, follow-up, nurture, and more.

### **Audience**

An audience is a group of contacts that meet certain conditions. Audiences are used to determine who should enter a campaign.

### **Workflow**

A workflow controls automation in Hatch, connecting audiences to campaigns. When a contact meets the audience criteria, the workflow automatically enrolls them in the campaign.

### **Salesboard**

The Salesboard is where your team works conversations. It’s a Trello-style shared inbox where you can view, respond to, assign, and organize active conversations. Each workspace has one Salesboard.

### **Workspace**

A workspace groups campaigns, contacts, conversations, and settings together. Each workspace has its own phone number,email address, and Salesboard.

### **Organization (Org)**

Your organization is the top-level account in Hatch. It contains all of your workspaces, users, and global settings.

### **AI Agent**

An AI agent can respond to customers automatically using approved messaging and rules. AI agents can answer questions, qualify leads, and book appointments—with your team stepping in for more complex or sensitive conversations.

### **Business Profile**

Your business profile stores information like your company name, branding, and business details used in messages and AI responses.

### **Decision Tree**

A decision tree guides AI behavior by defining how it should respond based on customer answers or intent.


# Minimum Requirements for Using Hatch
Source: https://docs.usehatchapp.com/getting-started/intro-to-hatch/minimum-requirements-for-using-hatch

Curious about what the technical requirements are to run Hatch? We've put together some helpful information about our supported browsers and operating systems (OS).

### Web Browsers

Connect to Hatch from the web on your device at anytime at [app.usehatchapp.com](https://app.usehatchapp.com/). Just make sure it's one of our supported browsers.

| **Browser**    | **Requirements**      |
| -------------- | --------------------- |
| Chrome         | Version 77 or above   |
| Firefox        | Version 70 or above   |
| Safari         | Version 12.1 or above |
| Microsoft Edge | Version 18 or above   |

To update an outdated browser, use [this website](https://bestvpn.org/outdatedbrowser/en) to get all the latest versions of popular browsers.

### Mobile Devices

Hatch can be accessed on mobile or tablet devices using Mobile Browsers. However, we have optimized our site for certain Operating Systems.

| **Operating System** | **Requirements**     |
| -------------------- | -------------------- |
| iOS                  | iOS 11.1 or above    |
| Android              | Android 5.0 or above |

### Unsupported browsers and OS

To focus on delivering the best possible experience in Hatch, it is necessary to keep the list of supported browsers and operating systems short. When a browser is no longer supported, we stop fixing bugs and issues.

**Need Help?** If you are having trying to update, but find yourself getting stuck, reach out to our team.


# What is Hatch?
Source: https://docs.usehatchapp.com/getting-started/intro-to-hatch/what-is-hatch

Hatch is an AI-powered communication platform built for service businesses. It helps you respond to leads faster and follow up more consistently throughout the customer journey—across voice, SMS, and email. With everything in one place, you can deliver a better customer experience without juggling multiple tools.

### **How Hatch works**

As you know, service businesses win or lose revenue based on how quickly and consistently they communicate with customers. Hatch combines automation, AI, and humans to make sure every lead and customer gets a fast, consistent response—without overwhelming your team. Here’s how Hatch works at a high level:

* **Campaigns fire automatically**: Based on CRM triggers, Hatch sends outreach via SMS, email, or voice at the right time
* **AI handles the response**: When customers reply or call, AI picks up the conversation, qualifies them, answers questions, and books appointments
* **Humans step in when needed**: Complex or sensitive conversations get routed to your team with full context
* **Everything syncs automatically**: Outcomes, notes, and transcripts flow back to your CRM

All of this happens in one platform, where every conversation with a contact lives in a single card. On your end, you see the full picture. On the customer's end, it just feels like a normal text or call.

### **Who uses Hatch?**

Hatch serves home services and home improvement businesses of all sizes—from single-location shops to multi-brand, multi-location enterprises.

Common roles that use Hatch daily:

* **CSRs, dispatchers, and appointment setters** use Hatch to manage conversations, handle escalations, and stay organized
* **Marketing and sales leaders** use Hatch to create campaigns, tweak templates, and track performance across the funnel
* **Owners and executives** use reporting dashboards to see ROI and understand what's driving results

Whether you're trying to book more leads, reduce no-shows, re-engage past customers, or just stop missing calls, Hatch provides the AI infrastructure to make it happen consistently.


# What is Speed to Lead?
Source: https://docs.usehatchapp.com/getting-started/intro-to-hatch/what-is-speed-lead

Learn why and how to reach out to leads immediately.

<Note>
  \_Note: If you're not a Hatch user, you can learn more about improving your speed to lead with our [Speed to Lead eBook](https://www.usehatchapp.com/playbooks/speed-to-lead)
</Note>

Speed to Lead focuses on one thing: reaching new leads immediately.

When someone submits a form or requests information, Hatch ensures they hear from you right away — even if your team is busy.

### **Why Speed to Lead matters**

Responding quickly increases your chances of:

* Connecting with the lead
* Booking an appointment
* Winning the sale

When multiple vendors are contacted at once, the business that responds first often earns the conversation.

### **How Speed to Lead works in Hatch**

1. **Integrate your lead sources**\
   Hatch connects to web forms, Google LSA, and numerous lead providers like Yelp, [Angi](https://docs.usehatchapp.com/integrations/lead-sources/angi-leads-integration) or [Modernize](https://docs.usehatchapp.com/integrations/lead-sources/modernize-integration).
2. **Create a Speed to Lead campaign**\
   Campaigns typically include SMS, email, and voice sent over one or more days.
3. **Automate enrollment**\
   As soon as a lead submits a request, Hatch creates a contact and adds them to the campaign automatically.
4. **Respond when they reply**\
   When the lead responds, automation pauses and the conversation appears on your Salesboard. A team member — or AI agent — can take over.

### **Example messages**

Hatch provides best-practice campaign templates you can customize to fit your business. Here are the first two text messages in a typical Speed to Lead sequence:

Launch **text**

Hey \[\[Contact First Name]], this is \[\[User First Name]] with \[\[Company Name]]. I got your information from the form you submitted. Text me back with what you’re looking for!.

**Day 2 text**

Hi \[\[Contact First Name]]. I haven’t heard back since you submitted your form. Text me back with the details.

Note: These are just two texts across two days. Our templates also include emails, voicemails, and phone calls.

### **Supported lead sources**

Hatch integrates directly with several lead providers including (but not limited to) Yelp, Google LSA, Angi, Modernize, Homebuddy, webforms, and more. The list continues to grow, and web forms can also be connected using Hatch’s standard API.

To get started or learn more, reach out to your Account Manager.

***


# Calling in Campaigns
Source: https://docs.usehatchapp.com/getting-started/messaging/calling-in-campaigns

Add phone calls to your campaign cadence

***What’s new with calling in campaigns?*<img alt="" />**

Calling in campaigns allows you to manage your outreach campaigns via a new channel in Hatch: phone calls. While you’ve been able to make and receive calls in Hatch, it’s operated separately from the text, email and voicemail drops of a campaign cadence.

Now, you can add a phone call as part of your outreach strategy within Hatch, right from the campaign editor.

***How does this actually work?*<img alt="" />**

When a contact hits a “phone call” step in a campaign cadence, their contact card pops up at the top of your inbox column. It looks similar to an unread text message, but with a green border rather than a blue border.

The card will say what campaign the phone call step came from, and clicking the card will let you take a look at the contact’s opportunity data and contact history, so you’ll have context on them before starting a call.

***Ok, I’m ready—I know who I’m calling and why! Now what?***

First, if you’re planning to call contacts from a lead source that uses [temporary contact information](/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch), such as Yelp or [Angi](/integrations/lead-sources/angi-ads-integration), make sure that any Hatch numbers you’re planning to call with are whitelisted with those third parties before you start calling.

Second, you might want to make sure your Hatch number is registered with major carriers’ analytic providers. Registering your number with [Free Caller Registry](https://www.freecallerregistry.com/fcr/) and [First Orion](https://portal.firstorion.com/) is a good way to make sure carriers know your Hatch number is associated with your business.

Otherwise, you’re ready to go! Just hit ‘Make a call’ or the phone icon in your toolbar to make a phone call to your customer.

***We had a great conversation! Now what?*<img alt="" />**

This is where phone calls are different from other campaign steps: Hatch doesn’t know what happened on your call, so it needs feedback from the user (you) to know what should happen to the contact. This is where *dispositioning* comes in.

At the end of any outbound call, you’ll be prompted to record a call disposition. It’s a helpful feature for tracking your interactions with a customer, as well as managing what communication will go to them in the future.

Here’s the (current) list of dispositions, and what they do:

> *Not Answered:* if a call hasn’t been answered, nothing needs to change for the contact. They’ll remain in any active campaigns, and receive messaging for subsequent steps in the campaign.

> *Answered:* if a call is answered, there’s usually some kind of follow-up, and it’s probably more specific than the subsequent steps in your campaign can account for.<img alt="" />

Hitting ‘Answered’ will take the contact out of the campaign (with a campaign status of ‘replied’), so you can handle the contact directly on your salesboard.

You’ll be prompted to send the contact card to a column—whichever column you choose, it will be reflected back on your salesboard, and you can add a note to explain what was discussed on your call.

If you set an appointment on your call, you could move the contact to your ‘sold’ column. If a contact asks you to follow-up later, you could move the contact to a follow-up column, and add a reminder for when to call them back.

> *Left Voicemail:* In terms of campaign status, ‘left voicemail’ functions the same way as ‘not answered’—subsequent steps in a campaign cadence will go out. If another user in your Hatch workspace sees this call record, they’ll know a voicemail was left for the contact thanks to this disposition.

> *Not Interested:* When a contact tells you on the phone they’re not interested, they don’t need to receive the rest of your campaign cadence. Selecting this disposition takes the contact out of the campaign, and closes the conversation so it’s no longer on your salesboard.

> *Wrong / Invalid Number:* This disposition marks the phone number as an opt-out, so future phone communications (SMS / phone calls) won’t go out to the contact. But they will still receive email notifications, and the campaign cadence will continue as normal.

***I’ve had a look at this contact, and I don’t want to call them, on second thought***

No worries! Clicking into the contact card, the banner gives you two options besides calling:

> *Ignore* : If you want to send a text message or SMS, or want to keep this contact on your salesboard for any reason, just hit ignore. The phone call step is removed from the contact. Subsequent campaign steps will proceed as normal.

> *Close conversation* : If you want to take the contact off the salesboard and skip the phone call step, hit close conversation. The campaign will proceed as normal, and the contact will be out of your sight.<img alt="" />

If you want to remove a contact from the campaign so they won’t receive subsequent messages, you can go to the campaign directly and remove them and any other contacts.

If you want to remove a large number of contacts that appeared in the inbox at the same time, you can always go to the top of the column and hit ‘Close conversations’ to take them all off at once.

***Which campaigns can I add call steps to?***

Any campaigns you like! A couple tips to look out for:

> If you’re reaching out to a lot of contacts at once, a call step for each of them might get a little overwhelming. You can always close these conversations (and the campaign will proceed as normal), but if 150 contacts all hit a voice step at once, 150 reminders will pop up.

> Because Hatch isn’t pausing your campaign cadence while a call reminder sits on your salesboard, you might not want to make reference to a call step in the text of your subsequent steps. A text that says “we just tried calling you” will go out *whether you make that call or not*.

You might want to use the “Phone call speed to lead” campaign template as a jumping off point.

> On your salesboard, the contact card will display whatever the most recent action associated with the contact is. So if you schedule a text to go out 5 minutes after a call step, you’ll see that text (rather than a call step). You might want to have a voice step be the last step on a given day, rather than the first, to keep things clear.

***I’m managing a lot of calls—how can I find calls I might have missed on my salesboard?*<img alt="" />**

We’ve added some logic so you can know if any call steps are ‘past due,’ defined as longer than 24 hours ago. When a call step sits on your salesboard for more than 24 hours:

> The phone icon on the salesboard will turn from green to orange
> The call banner on the contact card will also turn orange and say “past due”

> You can filter for these calls on the salesboard—just hit Filter > Calls > Past due

***We have multiple users on one workspace to take calls, can we all use this feature at the same time?***

<img alt="" />

Yes! We’ve added new ‘call in progress’ features so you can see who on your workspace is talking to a contact, and which contact they’re speaking to.

***Can I get recordings or transcripts of calls once they’re done?***

Not yet! We’re still working on adding new features to calling in campaigns—get in touch if this is something you’re interested in doing in Hatch.

***How can I track dispositions associated with calls in my workspace?***

Hatch can set up webhooks to be associated with dispositions, so you have records in your CRM! Just ask your account manager.

We’re also currently working on getting dispositions added to the reporting tab within Hatch.

***My outbound calls are failing, help!***

First, double check that your Hatch number is registered with any third party lead source you’re using (if they’re using temporary numbers, like Yelp and [Angi](/integrations/lead-sources/angi-ads-integration) do), if applicable.

Second, we’d recommend registering your Hatch numbers with [Free Caller Registry](https://www.freecallerregistry.com/fcr/) and [First Orion](https://portal.firstorion.com/) to make sure all major carriers are familiar with your business.

Finally, make sure that your Hatch set-up is ready to make calls. If you’re using Google Chrome on a desktop and have a working speaker and microphone that’s properly permissioned, you should be ready to go.

If you’re still experiencing issues with calling, get in touch with the Hatch support team at any time.


# Hatch Campaign Templates
Source: https://docs.usehatchapp.com/getting-started/messaging/hatch-campaign-templates

How to view, implement, and modify Hatch campaign templates. Hatch campaign templates are recommended messaging sequences for specific use cases, to help you maximize response rates, reduce opt-out rates, and reduce spam rates. The duration, frequenc

Hatch campaign templates are recommended messaging sequences to help you maximize response rates, reduce opt-out rates, and reduce spam rates. The duration, frequency, channel, and verbiage are all based on analyzing performance data on thousands of Hatch campaigns, as well as [these messaging best practices](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/Hatch-Messaging-Best-Practices-Guide.pdf).

## Campaign template FAQs

<AccordionGroup>
  <Accordion title="Can I modify the templates?">
    Absolutely. You are free to modify the campaign templates to your liking — **just be sure to stick to [the best practices](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/Hatch-Messaging-Best-Practices-Guide.pdf)!**

    We also have compiled guides with variations of the messaging, in case you want to try something new. Those can be found here:

    * [Speed to Lead Message Ideas](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/Lead-Outreach-Templates-Hatch-eBook.pdf)
    * [Estimate Follow-Up Message Ideas](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/Sales-Follow-up-Templates-Hatch-eBook.pdf)
    * [Appointment Confirmation and Reminder Message Ideas](https://www.usehatchapp.com/hubfs/eBooks%20and%20Playbooks/23-Appointment-Confirmation-and-Reminder-Templates-Hatch.pdf)
  </Accordion>

  <Accordion title="Where can I see the Hatch campaign templates?">
    The campaign templates are available right within Hatch, but we also have made them available in [word document form](https://docs.google.com/document/d/1IWBrYRXaTwO6JZTtfgsP7tsL99qd2djrPLFRqmIpdvs/edit?usp=sharing). This is helpful for:

    * Collaboration with team members on message verbiage.
    * Being able to first browse the templates without having to implement them.
    * Anyone who doesn't have access to Hatch, who wants to understand what a campaign looks like.
  </Accordion>

  <Accordion title="How do I use a Hatch campaign template?">
    1. Log in to Hatch and navigate to your campaigns tab.

    2. Click on "Create Campaign"

       <img alt="" />

    3. You will be brought to the campaign template library, where you can choose a template or start from scratch.

       <img alt="" />

    4. Once you click "Use Template," you'll be able to modify it however you want. You can change the verbiage, add and remove messages, channels, and more.
  </Accordion>
</AccordionGroup>

## Hatch campaign templates

### Lead outreach campaign templates

Beat your competitors to leads and book more appointments.

#### 1. Hatch Chat

Engage contacts who have requested text outreach through your website.

|               |                                                                                                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text | Hi \[\[Contact First Name]], this is \[\[User First Name]] with \[\[Details Company Name]]. Thanks for texting us! Can you tell me more about what you need help with? Reply END to stop texts. |
| Day 2 - text  | 10am Thanks again for texting us the other day. I didn't hear back from you, text me back with what you need, I'm here to help.                                                                 |
| Day 3 - text  | 11:15am Hi \[\[Contact First Name]], it's \[\[Details Company Name]]. Text me back when you have some time so I can help you out!                                                               |
| Day 5 - text  | 9am Hi \[\[Contact First Name]], it's \[\[Details Company Name]]. If you ever need help with anything, text me at this number!                                                                  |

#### 2. Home show or conference

Follow up with leads from a home show or conference.

|               |                                                                                                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Launch - text | Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. Great meeting you at the home show! Are you looking to get any work done in the next couple of months? Reply END to stop texts. |
| Day 2 - text  | 10am I'm setting aside time this week to connect with people I met at the home show. Do you have time to talk?                                                                                                           |
| Day 4 - text  | 11:15am Are you looking to get any work done this year, or should I stop reaching out for now?                                                                                                                           |

#### 3. Speed to lead message template

Engage new leads instantly (from your website, Angi, and other lead sources.).

|                |                                                                                                                                                                                                                                                                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | Hi \[\[Contact First Name]], it's \[\[User First Name]] with \[\[Details Company Name]]. I got your information from the form you submitted. Text me back with what you are looking for! Reply END to stop texts.                                                                                                                                                      |
| Launch - email | Subject line: Thanks for inquiring with \[\[Details Company Name]] Hi \[\[Contact First Name]], I got your information from the form that you submitted online. I'd love to learn more about your request, or get you scheduled for an appointment. Please email me back the details! Talk soon, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 2 - text   | 10am Hi \[\[Contact First Name]]. I haven't heard back since you submitted your form. Text me back with the details.                                                                                                                                                                                                                                                   |
| Day 3 - email  | 11am Subject line: \[\[Contact First Name]] - reminder about your request! <br />\[\[Contact First Name]],<br />I haven't heard back yet regarding the request you submitted. Can you email me back the details of what you want to do? Thank you, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                               |
| Day 3 - text   | Hi \[\[Contact First Name]]. Are you still looking to get work done? Text me back with details, I would love to help.                                                                                                                                                                                                                                                  |
| Day 4 - text   | Hi \[\[Contact First Name]] - Following up again on the form you submitted - are you still interested? I would love to help!                                                                                                                                                                                                                                           |
| Day 5 - text   | Hi \[\[Contact First Name]] Reaching out one last time - would you prefer a phone call?                                                                                                                                                                                                                                                                                |

### Sales follow-up campaign templates

Seize more opportunities and close more deals.

#### 4. Canceled Appointments

Reach out to canceled prospects to reschedule their estimate.

|                    |                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Launch day - text  | 10:00am Hi \[\[Contact First Name]]! This is \[\[User First Name]] with \[\[Details Company Name]]. Your appointment with us got canceled, and I'd love to get you back on the calendar. What day works best for you? Reply END to stop texts.                                                                                                                                                         |
| Launch day - email | 10:30am Subject line: Reschedule your appointment with \[\[Details Company Name]] Hi \[\[Contact First Name]] <img alt="" />, I saw that you recently canceled an appointment with us. Is your project still on the table? If so, I'm happy to reschedule you and get the ball rolling. Let me know! \[\[User First Name]] \[\[User Last Name]]<img alt="" /> \[\[Details Company Name]]<img alt="" /> |
| Day 2 - text       | 11:00am When is a better day/time to get you on the books?                                                                                                                                                                                                                                                                                                                                             |
| Day 3 - text       | 10:00am Hi again, \[\[Contact First Name]]. Are you interested in rescheduling your appointment?                                                                                                                                                                                                                                                                                                       |
| Day 5 - text       | 2:00pm Before I close this out, reaching out one more time to see if we can reschedule your appointment. When works for you?                                                                                                                                                                                                                                                                           |

#### 5. Appointment Follow-Up - Feedback Approach

Engage prospects after their appointment/estimate.

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Launch day - text  | 10:00am Hi \[\[Contact First Name]]! This is \[\[User First Name]] with \[\[Details Company Name]]. I want to follow up on your recent appointment. How did everything go? Reply END to stop texts.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Launch day - email | 10:30am SL: \[\[Contact First Name]], how'd it go? Hi \[\[Contact First Name]], \[\[User First Name]] here from \[\[Details Company Name]]. Thanks for having us out! How did everything go during your visit? Do you have any feedback or questions I can help answer? Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                                                                                                                                                                                                                                                      |
| Day 2 - text       | Hey \[\[Contact First Name]], checking in again to see how your appointment went. Do you have any questions or feedback?                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Day 4 - text       | 10:00am Hi \[\[Contact First Name]], I just want to make sure we met your expectations. A yes or no is perfectly fine!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Day 4 - email      | 10:15am SL: \[\[Contact First Name]], \[\[Details Company Name]] Feedback Hi \[\[Contact First Name]], It's \[\[User First Name]] at \[\[Details Company Name]]. Typically, people don't get back to us for one of the below reasons: <br /><br />1. Too busy (understandable!)<br />2. Affordability<br />3. Something didn't go well at your appointment<br /><br />I'm happy to work with you to better understand what it will take to earn your business. Is one of the above affecting your response? Thank you, \[\[User First Name]] \[\[User Last Name]]<img alt="" /> \[\[Details Company Name]]<img alt="" /> |
| Day 5 - text       | 11:00am Is your project still on the table, \[\[Contact First Name]]?                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Day 7 - text       | 10:45am Hi \[\[Contact First Name]], are you still looking to get your project done soon, or should I touch base in a few months?                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### 6. Estimate Follow-Up

Follow up directly on an estimate you provided.

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 10:00am Hi \[\[Contact First Name]]! This is \[\[User First Name]] with \[\[Details Company Name]]. Do you have any questions on the estimate we sent over? Reply END to stop texts.                                                                                                                                                                                                                                                                                                                                                  |
| Launch day - email | 10:30am SL: \[\[Contact First Name]], how can I help? Hi \[\[Contact First Name]], \[\[User First Name]] here with \[\[Details Company Name]]. It was great to meet you in our recent appointment, thanks for giving us the opportunity to earn your business! Do you have any questions on the estimate we sent over?  \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                                                                                                                         |
| Day 2              | Skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Day 3 - text       | 10:30am Hey \[\[Contact First Name]], let me know if you have everything you need to make an informed decision.                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Day 4 - text       | 10:00am Hey \[\[Contact First Name]], \[\[User First Name]] again, checking in on your estimate. I'm happy to talk through any questions or concerns you have—let me know how I can help!                                                                                                                                                                                                                                                                                                                                             |
| Day 4 - email      | 10:15am SL: Your estimate with \[\[Details Company Name]] Hi \[\[Contact First Name]], It's \[\[User First Name]] again from \[\[Details Company Name]]. I haven't heard from you since we provided your estimate. Is it for any of these reasons? <br /><br />1. Price too high<br />2. Not ready<br />3. Considering someone else<br /><br />I'm happy to work with you on any of these—we want to earn your business! Thank you, \[\[User First Name]] \[\[User Last Name]]<img alt="" /> \[\[Details Company Name]]<img alt="" /> |
| Day 5 - text       | 11:00am Is your project still on the table, \[\[Contact First Name]]?                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Day 7 - text       | 10:45am Hi \[\[Contact First Name]], are you still looking to get your project done soon, or should I touch base in a few months?                                                                                                                                                                                                                                                                                                                                                                                                     |

### Customer experience campaign templates

Keep customers informed and engaged, to increase satisfaction, loyalty, and retention.

#### 7. Accounts Receivable

Reach out to customers for payments.

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 9:30am Hi \[\[Contact First Name]]. \[\[User First Name]] from \[\[Details Company]] here. We are ready to collect payment for your completed service. You can pay by calling or online through this link: \[\[Details Link]]. Thanks! Reply END to stop texts.                                                                                                                                                                                                                    |
| Launch day - email | 2:30pm Subject line: Your Payment is Due  Hi \[\[Contact First Name]] - <br />\[\[User First Name]] from \[\[Details Company]] here. We are ready to collect payment for your completed service. You can pay by calling or online through this link: \[\[Details Link]]. <br />Thanks! \[\[User First Name]]                                                                                                                                                                       |
| Day 2              | skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Day 3 - text       | 10:00am Hi again \[\[Contact First Name]], this is \[\[User First Name]] from \[\[Details Company]] here. Reminding you that your payment is due. Please either give me a call to resolve your payment, or you can pay online through this link: \[\[Details Link]].                                                                                                                                                                                                               |
| Day 4              | skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Day 5 - text       | 10:00am \[\[Contact First Name]], your payment to \[\[Details Company]] is due. Please either give me a call to make a payment, or you can pay online through this link: \[\[Details Link]].                                                                                                                                                                                                                                                                                       |
| Day 6 - email      | 10:00am Subject line: Reminder: Your Payment to \[\[Details Company]] <br />Hi \[\[Contact First Name]] - <br />We have not had luck getting in touch with you to resolve your balance for your completed service. Are there questions I can answer for you?<br />Please call or email us if there are questions or concerns. If you're able to make the payment online, here's a link to do so: \[\[Details Link]]<img alt="" /><br />Thanks! \[\[User First Name]]<img alt="" /> |
| Day 6 - text       | 10:00am Hi \[\[Contact First Name]]. We haven't heard back from you to collect payment on your completed service. When can we get this resolved? Call me when you get a chance.                                                                                                                                                                                                                                                                                                    |

#### 8. Upcoming Appointment Reminder

Remind customers about their upcoming appointment

|                    |                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 9:00am Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. Just sending a reminder about your upcoming appointment - we are excited to see you! Reply END to stop texts.                                                                                                                                                    |
| Launch day - email | 9:00am Subject line: Appointment Reminder with \[\[Details Company Name]]<br /><br />Hi \[\[Contact First Name]],<br />Just sending a quick reminder about your upcoming appointment. Please let me know if you have any questions or need to reschedule.<br />We're excited to see you soon!<br />Thanks,<br />\[\[User First Name]] \[\[Details Company Name]] |

#### 9. Appointment Confirmation\*

\*This template is not in Hatch because the appointment date/time snippet varies depending on your CRM. If you want to use it, work with your Account Manager to identify the right snippet.

Ensure clients their appointment is booked.

|                    |                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 9:00am Hi \[\[Contact First Name]], thank you for scheduling your appointment with \[\[Details Company Name]] on \[\[THIS SNIPPET VARIES BY CRM - IDENTIFY WITH YOUR ACCOUNT MANAGER]]. If you have any questions, let us know! Reply END to stop texts.                                                          |
| Launch day - email | 9:00am Thank you for scheduling your appointment with \[\[Details Company Name]] on \[\[THIS SNIPPET VARIES BY CRM - IDENTIFY WITH YOUR ACCOUNT MANAGER]]. If you have any questions, you can call, text, or email us. We look forward to seeing you!<br />Best, \[\[User First Name]] \[\[Details Company Name]] |

#### 10. Schedule installation template

Inform customers that their product has come in and that it's time to schedule the install.

|                    |                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 10:00am Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]! Great news, your products will be arriving soon, so I can go ahead and schedule the installation. What day/time works for you? Reply END to stop texts.                                                                                                                           |
| Launch day - email | 10:30am Subject line: \[\[Contact First Name]] - Your Order Is Ready Hi \[\[Contact First Name]], Your products from \[\[Details Company Name]] should be here within the next few days, so let's schedule a day and time for the installation to begin. What day works best for you? <br />Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]            |
| Day 3 - text       | 10:15am Hi again - quick reminder to contact us to get scheduled for installation. We're eager to get your job started!                                                                                                                                                                                                                                                            |
| Day 3 - email      | 10:30am Subject line: Reminder - Your Order Is Ready Hi \[\[Contact First Name]], <br />Reminding you that your installation is ready to be scheduled. Give me a call or shoot over a text/email with your availability. We look forward to starting your project!<br />Thanks, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]<img alt="" /> <img alt="" /> |
| Day 5 - text       | 11:00am Hi \[\[Contact First Name]]. Did you have a date in mind to start your installation?                                                                                                                                                                                                                                                                                       |

### Nurture campaign templates

Reach out to aged leads or past customers in your database to drum up new opportunities.

#### 11. Nurture - Canceled Appointments

Re-engage old leads who canceled their appointments.

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 1:45pm Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. We never met on the project you inquired about a while back. Are you still interested in getting work done? Reply END to stop texts.                                                                                                                                                                             |
| Launch day - email | 2:30pm Subject line: Your canceled appointment with \[\[Details Company Name]] \[\[Contact First Name]], You inquired about an appointment in the past, and we were never able to meet with you. Did you complete this project, or does it make sense for us to reconnect and schedule an appointment? Thanks, \[\[User First Name]] \[\[User Last Name]]<img alt="" /> \[\[Details Company Name]]<img alt="" /> |
| Day 3 - text       | 2:00pm Are you interested in us taking a look at the project you inquired about in the past?                                                                                                                                                                                                                                                                                                                     |
| Day 6 - text       | 2:00pm Circling back one last time! Did you want to talk to a specialist about your project?                                                                                                                                                                                                                                                                                                                     |

#### 12. Nurture - Dead - Open Estimate

Reach out to aged leads who never responded to your estimate.

|                    |                                                                                                                                                                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 1:45pm Hi \[\[Contact First Name]], it's \[\[User First Name]] with \[\[Details Company Name]]. We never got the opportunity to discuss your estimate. Are you still looking to get this project done? Reply END to stop texts.                                                               |
| Launch day - email | 2:30pm Hi \[\[Contact First Name]],<br />I hope you're doing well! We never got the opportunity to finalize your estimate. Could you let us know your current thoughts on it?<br />Looking forward to hearing from you, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 2              | skip                                                                                                                                                                                                                                                                                          |
| Day 3 - text       | 2pm Just checking in to see if you received my last message. When would be a good time for you to discuss the estimate we provided?                                                                                                                                                           |
| Day 4              | skip                                                                                                                                                                                                                                                                                          |
| Day 5              | skip                                                                                                                                                                                                                                                                                          |
| Day 6 - text       | 1:15pm I would love the opportunity to review the estimate we provided with you. Do you have time this week to discuss it?                                                                                                                                                                    |
| Day 8 - text       | 11am Hey \[\[Contact First Name]], before I close this out, is this project something you'd like to revisit in the future?                                                                                                                                                                    |

#### 13. Nurture - Dead - Never Booked Appointment

Reach out to aged leads who never booked an appointment.

|                    |                                                                                                                                                                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 1:45pm Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. We never got around to scheduling an estimate for you. Are you still looking to get work done? Reply END to stop texts.                                                                                                                                  |
| Launch day - email | 2:30pm Subject line: \[\[Contact First Name]], still looking to complete your project? Hi \[\[Contact First Name]], I hope you're doing well! We never got around to scheduling an estimate for you. Are you still looking to get work done?  Looking forward to hearing from you, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 2              | skip                                                                                                                                                                                                                                                                                                                                                     |
| Day 3 - text       | 2pm Hi \[\[Contact First Name]], are you still looking to get an estimate on your project? I'd be glad to get you scheduled.                                                                                                                                                                                                                             |
| Day 4              | skip                                                                                                                                                                                                                                                                                                                                                     |
| Day 5              | skip                                                                                                                                                                                                                                                                                                                                                     |
| Day 6 - text       | 1:15pm Hey \[\[Contact First Name]], before I close this out, is this project something you'd like to revisit in the future?                                                                                                                                                                                                                             |

#### 14. Nurture - Previous Customer

Reach out to past customers about new projects.

|                    |                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 1:45pm Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. We enjoyed working with you in the past! Do you have any new projects coming up that we can help with? Reply END to stop texts.                                                                                                                                                       |
| Launch day - email | 2:30pm Subject line: \[\[Contact First Name]], another project? \[\[Contact First Name]], I hope you've been well since we completed your last project! We enjoyed working with you, so I'm reaching out to see if you have any additional projects coming up that we can help with? Let me know! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]               |
| Day 2              | skip                                                                                                                                                                                                                                                                                                                                                                                  |
| Day 3 - text       | 2pm Circling back around to see if you have upcoming projects we can help with. I'm happy to jump on a quick call - are you free this week?                                                                                                                                                                                                                                           |
| Day 3 - email      | 2:30pm Subject line: \[\[Contact First Name]], what's next? \[\[Contact First Name]], Checking in once more to see if you have any new projects on your mind that we can help with. We value our past customers and would love to talk more about what's next. What day/time works best to catch up? Thank you, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 4              | skip                                                                                                                                                                                                                                                                                                                                                                                  |
| Day 5 - text       | 1:00pm I'm going to close this out. Please reach out in the future if you're interested in working on another project with us!                                                                                                                                                                                                                                                        |
| Day 5 - email      | 1:15pm \[\[Contact First Name]] - keep us in mind! Hi \[\[Contact First Name]], I haven't heard back from you, so I'll go ahead and close this out. Please reach out in the future when you're ready to discuss another project! Best, \[\[User First Name]]<img alt="" /> \[\[User Last Name]]<img alt="" /> \[\[Details Company Name]]                                              |

### Review & Referral Campaign Templates

Ask satisfied customers to spread the word about your business.

#### 15. Referrals

Tell satisfied customers about your referral program.

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 2:30pm Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. Thank you for being our customer! We have a referral program for referring friends and neighbors - do you know anyone we can help? Reply END to stop texts.                                                                                                                                                                                               |
| Launch - email | 2:30pm Subject line: Refer us and save! Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]. Thank you for being our customer! As referrals are a huge help to us, I wanted to let you know that we have a referral program. Do you have any friends or neighbors who could benefit from our services? Email back any questions you have! Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 3 - text   | 10am Hi \[\[Contact First Name]], \[\[User First Name]] here once more from \[\[Details Company Name]]. Do you want me to send over the details of our referral program?                                                                                                                                                                                                                                                                                  |
| Day 7 - email  | 2:30pm Subject line: Refer us and save! Hi \[\[Contact First Name]], it's \[\[User First Name]] once more from \[\[Details Company Name]]. We really appreciate your business, and wanted to let you know one last time that you get perks for referring friends and family to us! Call, email, or simply refer a customer to us to learn more! Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                               |

#### 16. Reviews

Share a link with customers to leave a review.

<Note>
  NOTE: There is not a snippet in Hatch for your review link, so you must add this manually.
</Note>

|                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch day - text  | 1:45pm Hi \[\[Contact First Name]], it's \[\[User First Name]] from \[\[Details Company Name]]! Thank you for choosing us! Would you be open to writing a quick review for us? Here is the link: \[\[YOU MUST MANUALLY INSERT LINK HERE]] Thank you in advance! Reply STOP to stop texts.                                                                                                                                                                                         |
| Launch day - email | 2:30pm Subject line: \[\[Contact First Name]], leave us a review? Hi \[\[Contact First Name]], Reviews don't just help us, they also help future customers like you to feel confident in choosing a service provider. If you had a positive experience with us, would you take a minute to leave a quick review? You can do so at this link: \[\[YOU MUST MANUALLY INSERT LINK HERE]] Thank you in advance! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 2              | skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Day 3 - text       | 11:00am Hi \[\[Contact First Name]], \[\[User First Name]] here again from \[\[Details Company Name]]! Reviews mean a lot to us! If you have 45 seconds to leave a sentence or two, we'd be so appreciative. Here is the link: \[\[YOU MUST MANUALLY INSERT LINK HERE]] Thank you in advance!                                                                                                                                                                                     |
| Day 5 - email      | 11:00am Subject line: Leave a review for \[\[Details Company Name]] Hi \[\[Contact First Name]], \[\[User First Name]] here again from \[\[Details Company Name]]! Reviews mean a lot to us! If you have 45 seconds to leave a sentence or two, we'd be so appreciative. Here is the link: \[\[YOU MUST MANUALLY INSERT LINK HERE]] Thank you in advance! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                                   |

#### 17. Feedback

Ask customers for feedback on a completed project.

|                |                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 2pm Hi \[\[Contact First Name]], this is \[\[User First Name]] with \[\[Details Company Name]]. Thanks for choosing us for your project! On a scale of 1-5, how would you rate your experience? Reply STOP to stop texts.                                                                                                                                                                                  |
| Launch - email | 3pm Subject line: \[\[Contact First Name]] - share your feedback! <br />Hi \[\[Contact First Name]], I hope everything went well with your recent project. On a scale from 1-5, how would you rate your recent experience with us? We're always looking to improve, so I'd be so appreciative of any feedback you have.<br />Thanks! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 3 - text   | 12pm Hi \[\[Contact First Name]], I hope you're satisfied with your \[\[Details Company Name]] experience! On a scale from 1-5, how would you rate your experience?                                                                                                                                                                                                                                        |
| Day 5 - text   | 12pm Hi again, \[\[Contact First Name]]. I'm always looking for feedback and ways to improve. How was your recent experience with us?                                                                                                                                                                                                                                                                      |

### Recurring service and membership campaign templates

Increase retention and loyalty with maintenance services.

#### 18. Membership Auto-Renewal Reminder

Remind membership customers that their membership will renew soon.

|                |                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 9am Hi \[\[Contact First Name]], this is \[\[User First Name]] for \[\[Details Company Name]]. This is your annual reminder that your Membership is set to renew soon. Thank you for choosing us for your project needs! Reply END to stop texts.                                                                                                                                                                          |
| Launch - email | 9:30am Subject line: Your maintenance plan is set to renew soon Hi \[\[Contact First Name]], This is \[\[User First Name]] for \[\[Details Company Name]], letting you know that your annual Maintenance Plan is set to renew soon. Thank you for choosing us for your home maintenance needs.<br />Just let us know if you have any questions!<br />\[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 3 - text   | 1pm Hi \[\[Contact First Name]], just reminding you once more that your annual Membership is set to renew soon. Thank you for choosing \[\[Details Company Name]]! Reply STOP to stop texts.                                                                                                                                                                                                                               |

#### 19. Join Membership

Promote your membership program to current customers.

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 9am Hi \[\[Contact First Name]], it's \[\[User First Name]] with \[\[Details Company Name]]. As a thank you for your loyalty, we would like to offer our Membership Program to you! Do you want me to share more details on this service? Reply END to stop texts.                                                                                                                                                                                                                                      |
| Launch - email | 9:30am Subject line: Save on costs with our Membership Program<br />Hi \[\[Contact First Name]],<br /><br />This is \[\[User First Name]] with \[\[Details Company Name]].<br />Regular maintenance can extend equipment life, prevent costly repairs, and lower your energy bills. Is joining our Membership Program something you might be interested in?<br />Email back with any questions.<br />Thank you for your business! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 3 - text   | 1pm Hi \[\[Contact First Name]], our Maintenance Program extends equipment life, prevents costly repairs, and lowers energy bills. Are you interested?                                                                                                                                                                                                                                                                                                                                                  |
| Day 5 - text   | 1pm Just checking in one last time, as our Maintenance Program is a great way to get the most out of your investment with us. Do you want someone to reach out to you about it?                                                                                                                                                                                                                                                                                                                         |
| Day 5 - email  | 1pm Subject line: Maintenance program?<br />Hi \[\[Contact First Name]], \[\[User First Name]] here again with \[\[Details Company Name]]. I wanted to ping you one last time about our Maintenance Program, as it can help lower your costs in the long run. Do you want someone to reach out to you about it? Email back with any questions. As always, thank you for your business! \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                            |

#### 20. Expiring Membership

Encourage membership customers to renew before expiration.

|                |                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 9am Hi \[\[Contact First Name]]! This is \[\[User First Name]] at \[\[Details Company Name]]. Your membership is set to expire within the month. Are you signing up for another year of service with us? Reply STOP to stop texts.                                                                                                                                                           |
| Launch - email | 9:30am Subject line: Renew your membership with \[\[Details Company Name]] Hi \[\[Contact First Name]]! This is \[\[User First Name]] at \[\[Details Company Name]]. I'm reaching out to let you know your membership is set to expire within the month. Are you signing up for another year of service with us? Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |

#### 21. Expired Membership

Encourage expired membership customers to renew.

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 9am Hi \[\[Contact First Name]]! This is \[\[User First Name]], the Membership Coordinator for \[\[Details Company Name]]. I was just reaching out to let you know your Membership has expired - please text back to renew your membership! Reply STOP to stop texts.                                                                                                                                                                 |
| Launch - email | 9:00am Subject line: \[\[Contact First Name]], your membership has expired <br />Hi \[\[Contact First Name]]! This is \[\[User First Name]], the Membership Coordinator for \[\[Details Company Name]]. I am reaching out to let you know your Membership has expired. Email, call, or text us back to renew! Let me know if you have any questions.<br />Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |

#### 22. Schedule Recurring Service

Reach out to membership customers to schedule their service.

|                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text  | 10AM Hi \[\[Contact First Name]], it's \[\[User First Name]] with \[\[Details Company Name]]. It's time for your complimentary maintenance visit as a part of your membership! Do you want to schedule that? Reply STOP to stop texts.                                                                                                                                                                                                                                                                    |
| Launch - email | 10AM Subject line: Schedule your free maintenance check with \[\[Details Company Name]] <br />Hi \[\[Contact First Name]], it's \[\[User First Name]] with \[\[Details Company Name]]. Our records show that it's time for your complimentary maintenance check, which you've already paid for as a part of your membership with us. Do you want to schedule that?<br /><br />Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]]                                                 |
| Day 2 - text   | 10am Hi \[\[Contact First Name]], let me know when you're free to schedule your complimentary maintenance visit.                                                                                                                                                                                                                                                                                                                                                                                          |
| Day 3          | skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Day 4 - text   | 10:30am Hi \[\[Contact First Name]], just checking in again. Your maintenance check has already been paid for—let me know when you're available for us to come out!                                                                                                                                                                                                                                                                                                                                       |
| Day 4 - email  | 10:30am Subject line: Your maintenance check with \[\[Details Company Name]] <br />Hi \[\[Contact First Name]], just checking in again to see if you want to schedule your maintenance check with \[\[Details Company Name]]. You've already paid for it with your membership, and maintenance prevents costly repairs and replacements down the line. Let me know when you're available and we'll get you booked!<br /><br />Best, \[\[User First Name]] \[\[User Last Name]] \[\[Details Company Name]] |
| Day 5 - text   | 11AM Hi \[\[Contact First Name]], Reaching out one last time. Your maintenance check is already paid for through your membership with us and prevents costly repairs down the line. Do you want to schedule or should I close this out?                                                                                                                                                                                                                                                                   |

### Bot campaign templates

Text-only campaigns for Hatch AI users, focused on real-time engagement.

#### 23. Day-Of Appointment Confirmations (Bot)

Single-text campaign that requests the customer to confirm their appointment for the current day.

|              |                                                                                                                                                                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Day 1 - text | Hi, this is \[\[User First Name]] with \[\[Details Company Name]]. I am confirming your appointment with us for today! Reply YES to confirm or RESCHEDULE to reschedule. To opt out of all future communication, reply END. |

#### 24. Appointment Follow-Up (Bot)

7-day text campaign specifically tailored to be attached to a Sales Follow-Up bot.

|               |                                                                                                                                                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Launch - text | Hi \[\[Contact First Name]], this is \[\[User First Name]] with \[\[Details Company Name]], following up on your appointment with us the other day. I wanted to ask you a few questions about your appointment - is that ok with you? Reply END to stop texts. |
| Day 2 - text  | 10am Hey \[\[Contact First Name]], \[\[User First Name]] again with \[\[Details Company Name]]. I didn't hear back, I wanted to follow up and ask you a few questions about your appointment, is that alright with you?                                        |
| Day 3 - text  | Hi \[\[Contact First Name]] - \[\[User First Name]] with \[\[Details Company Name]] again - following up on your appointment a few days ago, is it alright if I ask some questions about your appointment?                                                     |
| Day 5 - text  | Hi It's \[\[User First Name]] at \[\[Details Company Name]] again! Is it alright if I ask some questions to follow up on your appointment? Text me and let me know. Thanks                                                                                     |
| Day 7 - text  | Hi It's \[\[User First Name]] at \[\[Details Company Name]] for the last time! Is it okay if I ask some follow-up questions about your appointment? If not, text me and I can close this follow up out. Thank you!                                             |

### [Click here to access the templates in document form.](https://docs.google.com/document/d/1IWBrYRXaTwO6JZTtfgsP7tsL99qd2djrPLFRqmIpdvs/edit?usp=sharing)


# Hatch Delivery Status
Source: https://docs.usehatchapp.com/getting-started/messaging/hatch-delivery-status

Learn where your texts are in the delivery process and what those statuses mean

With ever-increasing [10DLC compliance laws](/getting-started/compliance/10dlc-registration-tcpa-compliance), it's important to know if you're messages are aligned with customer communication regulations. That's why we added the delivery status to your text messages.

### How does it work and what do they mean?

When you send a message in Hatch, the text bubble will show in your contacts’ conversation card history. Under that text bubble, you will see a delivery status.

<img alt="delivery-status-vid" />

Here is a list of delivery statuses:

**Sending:** the message has been created and is on its way to the mobile service provider.

<img alt="delivery-status-sending" />

**Sent:** the mobile service provider has received the message, but has not yet reached the recipient.

<img alt="delivery-status-sent" />

**Delivered:** the text has made it to the recipient.

<img alt="delivery-status-delivered" />

**Failed to send:** the mobile service provider did not accept the message.

<img alt="delivery-status-send-failed" />

**Undelivered:** the mobile service provider accepted the message but did not deliver it to the recipient.

<img alt="delivery-status-undelivered" />

A message may be undelivered or fail to send for a few reasons. Some of those reasons might be that the number you tried to send to was not a real phone number or a landline number.

<img alt="delivery-status-error" />

Most of your messages, assuming you are [10DLC compliant](/getting-started/compliance/10dlc-registration-tcpa-compliance), should go through as delivered.

<Note>
  *Note that this feature is only available for text messages, not emails, and is not yet available in the Hatch mobile app.*
</Note>


# Overview
Source: https://docs.usehatchapp.com/getting-started/messaging/overview



# Messaging

<CardGroup>
  <Card title="Calling in Campaigns" href="/getting-started/messaging/calling-in-campaigns" />

  <Card title="Hatch Campaign Templates" href="/getting-started/messaging/hatch-campaign-templates" />

  <Card title="Hatch Delivery Status" href="/getting-started/messaging/hatch-delivery-status" />

  <Card title="Working with Leads with Temporary Information in Hatch" href="/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch" />
</CardGroup>


# Working with Leads with Temporary Information in Hatch
Source: https://docs.usehatchapp.com/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch

Find out what temporary or masked information is, and how to collect a lead's real information with Hatch.

Masked or temporary information is a new privacy solution being implemented by lead aggregators, where the email address or phone number they provide you is not the contact's real information, but instead is temporary information that will expire after a period of time (for instance, 30 days from receipt).

In order to ensure you can contact these leads after the expiration date, you need to have the lead supply their permanent contact information and update it in Hatch. This article walks through how to do that.

<Warning>
  The lead aggregator is the source of truth on whether a lead's information is temporary. Some lead aggregators also have restrictions on what message formats are supported to temporary phone numbers or email addresses. Please consult your lead aggregator if you have questions on whether they are sending you temporary or masked leads or what their limitations are.
</Warning>

### Identifying a contact with temporary information in Hatch

Contacts with temporary information will have an indicator next to their name or contact information on the Sales Board, Open Card, and Contact List.

| **Sales Board** | **Open Card**  | **Contact List** |
| --------------- | -------------- | ---------------- |
| <img alt="" />  | <img alt="" /> | <img alt="" />   |

Hovering over this new icon will reveal how much longer the temporary phone number and/or email address will be valid, or if it is already expired.

| **Sales Board** | **Open Card**  | **Contact List** |
| --------------- | -------------- | ---------------- |
| <img alt="" />  | <img alt="" /> | <img alt="" />   |

### Using a Hatch AI Agent to collect contact info

Collecting a contact's permanent information before the expiration date is **crucial** to continue to generate value from that lead. This is why using a Hatch AI Agent to collect a contact's real contact information is our **recommended approach** to handling temporary contacts.

<Tip>
  If you're not currently a user of Hatch AI or unsure if you have access to this feature, please reach out to your Hatch account manager for more information!
</Tip>

To set up a bot to capture contact information, create a new bot from a template and toggle the **Ask contact information for temporary leads** setting to on.

<img alt="Screen-Shot-2024-10-15-at-3.40.39-PM-1" />

This will automatically add 2 *always included* interactions: **Obtain Email Address** and **Obtain Phone Number.** The bot will attempt to collect the phone number and email address of any contact who goes through the specified campaign if Hatch does not already have their permanent contact information.

<img alt="Screen-Shot-2024-10-15-at-3.38.30-PM-1" />

Once the bot collects the information, it will also update the contact record automatically. The bot will then finish the rest of the conversation according to the remaining interactions, requiring no manual intervention on your part to confirm and update the contact details of this lead.

<Tip>
  If you takeover a bot conversation, the bot *will*  *not* update contact information for you. If the bot had previously collected contact information before the takeover, you will need to manually update the contact.
</Tip>

### Updating contact info without a bot

If you are not using the Hatch AI Agent to collect and update your contacts with real information, you will need to do so using the Edit Contact form accessible from the Open Card. Once a contact supplies their information, edit it here to remove the "temporary" status from their phone number or email address.

<img alt="" />

### Using [Hatch webhooks](/integrations/hatch-webhooks/webhooks-basics) to update your CRM

If you are sending these contacts to your CRM, Hatch can help you keep information in sync as temporary contact information is updated to permanent information, or as a temporary contact expires. We offer 3 webhooks to help you keep your CRM up to date with accurate contact information:

1. **Contact created:** Triggered when a new contact is created in Hatch

   1. The payload of this webhook contains the status of the contact's phone and email and if temporary, the expiration date
   2. <img alt="Screenshot-2024-11-07-at-12.14.13-PM" />
2. **Contact edited:** Triggered when contact information is edited in Hatch

   1. This will help you sync the capture of real contact information in Hatch to downstream systems
3. **Contact (email or phone) expired:** Triggered when the email or phone of a contact with temporary information expires

### FAQ

<AccordionGroup>
  <Accordion title="Which lead aggregators are providing temporary contact information for leads?">
    Currently, Yelp and Angi supply temporary contact information. (If Angi's feature is not live in your account yet, it will be soon.) You can learn more here:

    <ul>
      <li>
        <a href="https://intercom.help/angi/en/articles/8549475-product-update-temporary-phone-numbers-for-homeowners">
          Angi Product Update: Temporary Phone Numbers
        </a>
      </li>
    </ul>
  </Accordion>
</AccordionGroup>


# Access data in bulk from the Export API
Source: https://docs.usehatchapp.com/getting-started/reporting/bulk-export-api

Export BI-ready Hatch data sets into your analytics stack.

## Export Hatch reporting data on demand

The Bulk Export API gives enterprise teams direct access to Hatch’s reporting datasets. Data refreshes every night with the previous day's data.

<CardGroup>
  <Card title="Bulk Export API Overview" href="/integrations/hatch-api/bulk-export/overview" />
</CardGroup>

### What’s included

* **`contact_history`** – campaign membership, attribution status, latest stage, sales data, and opt-out details for each contact.
* **`conversation_items`** – every outbound and inbound message with actor, channel, delivery status, and body text for auditing or conversational analytics.

### Access requirements

* Your Account Manager will enable API access for you.
* A **Manager** role is required to manage API keys under.
* Keys are scoped to the organization.

### Next steps

1. Review the [Bulk Export API integration guide](/integrations/hatch-api/bulk-export/overview) for endpoint details, rate limits, and schema references.
2. Request the Bulk Export API to be enabled for your organization through your Hatch Account Team.
3. Check for API Keys under **Integrations → API Keys** inside the workspace menu
4. Schedule exports at a cadence that aligns with the published limits (one every 5 minutes, 100 per day).


# Review Campaigns and SMS Performance
Source: https://docs.usehatchapp.com/getting-started/reporting/legacy-reporting

Campaign, messaging, and attribution reporting — sales, appointments, response rates, opt-outs, and first response times.

Legacy Reporting covers Hatch's campaign and messaging analytics: **campaign** performance, **text and call** activity, and **attribution** of sales and appointments back to the Hatch communication that drove them. Use it to assess performance and ROI across your outbound programs.

<Note>
  Looking for how your AI and human agents are performing on individual conversations? That lives in [Reviewing Agent Performance](/getting-started/reporting/reviewing-agent-performance) — the Dashboard, the Voice AI Scorecard, and the Conversations page.
</Note>

## The dashboards

<CardGroup>
  <Card title="Sales and Appointments" href="/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports">
    What your CRM booked and sold, and how much of it Hatch drove.
  </Card>

  <Card title="Messaging and Campaigns" href="/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports">
    Message volume, response rates, and opt-outs.
  </Card>

  <Card title="Users and Trends" href="/how-to-use-hatch/legacy-reporting/user-and-trend-reports">
    Response times, monthly trends, and the funnel.
  </Card>
</CardGroup>

Each dashboard answers a different question:

* **Sales** — the count and value of sales in your CRM, split into totals and the portion attributed to Hatch. Break down by campaign, workspace, and data source.
* **Appointments** — the same view for booked appointments.
* **Messaging** — inbound and outbound volume across SMS, email, calls, and voicemails.
* **Campaigns** — contacts launched, contacts responded, and response rate per campaign.
* **Opt-Outs** — opt-out counts and rates, and how close you are to carrier limits.
* **Users** — how quickly your team makes a first response, by user, campaign, and workspace.
* **Month-over-Month** — trends and monthly comparisons across all the core metrics.
* **Funnel** — aggregate contact journey data, from first contact to final sale.

All of these can be filtered to fit your business needs.

## Before you start

Sales and appointment figures are read from **your** CRM, so Hatch needs to know which fields to look at. If those dashboards are blank, that's almost always why — see [Attribution Settings](/how-to-use-hatch/reporting-settings/attribution-settings).

## Related Articles

* [Sales and Appointments Reports](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports): attribution criteria and CRM setup.
* [Messaging and Campaign Reports](/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports): message volume, response rate, and opt-out formulas.
* [User and Trend Reports](/how-to-use-hatch/legacy-reporting/user-and-trend-reports): first response time, month-over-month, and funnel.
* [Legacy Reporting FAQ](/how-to-use-hatch/legacy-reporting/legacy-reporting-faq): permissions, blank reports, and common questions.
* [Reviewing Agent Performance](/getting-started/reporting/reviewing-agent-performance): AI and human agent performance.


# Reviewing Agent Performance
Source: https://docs.usehatchapp.com/getting-started/reporting/reviewing-agent-performance

Where to see how your AI and human agents are performing — the Dashboard, the Voice AI Scorecard, and the Conversations page.

Hatch gives you three views onto how your agents are doing. Each answers a different question, so start at the top when you want a number and work down when you want to know why.

<CardGroup>
  <Card title="Dashboard" href="/how-to-use-hatch/dashboard/dashboard-overview">
    Who is handling what, and how much of it is landing.
  </Card>

  <Card title="Voice AI Scorecard" href="/how-to-use-hatch/dashboard/voice-ai-scorecard">
    How one Voice AI agent is performing, and why.
  </Card>

  <Card title="Conversations" href="/how-to-use-hatch/conversations/conversations">
    The individual calls and threads behind the numbers.
  </Card>
</CardGroup>

## The Dashboard

The [Dashboard](/how-to-use-hatch/dashboard/dashboard-overview) is your control center. It lists every agent in your organization across two tables — **AI Agents** and **Human Agents** — with conversation volume, success rate, and outcomes for each, updating in real time. It's also where you see which of your AI agents are currently turned on or off.

<img alt="Dashboard" />

Filter by organization, workspace, date range, or a specific agent to narrow it down.

See [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table) for what every column means.

## The Voice AI Scorecard

Click **Scorecard** on the Dashboard to open the [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard) for a single Voice AI agent. It breaks down booking performance, why bookable calls weren't booked, where calls are being transferred, and what callers are ringing about — with drill-downs to the specific calls behind each figure.

## The Conversations page

The [Conversations page](/how-to-use-hatch/conversations/conversations) is Hatch's log of every conversation on the platform. Click any conversation to get a summary and more details.

<img alt="Conversations" />

Voice calls come with additional insights — [Conversation Metrics](/how-to-use-hatch/conversations/glossary) such as **Booking Status** and **Handling** — so you can find the calls worth listening to without opening any of them. From there you can play the recording, read the transcript, and [flag anything that went wrong](/how-to-use-hatch/conversations/flagging-a-call).

## Related Articles

* [Dashboard Overview](/how-to-use-hatch/dashboard/dashboard-overview): the Dashboard in detail.
* [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table): every column in the AI Agents and Human Agents tables.
* [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard): per-agent Voice AI performance.
* [Review your new AI Agent](/getting-started/hatch-assistant/review-your-new-ai-agent): where to start with a newly launched agent.
* [Review Campaigns and SMS Performance](/getting-started/reporting/legacy-reporting): campaign, messaging, and attribution reporting.
* [Access data in bulk from the Export API](/getting-started/reporting/bulk-export-api): export reporting datasets into your own analytics stack.


# Account Settings Overview
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/account-settings-overview



To get started with Account Settings, watch this quick demo video.

<iframe title="Account Settings Overview Demo Video" />

From Account Settings, you can do the following:

[Manage Workspaces](/how-to-use-hatch/account-settings/managing-workspaces) - add, edit, or deactivate a workspace

[Manage Team](/how-to-use-hatch/account-settings/managing-users) - add, edit, or remove users from your Hatch Account

[Configure Business Hours](/how-to-use-hatch/business-hours-features/organization-level-business-hours) - set organization-level business hours

[Configure Dispositions](/how-to-use-hatch/reporting-settings/configuring-dispositions) - manage your organization's dispositions

[Attribution Settings](/how-to-use-hatch/reporting-settings/attribution-settings) - configure reporting attribution fields


# Add a Workspace
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/add-a-workspace



This article covers how to add a Workspace to your Hatch Account. If you would like to see an overview of Workspaces, see [What is a Workspace.](/how-to-use-hatch/account-settings/add-a-workspace)

<Note>
  **Note** : You must have owner or manager permission to access Account Settings.
</Note>

### Add a Workspace to your Account

1. Navigate to your **Account Settings** by clicking on your profile in Hatch. Click **Account Settings**.

![navigate.png](https://help.usehatchapp.com/hc/article_attachments/360070762792/navigate.png)

<img alt="Account settings KBI" />

When you first reach Account Settings, you can see a quick overview of your account.
*On the General Page, see your account name, owner email, and owner phone number, and other details.*

2. Click **Workspaces** in Account Settings to see all your current workspaces, or add a new workspace.

*On the Workspaces Page, you can see all your active Workspaces, and see which users are assigned to each.*

3. Click **Add Workspace.** Name your workspace, and **pick** **your area code** for your workspace’s number. We’ll assign a phone number based on what area code you choose.

*Clicking Add Workspace will present you with what information is required to set up the workspace.*

4. Pick your timezone, assign your team members, and then hit **Save**.

<Note>
  **Note** : Members can be added to workspaces at any time.
</Note>


# Add or Remove a Member from Workspace
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/add-or-remove-member-from-workspace



This article covers how to add or remove users from Workspaces.

<Note>
  **Note** : You must have owner or manager permission to access Account Settings.
</Note>

### Add or Remove Member to Workspace

1. Navigate to your **Account Settings** by clicking on your profile in Hatch. Click **Account Settings**.![navigate.png](https://help.usehatchapp.com/hc/article_attachments/360070762792/navigate.png)When you first reach Account Settings, you can see a quick overview of your account. ![Screen\_Shot\_2020-09-29\_at\_4.14.05\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070763172/Screen_Shot_2020-09-29_at_4.14.05_PM.png)

*On the General Page, see your account name, owner email, and owner phone number, and other details.*

2. Click **Workspaces** in Account Settings to see all your current workspaces.![Screen\_Shot\_2020-09-29\_at\_4.17.52\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070766712/Screen_Shot_2020-09-29_at_4.17.52_PM.png)

*On the Workspaces Page, you can see all your active Workspaces, and see which users are assigned to each.*

3. Next to the Workspace, click the three dots. Click **Edit.** Here you will see all the details for your Workspace.![Screen\_Shot\_2020-09-29\_at\_4.57.51\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070976211/Screen_Shot_2020-09-29_at_4.57.51_PM.png)

4. From Edit Workspace, scroll down until you see **Assigned Members.** You can **add or remove Members** that have already been invited to your Hatch Account.![addusertoworkspace.gif](https://help.usehatchapp.com/hc/article_attachments/360070979831/addusertoworkspace.gif)

<Note>
  **Note** : If you are trying to add a user that has not been added to Hatch yet, go to the **Teams** **Page** and invite the user through email. Once invited, you will be able to add them to Workspaces.
</Note>


# Deactivate a Workspace
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/deactivate-a-workspace

This article covers how to deactivate a Workspace to your Hatch Account.

<Note>
  **Note** : You must have owner or manager permission to access Account Settings.
</Note>

Take note, there are very rare cases that you will need to Deactivate a Workspace. **Do not** deactivate a workspace if you are trying to do the following:

* [Removing contacts from Campaign](/how-to-use-hatch/campaigns/removing-contacts-from-campaigns)
* [Remove Team Members from a Workspace](/how-to-use-hatch/account-settings/add-or-remove-member-from-workspace)
* Turn off an integration

Deactivating a Workspace will remove all contacts from Campaign, pause any integrations, and remove team members from the board. Conversations **will not** be accessible. Workspaces CAN NOT be reactivated without contacting Customer Support. Before deactivating a board, please consider all options.

### Deactivate a Workspace

1. Navigate to your **Account Settings** by clicking on your profile in Hatch. Click **Account Settings**.![navigate.png](https://help.usehatchapp.com/hc/article_attachments/360070762792/navigate.png)When you first reach Account Settings, you can see a quick overview of your account. ![Screen\_Shot\_2020-09-29\_at\_4.14.05\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070763172/Screen_Shot_2020-09-29_at_4.14.05_PM.png)

*On the General Page, see your account name, owner email, and owner phone number, and other details.*

2. Click **Workspaces** in Account Settings to see all your current workspaces.![Screen\_Shot\_2020-09-29\_at\_4.17.52\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070766712/Screen_Shot_2020-09-29_at_4.17.52_PM.png)

*On the Workspaces Page, you can see all your active Workspaces, and see which users are assigned to each.*

3. Next to the Workspace, click the three dots. From here, you can edit the workspace or click **Deactivate**. ![Screen\_Shot\_2020-09-29\_at\_4.57.51\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070976211/Screen_Shot_2020-09-29_at_4.57.51_PM.png)

*Clicking Add Workspace will present you with what information is required to set up the workspace.*

4. **Confirm** that you would like to Deactivate the Workspace.

<Note>
  **Note** : Deactivating a Workspace will remove all contacts from Campaign, pause any integrations, and remove team members from the board. Conversations **will not** be accessible. Workspaces CAN NOT be reactivated without contacting Customer Support. Before deactivating a board, please consider all options.
</Note>


# Holidays
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/holidays

Configure which holidays Hatch should respect when sending campaign messages.

<Note>
  You must have **Manager** permissions to access the Holidays page.
</Note>

### What are Holidays in Hatch?

The **Holidays** tab in Account Settings lets you control which days Hatch treats as holidays. When a campaign is set to skip holidays, any message that would go out on an observed holiday gets pushed to the next eligible day instead.

Holidays are set at the organization level, so they apply across all campaigns where **Send on holidays** is turned off.

***

### Finding Your Holiday List

Navigate to **Account Settings → Holidays** to see your full list of holidays. Each row shows the holiday name, when it falls each year (for example, "December 25" or "Fourth Thursday in November"), and whether it's currently enabled.

Any holidays your team has added manually will show a **Custom Holiday** badge next to the name. You can use the search bar at the top to filter by name if your list gets long.

***

### Federal Holidays

Hatch comes preloaded with all 11 US federal holidays for your organization. Thanksgiving and Christmas are enabled by default — the rest are included but turned off until you enable them.

<img alt="Federal holidays list in Account Settings" />

Federal holidays can't be renamed, moved to a different date, or deleted — you can only toggle them on or off.

***

### Enabling or Disabling a Holiday

Use the toggle in the **Enabled** column to turn any holiday on or off. Changes take effect right away — any pending messages that haven't sent yet will automatically be rescheduled to reflect your updated holiday list.

<Note>
  Enabling a holiday only affects campaigns where **Send on holidays** is turned off. If a campaign has **Send on holidays** turned on, it will send as normal regardless of this setting.
</Note>

***

### Adding a Custom Holiday

If you observe a holiday that isn't on the federal list, you can add your own.

1. Click **Add Custom Holiday**.
2. Enter a name.
3. Pick a date — custom holidays are tied to a specific month and day each year (for example, always December 31).
4. Toggle **Enable Holiday** on or off depending on whether you want it active right away.
5. Click **Save**.

You can edit or delete custom holidays at any time using the icons in the holiday row.

***

### How This Connects to Campaigns

On each campaign, there's a **Send on holidays** toggle in the Settings tab. Here's how it works:

* **Send on holidays is on** — the campaign sends messages on holidays as normal.
* **Send on holidays is off** — if a message would land on an observed holiday, Hatch moves it to the next available day that isn't a holiday or weekend (based on the campaign's weekend setting).

If multiple days in a row are holidays or weekends, Hatch keeps looking forward until it finds an eligible day.

For more on setting this up, see [Create a Campaign](/how-to-use-hatch/campaigns/create-a-campaign).


# Managing Users
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/managing-users

This article covers how to edit a User in Hatch.

<Note>
  **Note** : You must have **Manager Permission to access Account Settings**.
</Note>

#### Editing User Information

The user is the only one who can change their name, email, phone number, and password. Managers can add or remove users from Workspaces and change User Permissions.

### Change User Permissions

<Frame>
  <img alt="Screenshot 2026 05 29 At 13 38 46" />
</Frame>

1. Navigate to your **Settings Page** by clicking on the gear icon next to your profile icon in Hatch.
2. Click **Settings Page**. When you first reach Settings Page, you can see a quick overview of your account.

<Frame>
  <img alt="Screenshot 2026 05 29 At 13 39 06" />
</Frame>

*On the General Page, see your account name, owner email, and owner phone number, and other details.*

3. Click **Team** on the left navigation of the **Settings Page** to see all your current team members.
4. Next to the Member Name, click the three dots. Click **Edit.**
5. Here you will see the details of the team member. Scroll down to **Role**. Here you can adjust the permissions of a user.

<Note>
  **Note** : The main difference is that **Managers** can access Account Settings. **Users** can only access Workspaces they were given access to.
</Note>

### Add or Remove a User from Workspaces

1. Navigate to your **Settings Page** by clicking on the gear icon next to your profile icon in Hatch.
2. Click **Account Settings**.When you first reach Account Settings, you can see a quick overview of your account.

*On the General Page, see your account name, owner email, and owner phone number, and other details.*

3. Click **Team** in Account Settings to see all your current team members.
4. Next to the Member Name, click the three dots. Click **Edit.**
5. Here you will see the details of the team member. Scroll down to **Add/Remove Workspaces**. Here you can add or remove that member from a Workspace.

<Note>
  **Note** : If you are trying to remove a member's access to your Hatch Account, [deactivate the user](/how-to-use-hatch/account-settings/remove-user-from-hatch) instead.
</Note>


# Managing Workspaces
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/managing-workspaces



When adjusting workspaces, it is important to remember that each section of the Workspace is interconnected.

While users may spend most time on the [**Board** ](/how-to-use-hatch/board-contact-card/salesboard-basics)responding to messages, [**Campaigns**](/how-to-use-hatch/campaigns/campaign-basics) and [**Contacts**](/how-to-use-hatch/contacts/contacts-basics) allow you to target contacts and send them messages.

Depending on what you are trying to adjust for your workspace, you may need to go to **Account Settings** or **Workspace Settings**.

### The following can be adjusted from **Account Settings** :

<Note>
  **Note**: To adjust Workspaces, you must have **Manager Permissions** within Hatch.
</Note>

* [Add a New Workspace](/how-to-use-hatch/account-settings/add-a-workspace)
* [Deactivate Workspace](/how-to-use-hatch/account-settings/deactivate-a-workspace)
* Edit Workspace
* [Add or Remove a User from Workspace](/how-to-use-hatch/account-settings/add-or-remove-member-from-workspace)
* [Edit User](/how-to-use-hatch/account-settings/managing-users)
* [Adjust User Permissions](/how-to-use-hatch/account-settings/managing-users)

### The following can also be adjusted from **Workspace Settings** :

* Workspace Name
* Workspace Company Name
* Workspace Email Address
* Workspace Phone Number
* Hatch Chat Image
* Workspace Initials
* Workspace Timezone
* [Workspace Call Forwarding Number](/how-to-use-hatch/workspace-settings/how-to-setup-call-forwarding-for-your-workspace)
* Workspace Voicemail Greeting


# Remove User from Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/account-settings/remove-user-from-hatch



This article covers how to remove a user from Hatch.

<Note>
  **Note** : You must have owner or manager permission to access Account Settings.
</Note>

### Remove User from Hatch

<img alt="Account settings KBI" />

1. Navigate to your **Account Settings** by clicking on your profile in Hatch.
2. Click **Account Settings**.![navigate.png](https://help.usehatchapp.com/hc/article_attachments/360070762792/navigate.png)When you first reach Account Settings, you can see a quick overview of your account. ![Screen\_Shot\_2020-09-29\_at\_4.14.05\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070763172/Screen_Shot_2020-09-29_at_4.14.05_PM.png)

*On the General Page, see your account name, owner email, and owner phone number, and other details.*

3. Click **Team** in Account Settings to see all your current team members.![Screen\_Shot\_2020-09-29\_at\_4.17.52\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070766712/Screen_Shot_2020-09-29_at_4.17.52_PM.png)
4. Next to the Member Name, click the three dots. Click **Deactivate.![Screen\_Shot\_2020-09-29\_at\_5.31.37\_PM.png](https://help.usehatchapp.com/hc/article_attachments/360070795912/Screen_Shot_2020-09-29_at_5.31.37_PM.png)**
5. Confirm that you would like to deactivate the team member. Deactivating a member will remove their access from Hatch.![deactivateuser.png](https://help.usehatchapp.com/hc/article_attachments/360070796652/deactivateuser.png)

<Note>
  **Note** : If you are trying to remove a member from a Workspace instead, click **Edit** and adjust which Workspaces the user has access to.
</Note>


# Audience Builder: Field Picker
Source: https://docs.usehatchapp.com/how-to-use-hatch/audience-builder-v2/audience-builder-v2-field-picker



Once you've selected the data source for the contacts in your Audience, the next way to narrow down your criteria is to look for information in a **field**. A **field** is an attribute that contains data about a specific contact.

The fields available here are determined by your Manage Data settings. If you're not seeing a field you expect, it may need to be enabled — see [Audience Builder: Manage Data](/how-to-use-hatch/audience-builder-v2/audience-builder-v2-manage-data) for details.

For example, if I want to know the outcome of a contact's appointment, my CRM likely has a **field** called something like *Appointment Result* ,  *Disposition* , or  *Status*.

#### Parent Objects

When we receive data from a CRM, sometimes that data includes an **object** that contains fields or even **sub-objects** which contain fields. The Audience Builder allows you to navigate through these to find the data you are looking for.

A good way to think about it is how on your computer you have folders, and sometimes those folders contain other folders that you need to click into to get to a specific file.

For the example below, I've used the improveit360 CRM. When you select improveit360 as a source and open the Field Picker, you can see that all fields are contained within 1 of 3 parent objects: Appointment, Project, and Prospect.

If you know that the field you are looking for is something pertaining to the appointment/demo that took place, you could find that information contained in the Appointment object, for example.

#### <img alt="" />

If you see an arrow on the right of an item in the menu, that means that selection contains more within it.

See below how in the Appointment object, there is a sub-object called Attributes and there is also a list of fields.

<img alt="" />

If I click into the Attributes sub-object, you can see a list of fields contained in the Attributes sub-object, which is contained in the Appointment parent object.<img alt="" />

The Audience Builder will show you the path you've take at the top of the Field Picker (shown above).


# Audience Builder: Glossary and FAQ
Source: https://docs.usehatchapp.com/how-to-use-hatch/audience-builder-v2/audience-builder-v2-glossary-and-faq



The new version of the Audience Builder allows you to create even more specific lists of contacts by being able to query both the current state of data and past states of data for contacts.

Below is a glossary of all the operators as well as examples of what kinds of statements they are used for.

### Operator Glossary

There are a couple of things to consider when using the Audience Builder: The type of data that a field contains and whether you want to look at the current state of data for a contact or all historical data for a contact.

Each operator has a version which queries the current Hatch opportunity only, or queries all opportunities (example below). The operators you see in the list will depend on the data type of the selected field; the 4 data types are "text", "date", "number", "true/false" (shown in that order below).

<Frame>
  <img alt="Text field operators" />

  <img alt="Date field operators" />

  <img alt="Number field operators" />

  <img alt="True/False field operators" />
</Frame>

#### Text Fields

* is
  * Definition: Show contacts that have, on their most recent Hatch opportunity, the exact queried value in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `demo no sale` would still show contacts with `Demo No Sale`
* is not
  * Definition: Show contacts that, on their most recent Hatch opportunity, do not have the exact queried value in the queried field
  * Notes:
    * This is not case-sensitive, so looking for `demo no sale` would still filter out contacts with `Demo No Sale`
* is any of
  * Definition: Show contacts that, on their most recent Hatch opportunity, have any of the exact queried values in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `cat`, `dog` would still show contacts with `Cat` or `Dog`
* is not any of
  * Definition: Show contacts that, on their most recent Hatch opportunity, do not have any of the exact queried values in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `cat`, `dog` would still filter out contacts with `Cat` or `Dog`
* contains
  * Definition: Show contacts that, on their most recent Hatch opportunity, have what is typed anywhere in the queried value for the queried field
  * Example: `Appointment Result` | `contains` | `Not` would return contacts that have any of the following in the field `Appointment Result`:
    * `Not Demoed`
    * `Not Qualified`
    * `not run`
    * `not scheduled`
  * Notes:
    * This is not case-sensitive, so looking for `demo no` would still show contacts with `Demo No Sale`
* does not contain
  * Definition: Show contacts that, on their most recent Hatch opportunity, do not have what is typed anywhere in the queried value for the queried field
  * Example: `Appointment Result` | `does not contain` | `Not` would filter out contacts that have any of the following in the field `Appointment Result`:
    * `Not Demoed`
    * `Not Qualified`
    * `not run`
    * `not scheduled`
  * Notes:
    * This is not case-sensitive, so looking for `demo no` would still filter out contacts with `Demo No Sale`
* is empty
  * Definition: Show contacts that, on their most recent Hatch opportunity, do not have a value for this field
* is not empty
  * Definition: Show contacts that, on their most recent Hatch opportunity, have *any* value for this field
* was ever
  * Definition: Show contacts that have, on any of their Hatch opportunities, the exact queried value in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `demo no sale` would still show contacts with `Demo No Sale`
* was never
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have the exact queried value in the queried field
  * Notes:
    * This is not case-sensitive, so looking for `demo no sale` would still filter out contacts with `Demo No Sale`
* was ever any of
  * Definition: Show contacts that, on any of their Hatch opportunities, have any of the exact queried values in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `cat`, `dog` would still show contacts with `Cat` or `Dog`
* was never any of
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have any of the exact queried values in the queried field, nothing more and nothing less
  * Notes:
    * This is not case-sensitive, so looking for `cat`, `dog` would still filter out contacts with `Cat` or `Dog`
* ever contained
  * Definition: Show contacts that, on any of their Hatch opportunities, have what is typed anywhere in the queried value for the queried field
  * Example: `Appointment Result` | `ever contained` | `Not` would return contacts that ever had any of the following in the field `Appointment Result`:
    * `Not Demoed`
    * `Not Qualified`
    * `not run`
    * `not scheduled`
  * Notes:
    * This is not case-sensitive, so looking for `demo no` would still show contacts with `Demo No Sale`
* never contained
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have what is typed anywhere in the queried value for the queried field
  * Example: `Appointment Result` | `never contained` | `Not` would filter out contacts that ever had any of the following in the field `Appointment Result`:
    * `Not Demoed`
    * `Not Qualified`
    * `not run`
    * `not scheduled`
  * Notes:
    * This is not case-sensitive, so looking for `demo no` would still filter out contacts with `Demo No Sale`
* was ever empty
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have a value for this field
* was never empty
  * Definition: Show contacts that, on any of their Hatch opportunities, have *any* value for this field

### Number Fields

Using a number field will only provide a text input as the value.

* is
  * Definition: Show contacts that have, on their most recent Hatch opportunity, the exact number input in the queried field.

* is not
  * Definition: Show contacts that do *not* have the exact number input in the queried field on their most recent Hatch opportunity

* is greater than
  * Definition: Show contacts that have, on their most recent Hatch opportunity, a number in the queried field that is higher than the number input.

* is less than
  * Definition: Show contacts that have, on their most recent Hatch opportunity, a number in the queried field that is lower than the number input.

* is greater than or equal to
  * Definition: Show contacts that have, on their most recent Hatch opportunity, a number in the queried field that is higher than the number input or equal to the number input.

* is less than or equal to
  * Definition: Show contacts that have, on their most recent Hatch opportunity, a number in the queried field that is lower than the number input or equal to the number input.

* is empty
  * Definition: Show contacts that, on their most recent Hatch opportunity, do not have a value for this field

* is not empty
  * Definition: Show contacts that, on their most recent Hatch opportunity, have *any* value for this field

* was ever
  * Definition: Show contacts that have, on any of their Hatch opportunities, the exact number input in the queried field.

* was never
  * Definition: Show contacts that do *not* have the exact number input in the queried field on any of their Hatch opportunities.

* was greater than
  * Definition: Show contacts that have, on any of their Hatch opportunities, a number in the queried field that is higher than the number input.

* was less than
  * Definition: Show contacts that have, on any of their Hatch opportunities, a number in the queried field that is lower than the number input.

* was greater than or equal to
  * Definition: Show contacts that have, on any of their Hatch opportunities, a number in the queried field that is higher than the number input or equal to the number input.

* was less than or equal to
  * Definition: Show contacts that have, on any of their Hatch opportunities, a number in the queried field that is lower than the number input or equal to the number input.

* was ever empty
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have a value for this field

* was never empty
  * Definition: Show contacts that, on any of their Hatch opportunities, have *any* value for this field

### True/False

True/False fields do provide a value input because the query ends with the operators listed below.

* is true
  * Definition: Show contacts that have, on their most recent Hatch opportunity, a value of `true` for the queried field.

* is false

  * Definition: Show contacts that have, on their most recent Hatch opportunity, a value of `false` for the queried field.

* was ever true
  * Definition: Show contacts that have, on any of their Hatch opportunities, a value of `true` for the queried field.

* was ever false
  * Definition: Show contacts that have, on any of their Hatch opportunities, a value of `false` for the queried field.

### Date Fields

* is
  * today
    * Definition: Show contacts that, on their most recent opportunity, have the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, have the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have the selected time frame in the queried field.

* is not
  * today
    * Definition: Show contacts that, on their most recent opportunity, do not have the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, do not have the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, do not have the selected time frame in the queried field.

* is after
  * today
    * Definition: Show contacts that, on their most recent opportunity, have a date after the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, have a date after the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have a date after the selected time frame in the queried field.

* is before
  * today
    * Definition: Show contacts that, on their most recent opportunity, have a date before the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, have a date before the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have a date before the selected time frame in the queried field.

* is on or after
  * today
    * Definition: Show contacts that, on their most recent opportunity, have a date on the current calendar date or after the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, have a date on the selected calendar date or after the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have a date on the selected time frame or after the selected time frame in the queried field.

* is on or before
  * today
    * Definition: Show contacts that, on their most recent opportunity, have a date on the current calendar date or before the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on their most recent opportunity, have a date on the selected calendar date or before the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have a date on the selected time frame or before the selected time frame in the queried field.

* is between
  * custom range
    * Definition: Show contacts that, on their most recent opportunity, have a date between the selected calendar dates in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2-5 days ago` or `3-6 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, have a date between the selected time frames in the queried field.
  * now and
    * Definition: Show contacts that, on their most recent opportunity, have a date between right now the selected time frame in the queried field.

* is not between
  * custom range
    * Definition: Show contacts that, on their most recent opportunity, do not have a date between the selected calendar dates in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2-5 days ago` or `3-6 months from now` for example))
    * Definition: Show contacts that, on their most recent opportunity, do not have a date between the selected time frames in the queried field.
  * now and
    * Definition: Show contacts that, on their most recent opportunity, do not have a date between right now the selected time frame in the queried field.

* is blank
  * Definition: Show contacts that, on their most recent opportunity, do not have a date in the queried field.

* is not blank
  * Definition: Show contacts that, on their most recent opportunity, have any date in the queried field.

* was ever
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, have the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, have the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have the selected time frame in the queried field.

* was never
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have the selected time frame in the queried field.

* was ever after
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date after the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date after the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date after the selected time frame in the queried field.

* was ever before
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date before the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date before the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date before the selected time frame in the queried field.

* was ever on or after
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the current calendar date or after the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the selected calendar date or after the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the selected time frame or after the selected time frame in the queried field.

* was ever on or before
  * today
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the current calendar date or before the current calendar date in the queried field.
  * custom date
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the selected calendar date or before the selected calendar date in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2 days ago` or `3 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date on the selected time frame or before the selected time frame in the queried field.

* was ever between
  * custom range
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date between the selected calendar dates in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2-5 days ago` or `3-6 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date between the selected time frames in the queried field.
  * now and
    * Definition: Show contacts that, on any of their Hatch opportunities, have a date between right now the selected time frame in the queried field.

* was never between
  * custom range
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have a date between the selected calendar dates in the queried field.
  * range (This option allows you to choose a specific amount of days/months/years in the past or in the future (`2-5 days ago` or `3-6 months from now` for example))
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have a date between the selected time frames in the queried field.
  * now and
    * Definition: Show contacts that, on any of their Hatch opportunities, do not have a date between right now the selected time frame in the queried field.

* was ever blank
  * Definition: Show contacts that, on any of their Hatch opportunities, do not have a date in the queried field.

* was never blank
  * Definition: Show contacts that, on any of their Hatch opportunities, have any date in the queried field.

### Campaign and Communication-Specific Fields

`Campaign` | `Date`

* occurred
  * Definition: Show contacts that have ever been in the specified campaign
* never occurred
  * Definition: Show contacts that have never been in the specified campaign

`Communication` | `Date`

* occurred
  * Definition: Show contacts that have ever had the specified communication
* never occurred
  * Definition: Show contacts that have never had the specified communication

### Logic Notes

* Using operators that contain the word `ever` means that the query will look through all Hatch opportunities to find the information.
  * If you search for multiple fields using `ever` operators, the Audience Builder will only return contacts that fit all of the criteria *on the same opportunity*.

* Using operators that contain the word `never` will look through all opportunities and make sure all of the contact’s opportunities do not contain or equal the queried value.
  * For example, if you included `Shirt Color` `was never` `Blue` to your search, it will filter out contacts that have *any* opportunity where the `Shirt Color` is `Blue`, even if the contact fits all the rest of the criteria

* The Audience Builder will only show data from the current opportunity in the contacts table, but you will have the ability to click into any contact result to see all the opportunities of that contact<img alt="" />

  * To the right is an example of a contact with three opportunities. In this picture, the 2nd most recent opportunity is expanded.

* Queries that use a `contain` operator will only provide a text input for the value, not an autocomplete of options, since the user is looking for a partial match

* The Audience Builder is built so that when using *only past operators* with the `and` connector, it will retrieve contacts where all the criteria matched on a *single* opportunity, not mixing-and-matching data from different opportunities

* We only allow 2 levels of nesting. Notice in the screenshot that once you have added a nest within a nest, you can no longer add more nesting<img alt="" />

* When querying dates, all ranges are *inclusive* , meaning that if you query:

  * 06/17/2024 - 06/24/2024
    * You will get all dates with a calendar date **on or between** June 17, 2024 12:00am and June 24, 2024 11:59pm
  * 2 - 5 days ago
    * You will get anything with a calendar date that was 2, 3, 4, or 5 days ago

### FAQ

<AccordionGroup>
  <Accordion title="What is the difference between querying the most recent opportunity vs all opportunities?">
    The <b>Most recent opportunity</b> is the set of data related to a contact that came into Hatch most recently.<br /><br />
    Anything that is <i>not</i> the <b>Most recent opportunity</b> is considered an <b>Older opportunity</b>.<br /><br />
    When you use operators like <code>is</code> vs <code>was ever</code>, what you are saying is:

    <ul>
      <li><b><code>is</code></b>: The query must be true specifically on the <b>Most recent opportunity</b></li>
      <li><b><code>was ever</code></b>: The query can be true on any of the contact’s opportunities, whether or not the opportunity is the most recent set of data for a contact.</li>
    </ul>

    <img alt="most recent vs all opportunities" />
  </Accordion>

  <Accordion title="What is a “Nested Row” and what is it used for?">
    A <i>Nested Row</i> is a way to put a query within a query to use both the <code>and</code> connector and the <code>or</code> connector.<br /><br />

    <ul>
      <li>
        For example:<br />
        Using only <code>and</code> connectors means “for a contact to show, it must fit <i>every one of</i> the rows in my Audience”!

        <br />

        <img alt="and connector" />

        <br />

        In this example, contacts will only show if the Sport is Golf <b>AND</b> the City is New Orleans.
      </li>

      <br />

      <li>
        Using only <code>or</code> connectors means “for a contact to show, it must fit <i>any one of</i> the rows in my Audience”!

        <br />

        <img alt="or connector" />
      </li>

      <br />

      <li>
        Nested rows are a way to say “I want contacts that fit <i>this</i> row <code>and</code> <i>either one of these</i> rows!"

        <br />

        <img alt="nested rows" />
      </li>
    </ul>
  </Accordion>

  <Accordion title="What is the 'Date' field on the Campaign History rows?">
    When you use the <i>Date</i> field for campaign history, you are querying the date that the campaign started.<br /><br />
    For example, if your row says:

    <ul>
      <li><code>Sales Follow-Up</code> | <code>Date</code> | <code>was ever between</code> | <code>now and</code> | <code>5</code> | <code>days</code> | <code>ago</code></li>
    </ul>

    what you are saying is:

    <ul>
      <li>Show me contacts that started the <i>Sales Follow-Up</i> campaign between right now and 5 calendar days ago</li>
    </ul>
  </Accordion>
</AccordionGroup>


# Audience Builder: Manage Data
Source: https://docs.usehatchapp.com/how-to-use-hatch/audience-builder-v2/audience-builder-v2-manage-data



The **Manage Data** modal lets you control which fields from your CRM integration are available for use in the Audience Builder and Removal Rules. Smart defaults are pre-selected for you, so you likely won't need to make any changes — but if your team uses custom or less common fields, you can add them here.

## Where to find it

Open the Audience Builder and click the **Manage Data** button in the top right corner.

<img alt="Manage Data button in the Audience Builder" />

## How it works

When you open the modal, you'll see your connected integration sources listed on the left. Selecting a source shows you all available fields organized by object type — for example, if you're on ServiceTitan, you'll see fields grouped under Jobs, Calls, Estimates, Memberships, and so on.

Each field has a toggle that controls whether it's available as a filter in the Audience Builder. Fields that are toggled on will appear in the field picker when building an audience. Fields that are toggled off won't.

<img alt="The Manage Data modal showing fields organized by object type" />

To update your fields:

1. Select a source from the left panel.
2. Browse or search for the field you want to add or remove.
3. Toggle the field on or off.
4. Click **Save**.

After saving, a background process runs to make newly added fields available. **The field may take a few minutes to appear in the Audience Builder** — you'll see an in-progress indicator in the modal while this is happening.

## Things to know

**Smart defaults are pre-populated.** When you first connect an integration, Hatch automatically enables the most commonly used fields. You likely won't need to adjust anything.

**There's a limit of \~100 fields per integration.** If you're approaching the limit, prioritize the fields your team actually uses in audiences and disable any you no longer need.

**Fields in use can't be disabled.** If a field is currently referenced in one or more of your audiences, its toggle will be grayed out. To disable it, you'd first need to remove that field from any audiences using it.

**Newly added fields take a few minutes to become available.** After toggling a field on and saving, the field goes through a short processing step before it appears in the Audience Builder field picker. The Manage Data modal will show an in-progress indicator until it's ready.

**Array fields show a limited number of items.** For fields that contain lists (e.g., a list of tags), Hatch makes the first \~10 items available by default. This covers the vast majority of use cases, but you can enable additional items in the modal if needed.

**Object sort order is configurable per object type.** By default, records are sorted by last updated date. If you need a different sort order (e.g., sorting Calls by date received instead), you can configure this per object type in the modal.

**You can filter to active fields only.** Toggle **Active only** in the modal to see just your currently enabled fields instead of scrolling the full list — handy once you have a lot of fields configured. The modal footer also shows a live count of active fields.

## FAQ

**Why isn't the field I just added showing up in the Audience Builder?**

Newly enabled fields go through a short processing step after you save. This typically takes a few minutes. Check the Manage Data modal — if you see an in-progress indicator next to the field, it's still processing. Refresh the Audience Builder once it's complete.

**Why is a field's toggle grayed out and I can't turn it off?**

That field is currently being used as a filter in one or more of your audiences. To disable it, open those audiences and remove the condition using that field first, then come back to Manage Data.

**I've hit the field limit. What do I do?**

Review which fields you currently have enabled and disable any that your team isn't actively using in audiences. If you have a strong need for more fields, reach out to your Account Manager.

**Will changing my field selections affect existing audiences?**

Removing a field that's actively used in an audience will be blocked — the toggle will be grayed out. Any fields you add or remove only affect new audience conditions going forward.

**Does Manage Data apply to all my integrations?**

No — the Manage Data modal only applies to native integrations installed via the Hatch App Marketplace. For all other data sources (such as the Hatch API, Zapier, webhooks, or CSV imports), fields appear automatically in the Audience Builder without any configuration needed.

**How do I know how many fields I have enabled, or if I'm close to the 100-field limit?**

The Manage Data modal footer shows an active fields count that updates as you toggle fields on or off. Compare that number to the \~100 field limit for that source to see how much room you have left.


# Audience Builder: Operators
Source: https://docs.usehatchapp.com/how-to-use-hatch/audience-builder-v2/audience-builder-v2-operators



Operators are a way to relate the chosen field to the value you’re going to use.

There are 4 types of fields, and each type has its own set of operators. The 4 types and their operators are:

### **Text** (most fields will be this type)

<img alt="" />

**Current Operators**

**For the difference between Current Operators and Past Operators, please see the section below.**

* **is** and **is not** look for a single value that matches the exact input.
* **is any of** and **is not any of** allow you to input a list of values to find an exact match for the input.
* **contains** and **does not contain** look for partial value matches.
* **is empty** and **is not empty** simply look for contacts that either have nothing or anything in that field, respectively.

  * **Examples (using Field | Operator | Value):**
    * Appointment Result | is | Demo No Sale
      This would only return contacts that have exactly "Demo No Sale" in the field "Appointment Result"
    * Project Type | contains | do
      If you had "doors" and "windows" as project types, contacts with either of those would return because both values contain "do" within them
    * Sales Rep Assigned | is empty
      This would return any contacts that have the field "Sales Rep Assigned" blank

### **Date**

<img alt="" />

All of the options here are timeline related, and you will receive an additional **Date Operator** to further define your reference range (shown below):

* **is** and **is not** allow you to query based on one specific time. The options are  *today* ,  *custom date* ,  *range* (such as  *2 days ago*)
* **is after** allows you to find contacts with a date in the selected field that comes after *today* ,  *custom date* , or  *range* (such as  *after 2 days from now*)
* **is before** allows you to find contacts with a date in the selected field that comes before *today* ,  *custom date* , or  *range* (such as  *before 2 days ago*)
* **is between** allows you to find contacts with a date in the selected field that is between *2 specific dates* ,  *2 points in a time range* (such as  *between 2-5 days ago*), or between *now* *and some point in the past of future* (such as  *between now and 5 days ago*)
* **is not between** allows you to find contacts with a date in the selected field that is  ***not*** between *2 specific dates* ,  *2 points in a time range* (such as *is not* *between 2-5 days ago*), or *is not* between *now* *and some point in the past of future* (such as *is not* *between now and 5 days ago*)
* **is blank \_\_** allows you to find contacts that do not have  *any* date in the selected field
* **is not blank** allows you to find contacts that have  *any* date in the selected field, regardless if it is in the past, present, or future

### **Number**

<img alt="" />

These operators are typical amount/count comparisons

* Examples (using Field | Operator | Value):
  * Quote Amount | is greater than | 10000
  * Number of Windows | is less than or equal to | 6
  * Contract Total | is | 5000

### **True/False**

<img alt="" />

* Examples (using Field | Operator):
  * Appointment Set | is true
  * Contract Signed | is false

### Current Opportunities vs. Past Opportunities

An **Opportunity** in Hatch is an individual set of data that belongs to a contact. For example, if a contact comes into Hatch from a Lead Source, and later that same contact comes into hatch from your CRM; those sets of data both belong to the same contact, but they are separate sets of data at a given time.

Another example is if a contact had a project in 2021 and has a different project in 2024. In your CRM, it's likely that each record has its own set of data (and usually something like a unique Project ID or Job ID) because those are distinct sets of data that belong to the same contact.

Hatch considers the **Current Opportunity** the set of data that was either created or updated  *most recently*.

For this reason, most of the Audiences you create will rely on operators in the **Current Opportunity** section.

There are times, however, when you may want to reference older records. This is where the **Past Opportunities** operators come in.

Let's say you want to target a list of contacts that currently have an appointment result of  *Demo No Sale* , but you want to filter out contacts that  *ever* had a Sold job in the past.

Below is an example of the kind of Audience you might need:

<img alt="" />In this instance, the contacts that will show will be any contact where **both** of the following are true:

* The most recent set of data has  *Demoed, Not Sold* as the Appointment Result
* No other opportunities in the past have  *Sold* as the Appointment Result

The only difference between the **Current Opportunity** and **Past Opportunity** operators is whether the logic should apply just to the most recent set of data, or if it should apply to all sets of data regardless of how old they are.

**Note on Past Opportunity logic**

* When using past operators, a contact will only show if all of the criteria is true on any  *single* opportunity for that contact

In the example below, my Audience looks for a contact where both of the following are true  *on the same Hatch opportunity* :

* Appointment | Result 1 **was ever**  *Demoed, Not Sold*
* Appointment | Components **was ever**  *Windows*

<img alt="" />

The only contact that would show from this search is Kevin Fisher, based on Kevin's  *Past Opportunity 1*.

Even though at some point all contacts fit the different criteria for different opportunities, only Kevin has an opportunity on which both are true in the same set of data.

For a comprehensive list of all operator definitions and examples, please see the [Audience Builder: Glossary and FAQ](/how-to-use-hatch/audience-builder-v2/audience-builder-v2-glossary-and-faq)


# Audience Builder: Source Picker
Source: https://docs.usehatchapp.com/how-to-use-hatch/audience-builder-v2/audience-builder-v2-source-picker

This article will outline what the Source Picker is and what it is used for

When building an Audience, we start with the broadest category of information and gradually get more specific. This begins with the broadest category of the data within Hatch, the Source.

### Example of the Source Picker

When you click the Source Picker drop-down, you will see a list of all data sources that at least one contact has in your Hatch account.

**Hatch Contact** will always exist and will allow you to search for things like Name, Phone, Email, and other data that is associated to a Hatch Contact.

<img alt="" />

### Common Contact Sources

#### CRM Integration

<img alt="" />

If you are looking for contacts from your CRM, you will see the source name listed *.*

If you have a CRM that is handled by the Data Team, the source will be  *CSV Import*.

#### Lead Source

<img alt="" />

#### CSV Import

<img alt="" />

#### Hatch Contact

<img alt="" />

While all other sources listed are  *external* sources of data, the **Hatch Contact** selection allows you to query core attributes of a Hatch Contact (screenshot below).

<img alt="" />

Once you've selected a source, the next option that will become available is to select from a list of fields that exist for the chosen source. This will be covered in the Audience Builder: Field Picker article.


# Add Contact to Campaign from the Contact Card
Source: https://docs.usehatchapp.com/how-to-use-hatch/board-contact-card/add-contact-to-campaign-from-the-contact-card

Adding a contact to campaign directly from the contact's conversation is a great way to keep your salesboard organized while still making sure contacts receive messages.

### Step by Step

<img alt="" />

1. Navigate to a **contact card** on your Board.
2. In the top-right corner, click the the megaphone icon to **launch a campaign**.
3. Pick your campaign, and hit **Launch**. The contact will be launched into the campaign, and be moved off your board for safe keeping (find them on the Contacts page at any time).
4. When they respond to your campaign message, they will pop back up on your board and you can continue the conversation.

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is this the only way to launch a contact into a campaign?">
    No! Typically, customers use a [Workflow](/how-to-use-hatch/workflows/workflows-overview) to get campaign messages to a contact. You can also manually launch contacts into a campaign from the Contacts page.
  </Accordion>

  <Accordion title="But I don't want to send two campaigns to the same contact! What if they get thrown into a workflow?">
    Contacts can only ever be in <b>one campaign at a time</b>. If you launch them into a campaign from open contact card, they can not be placed into another campaign until the campaign ends or the contact is taken out of the campaign.
  </Accordion>

  <Accordion title="When should I use this?">
    Launching a contact directly from the conversation is an easy way to put the contact into a multi-touch campaign when you are ready to do so. If you only want to send one message to a contact, you should [schedule the message](/how-to-use-hatch/board-contact-card/contact-card-basics) directly from the contact card for a future time.
  </Accordion>
</AccordionGroup>


# Contact Card Basics
Source: https://docs.usehatchapp.com/how-to-use-hatch/board-contact-card/contact-card-basics



Clicking a contact's name on your salesboard takes you to the contact card. The contact card contains your conversation history with a given contact, as well as a number of actions you can take for a specific contact.

At the top right of the contact card, there are several icons for actions you can take on a contact directly from the open card.

* *Call contact:* Start a telephone call to this contact directly in your browser, using your Hatch workspace number to the contact's phone number (if they have one)
* *Mark unread:* Mark this contact as 'unread'. Just as an incoming message would mark a contact as a new unread, pressing this icon will add a border to the contact card on the salesboard, as a reminder to follow-up on this contact
* *Set reminder:* Set a reminder to follow-up with this contact. A record will be created in the conversation feed that a reminder was set, and the reminder icon on the salesboard will turn red once the reminder date / time is reached
* *Sold history:* View and record sales for this contact, complete with dollar amount
* *Launch campaign:* Manually launch this contact into any existing campaign
* *Move contact:* Move a contact card into a different column on your salesboard, or, if your workspace shares contacts with another workspace, to a column on a different salesboard
* *Close conversation:* Closing a conversation just takes it off your salesboard. A contact can still meet the criteria for a workflow, or be messaged directly, after their conversation has been closed—just find the contact on the [Contacts Page](/how-to-use-hatch/contacts/contacts-page)
* *Open in CRM:* If the contact has data from an integrated CRM, open their record directly in the CRM
* *Assign / assignee:* Select a user from your workspace to handle this conversation. An unassigned contact is assigned to a contact upon sending a message to that contact. Users can turn on notifications when they are assigned a conversation, either by a human or bot, in their Profile Settings.

<img alt="" />

In the right-hand sidebar, there are several sections with information about this contact.

* *Favorites:* To quickly show the information that matters most without having to dive into the details of an opportunity, you can make a certain field a favorite. A contact's phone and email are always favorites, you can add additional fields as favorites from a contact's opportunity details.
* *Notes:* Users can add a note to a contact to provide context / guidance for other users within a workspace.
* *Opportunities:* Every time new data about a contact comes into Hatch (from a CRM like ServiceTitan, or a lead source like Angi) a new opportunity is created. Some contacts that have been in Hatch for a long time might have a large number of past opportunities that you can look through by clicking the individual opportunity record. Within the opportunity record, you can search for field names and values.

<img alt="" />

By hitting the ellipsis next to a contact's name, you can see the contact's email and phone number, and perform the following actions.

* *Edit:* Quickly edit core contact information—the contact's name, email and phone number
* *Opt out:* Opt out this contact—this will prevent any outbound messages from Hatch (in any medium) from reaching the contact
* *Block / Unblock:* Block or unblock a contact's phone number from reaching your workspace
* *Delete:* Permanently delete this contact (admin only)

<img alt="" />

At the bottom of the contact card is the messaging box. Here is where you type messages to a contact. There are three symbols at the bottom left of this box:

* *Change contact method:* The first symbol shows which medium you're using to communicate with this contact. By default, your responses in Hatch will come from whichever medium your contact has used to contact you, but you can also switch in the middle of a conversation. A speech bubble means you're drafting a SMS message, a mail icon means you're writing an email, and the Yelp logo means you're going to send a message via [Yelp](/integrations/lead-sources/yelp-integration).
* *Add attachment:* Attach a file to your email / SMS
* *Use Suggested Response:* To avoid typing out the same message repeatedly, clicking this icon will let you fill in one of your pre-written [Suggested Responses](/how-to-use-hatch/board-contact-card/suggested-responses)

Hitting 'send' will send the contents of your messaging box. You can also click the downward facing arrow to schedule a message to be sent to this contact at a later date / time.


# Dispositions in Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/board-contact-card/dispositions-in-hatch

Here's how to track the results of your conversations in Hatch

When a contact responds to an outbound Hatch campaign, they'll appear front and center on your salesboard. Whether a Hatch AI Agent responds to the contact, or a Hatch user reaches out directly, the conversation will get assigned a  *disposition* , to help you keep track of what happened to the contact once they hit the salesboard.

***How do I manage dispositions in Hatch?***

<img alt="" />

Each organization in Hatch has one list of dispositions, for both human and AI conversations.

Managers in Hatch can go to the organization's settings page to add and manage dispositions

<img alt="" />

From the dispositions settings page, a manager can:

* Add a new disposition

* Delete an existing disposition

* Determine which dispositions should be marked as 'successful' for reporting purposes

***When does a 'conversation' start?***

<img alt="" />

For human users, as soon as an outbound message (SMS, email, Yelp) is sent by a user, the 'end conversation' button will appear in the messaging box.

For AI agents, a text conversation starts as soon as an inbound message is received in response to an outbound campaign to which the agent is assigned.

***What happens when a user ends a conversation?***

If you're finished with a text conversation with a contact, you can hit the 'End conversation' button to close it out—this will take the contact card *off* the salesboard. If you want to hand off to another user, or keep the contact on the salesboard, you can move the card to a new column, or assign it to another user (see [Contact Card Basics](/how-to-use-hatch/board-contact-card/contact-card-basics))

Now that the conversation is complete, the user will see the Conversation Complete modal, where they can select a disposition from the drop-down and optionally add a note:

<img alt="" />

By default, the following dispositions will appear in this drop-down:

* Success
* Appointment set
* Discarded
* Transferred
* Schedule follow-up

***How can I keep track of all the conversation records?***

Currently, we store a record in the contact history that a given disposition was applied before for both human and AI agent conversations, so when users revisit the contact, a record will be displayed.

<img alt="" />

On the reporting tab, you can also keep track of the results of AI conversations and their associated dispositions, and we're currently working on adding the results of human conversations to reporting as well.

<img alt="" />

In the near future, we'll have dedicated pages built into Hatch where you can keep track of new conversation records in real time—stay tuned!

***Can I still add a new disposition from the AI playground?***

*<img alt="" />*

Yes! If you use the */end* command in the playground, you can still add a new disposition from the drop-down list, and it will be stored on the same organization-level list as on the settings page.

***What happens if I delete an existing disposition?***

If you delete an existing disposition, it will no longer appear in the Conversation Complete modal when closing a conversation. AI Agents will continue to use that disposition if it’s assigned to an /End command within the Decision Tree. However, you’ll need to update the command before republishing the bot to ensure it reflects your changes.


# Salesboard Basics
Source: https://docs.usehatchapp.com/how-to-use-hatch/board-contact-card/salesboard-basics

The salesboard is where most of your conversations with your customers will occur. This article will give you a breakdown of the major features of the salesboard, as well as how to customize the Board to fit your team’s workflow. 

### Navigating to the salesboard

### <img alt="ezgif-5d72ac71b43615" />

The salesboard is your default view in Hatch as soon as you login to the website ([app.usehatchapp.com](http://app.usehatchapp.com)). If you have access to multiple workspaces, you can navigate between them on the left sidebar, by clicking the name of the workspace (or the workspace's initials, if the sidebar is in condensed mode).

<img alt="" />

### Salesboard Overview

#### How does the salesboard work?

Each workspace in Hatch has a *unique phone number and email* that allows your team to reach out to customers.

When a contact is put into a campaign, we use your workspace's information to send them text, voicemails, and emails. To your customer, it looks like they are simply having a text conversation or receiving a call.

<img alt="" />

*On your contact's phone, campaign messages appear like any other text message*

#### How do contacts get put on my salesboard?

When a contact sends you a communication (either a text or an email), their contact card will pop onto your salesboard, with an unread status. You click this contact card to respond to the message and take further actions in Hatch.

<img alt="" />

*When a contact responds to your campaign messages, they appear on your salesboard in the Inbox column with an unread notification.*

### What is on my salesboard?

The salesboard is where most of your conversations with customers will occur. The salesboard is made up of the following core features:

#### Contact Cards

Conversations with your customers pop up on the salesboard as 'contact cards,' which show the name of the contact, date of last communication, and which user in your workspace is assigned to the contact. Learn more about Contact Cards [here](/how-to-use-hatch/board-contact-card/contact-card-basics).

<img alt="" />

These cards contain not only the conversation you're having with your customer, but also details about the contact, notes, reminders, and sold entries. This allows you to get a complete overview of your customer without having to leave Hatch.

#### Columns

Contact cards are sorted into **columns** that your team can set up. You can name your columns in any way that suits your sales workflow, and add colored labels and symbols to help keep them differentiated. When a contact reaches a certain milestone in your flow, simply drag and drop the contact card into the appropriate column.

<img alt="" />

#### **Search your salesboard**

If you have a lot of contact cards on your board, easily retrieve a specific contact by using the search function. Only contact cards that meet your search criteria will appear on the board.

<img alt="" />

Next to the search bar, you can also use the Filter tool to isolate the contact cards that are relevant to you. If you've set reminders for a specific contact, scheduled a direct message for a contact, assigned a contact, or attached a [calling step to a campaign](/getting-started/messaging/calling-in-campaigns) for a contact, you can use filters to find them.

<img alt="ezgif-7946a70da42bd1" />

#### Create a Contact

You can create a contact quickly directly from the salesboard. If the contact already exists, it will update your previous contact record with any new information.

<img alt="ezgif-52a291cd3e7e48" />

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Can I change which salesboard a contact card appears on?">
    If you have access to multiple workspaces, you may want to move a contact from one salesboard to another. You can do that by using the <b>Move contact</b> tool on the contact card. As long as the two workspaces share contacts, the new card will appear on the other board, and a record of being moved will show in the contact's history.

    <img alt="" />
  </Accordion>

  <Accordion title="How do I put contacts directly on the salesboard?">
    If you ever want to put contacts on your salesboard without them sending an inbound message, you can find an existing contact record in the <a href="/how-to-use-hatch/contacts/contacts-basics">Contacts Page</a>. When you're in the open contact card, use the same 'Move contact' tool to bring the contact to the relevant salesboard.
  </Accordion>

  <Accordion title="How do I add other team members to a workspace?">
    If you are a Manager, you can add team members to a workspace from <a href="/how-to-use-hatch/account-settings/managing-workspaces">Account Settings</a>.
  </Accordion>
</AccordionGroup>


# Suggested Responses
Source: https://docs.usehatchapp.com/how-to-use-hatch/board-contact-card/suggested-responses

Save repetitive messages as a suggested responses for your team. Add new responses from Workspace Settings.

### **How it works**

1. Decide as a team how you would like to respond to certain messages. We often see message templates for things like **Pricing or Timing Objections** , **Not Interested** , or **Quick Follow Up**. If you're frequently sending the same hyperlink to customers, suggested responses are a good place to store it.
2. Add **a** **new response or edit a previously written response** from Workspace Settings under the **Features Tab**. Give it a title that will make it easily identifiable, and then add the message you'd like to save time by filling in automatically.

<img alt="" />

3\. When crafting a message from inside a contact card, write a message from scratch or use one of your new suggested responses.

**<img alt="" />**

**When to Use Suggested Responses**

You can add as many suggested responses as you want within your workspace.

We have found that our customers add message templates for the following reasons:

1. You find your team sending the same message over and over
2. To build consistency in messaging amongst team members
3. To save time from having to write messages / hyperlinks out manually


# Organization-Level Business Hours
Source: https://docs.usehatchapp.com/how-to-use-hatch/business-hours-features/organization-level-business-hours



### Setting up Organization-Level Business Hours in Account Settings

Setting Organization-Level Business Hours in the Account Settings before setting workspace-specific Business Hours is best practice because all workspaces will inherit these Organization-Level Business Hours by default, and can then be customized in specific workspaces as needed.

#### Operating Times

In the Account Settings, there is a section for Business Hours that includes an opening time and a closing time for each day of the week. By default the Business Hours are Monday through Friday from 9:00am to 5:00pm.

You are free to edit the operating times as necessary.

#### Auto-Reply Message

Below the Operating Times section is a text box that shows the message that a contact will receive if they message the workspace outside of the Operating Times.

This is the default message:

> *Thanks for reaching out! We are currently closed, but we wanted to confirm we received your message. We’ll get back to you as soon as possible after we open at \[\[next\_open\_time]].*

You are free to edit the verbiage if you'd like to say something specific.

#### Snippet

You’ll notice the default message has a snippet called  *\[\[next\_open\_time]].* This is the only snippet available for the auto-response and is determined by the operating hours. If the next open time is Thursday at 9:00am, in the message it will look like  ***9am Thursday***.

#### Toggling On/Off

<Note>
  **Note:** You must click the edit button before the On/Off toggle can be used
</Note>

If there are workspaces that inherit the Global Business Hours settings, those workspaces will:

* have Business Hours off if Organization-Level Business Hours are toggled off
* have Business Hours on if Organization-Level Business Hours are toggled on

Newly-created workspaces will inherit the Organization-Level Business Hours settings by default.


# Speed to Lead Alternate Messaging
Source: https://docs.usehatchapp.com/how-to-use-hatch/business-hours-features/speed-to-lead-alternate-messaging



<Note>
  **Note** : It is recommended that you set up [Organization-Level](/how-to-use-hatch/business-hours-features/organization-level-business-hours) and/or [Workspace-level](/how-to-use-hatch/business-hours-features/workspace-level-business-hours) Business Hours before continuing with this article, as both messages in this feature rely on established business hours.
</Note>

### Overview

For campaigns that have the first message  *At Launch* (Speed to Lead), there is an option to create alternate messaging for  *After Business Hours*. You can toggle this option on in the campaign editor.

If  *After Business Hours* is enabled, leads that come in during non-business hours will receive the alternate message. You can update this messaging by clicking the After Business Hours button in the campaign editor.

The contact will receive a message as soon as they launch into the campaign, and will also receive a message at the next open time (determined by set business hours), with whatever additional information is included in the second message.

<img alt="" />

#### Things to Note

* The alternate messaging option is only available if the campaign’s first message is  *At Launch*
* If you change a campaign’s first launch time from *Launch* to a scheduled time, the alternate messaging option will disappear
* For alternate messaging, the *times* of the messages cannot be modified.
  * First message will always be  *At Launch*
  * Second message will always be  *Next Open Time* (determined by workspace Business Hours)
* \[\[next\_open\_time]] is available as a snippet for alternate messaging only
* Alternate messaging is SMS only
* The regular messages associated with 'Launch Day" for a campaign are skipped if these after-hours messages go out
  * Normal campaign resumes the day after the Alternate messaging 2nd message (the one set for  *Next Open Time*)—i.e., Day 3 in a typical cadence, assuming no inbound from the contact.

### Default Messages

**First Message (At Launch):**

> *Hi \[\[Contact First Name]]! This is \[\[User First Name]] from \[\[Details Company Name]]. We’re closed right now, but I wanted to confirm we received the quote request you just submitted. If you reply with some details about your project, I’ll reach out as soon as I’m available after we open \[\[Next Open Time]].*

Users can edit the message if they’d like it to say something specific.

**Message at Next Open Time:**

> *Hello this is \[\[User First Name]] I just wanted to follow up with you on your request now that we are back in the office. Are you available to chat a bit more about your project?*

Users can edit the message if they’d like it to say something specific.


# Workspace-Level Business Hours
Source: https://docs.usehatchapp.com/how-to-use-hatch/business-hours-features/workspace-level-business-hours

Set the hours your workspace is open and configure an automatic after-hours SMS reply for contacts who reach out outside those hours.

<Note>
  It is recommended that a manager-level user set up [Organization-Level Business Hours](/how-to-use-hatch/business-hours-features/organization-level-business-hours) before configuring workspace-level business hours. Workspaces can inherit from the organization, which keeps things consistent and reduces repeated setup.
</Note>

<Frame>
  <img alt="Workspace-Level Business Hours" />
</Frame>

### Accessing business hours settings

Go to **Workspace Configs** and click the **General** tab. The **Business Hours** section is below the General section on the same page.

### Setting your hours

At the top of the Business Hours section, a dropdown lets you choose where this workspace's hours come from:

* **Your organization's name** — the workspace inherits hours from your organization's settings. Any changes to org-level hours will automatically apply here.
* **Another workspace** — inherit hours from a specific workspace that uses custom hours. Only workspaces with custom hours set appear in this list.
* **Custom Hours** — set hours specific to this workspace, day by day.

When **Custom Hours** is selected, you'll see a row for each day of the week. Toggle a day on to mark it as open and set the open and close times. Toggle it off to mark it as closed.

### After-hours auto-reply

Below the day rows, the **After Hours** section controls what happens when a contact messages outside your business hours.

A second **Inherit From** dropdown lets you choose the source for after-hours behavior — your organization, another workspace, or a **Custom Response** specific to this workspace.

When **Custom Response** is selected:

* Toggle **Send SMS** on to automatically reply to contacts who text outside business hours.
* Write the message you'd like to send in the text field. You can use snippets (like `[[Contact First Name]]`) to personalize the reply.

### Saving changes

Click **Save** to apply your changes. Click **Cancel** to discard them. You must have Manager permissions to edit business hours.


# Campaign Basics
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/campaign-basics



### What is a campaign?

Campaigns tell Hatch when to send messages, what those messages should say, and in which channels.

#### **Top Tips for Campaigns**

* Campaigns allow you to automate outbound messages via text, email, phone calls, and voicemail drops.
* Campaigns are created for specific workspaces and are not shared across different workspaces.
* Campaigns can be created from scratch or from a results-driven template.
* A campaign tells Hatch **what** to send, an audience tells Hatch **who** to send to, putting them together in a [workflow](/how-to-use-hatch/workflows/workflows-overview) gets outreach going!

### Finding Campaigns

On the left side navigation, click your workspace and hit **Campaigns** in the drop-down. On the Campaigns page, you can edit, duplicate or delete any existing campaigns, or create a new one by clicking the 'Create Campaign' button on the top right corner.

<img alt="" />

### How it Works

1. A campaign can be created from scratch, or by using an existing template aligned with Hatch best practices. In the campaign template gallery, you can click "Estimate Follow-up" to create a campaign to follow up on open estimates.

<img alt="" />

2. After selecting a template, you can update the messaging to suit your needs. [Learn more about creating a campaign here](/how-to-use-hatch/campaigns/create-a-campaign).

<img alt="" />

3. Contacts get launched into your campaign through a [workflow](/how-to-use-hatch/workflows/workflows-overview), or can be launched manually. For our Estimate Follow-Up campaign, we can set up an audience looking for all contacts with open estimates in ServiceTitan (or another CRM), so that each contact with an open estimate receives the messaging.
4. When contacts respond to your campaign, they will pop up in the Inbox column on your salesboard. Once a contact responds, they won't receive the subsequent messages in the campaign—you (or a bot!) take it from there.

<img alt="" />

### Resources

Hatch Customer support is always available if you want help creating campaigns, or want to hear what we've learned from successful campaigns in the past.

Here are some things to know:

**[Create a Campaign](/how-to-use-hatch/campaigns/create-a-campaign):** Check out how to create a campaign from a template

[**Edit or Update a Campaign**](/how-to-use-hatch/campaigns/update-a-campaign): Edit a previously created campaign

[**Launch Contacts into Campaigns**](/how-to-use-hatch/campaigns/launching-contacts-into-campaigns): Launch contacts into campaigns from the contacts page

[**Remove Contacts from Campaigns**](/how-to-use-hatch/campaigns/removing-contacts-from-campaigns): Remove some or all contacts from campaigns


# Campaign History
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/campaign-history



Campaign History is your cross-campaign audit log — a single place to see what's happened with every contact across every campaign in your workspace. Use it to reconstruct a contact's full campaign journey, verify that messages went out as expected, and quickly answer "what happened to this contact?" without hopping between individual campaigns.

## How to Access Campaign History

<img alt="Open Campaign History from the Campaigns tab" />

1. Click **Campaigns** in the left menu
2. Click the **History** button at the top of the page

You'll land on the Campaign History view, which shows activity across all campaigns in your workspace in chronological order.

<Note>
  Campaign History is scoped to the workspace you're currently in. If you have multiple workspaces, switch between them to see each workspace's history.
</Note>

## What You'll See in the History Table

<img alt="The cross-campaign History table" />

Each row is one audit event for one contact. The columns are:

* **Event**: What happened (see [event types below](#event-types-explained))
* **Campaign Name**: Which campaign the event belongs to — so you always know the source even when scanning activity from many campaigns at once
* **Type**: Campaign type (scheduled, instant, or third-party)
* **Date & Time**: When it happened, shown in your board's timezone
* **Customer Name**: The contact's name
* **Phone**: The contact's phone number
* **Email**: The contact's email address

## Filtering Your History

By default, History shows activity across every campaign. Use the filters at the top of the table to scope what you see:

* **Campaign**: Pick a single campaign to reproduce the old per-campaign view — useful when you're debugging one specific send sequence
* **Contact name**: Find every event for a specific person, across every campaign they've been part of within this workspace

Filters can be combined. Clearing them returns you to the full cross-campaign view.

## Event Types Explained

Here's what each event type means:

* **audience\_match**: The contact met your campaign's audience criteria and qualified to receive the campaign.
* **in\_campaign**: The contact is actively receiving campaign messages. The campaign is currently running for this contact.
* **completed**: The contact received all campaign messages and finished the campaign successfully.
* **removed**: The contact was taken out of the campaign. This happens when:
  * They matched a removal rule you set up
  * They opted out of messages
  * You manually removed them
  * Other removal conditions were met
* **scheduled\_step\_successfully\_sent**: A message from the campaign was successfully sent to this contact.
* **scheduled\_step\_failed\_to\_be\_sent**: A message was successfully scheduled, but couldn't be delivered when it was time to send. This usually points to a delivery problem at send time — for example, a carrier rejection or a phone number that became invalid between scheduling and sending. If the message was never scheduled to begin with, you'll see scheduled\_step\_not\_created instead. If it missed its send window entirely, you'll see scheduled\_step\_stale instead.
* **scheduled\_step\_stale**: A message was scheduled but didn't go out in time — this can happen during high-traffic periods when sends get briefly delayed. Since too much time had passed, the message wasn't sent, and it clears from your history automatically within 2 business days.
* **scheduled\_step\_not\_created**: A specific message in this campaign couldn't be scheduled for this contact, so that message was skipped. The rest of the campaign continues for the contact — only the specific step that failed is recorded here. The event details explain *why* the message was skipped. Common reasons include:
  * The contact is missing a phone number or email needed for this message
  * The contact's phone isn't SMS-capable
  * 10DLC registration isn't approved for the workspace
  * The message landed outside of business hours and after-hours sending isn't enabled
  * The message uses a [snippet](/how-to-use-hatch/campaigns/snippets) that failed to compile — for example, a snippet that references a field the contact doesn't have a value for
* **scheduled\_step\_rescheduled**: A scheduled message was moved off its original send time because of a [configured holiday](/how-to-use-hatch/account-settings/holidays) or a weekend. The event details name the trigger — for example, "Due to \[holiday name]" or "Due to weekend" — so you can see exactly why the send shifted. This includes both the initial schedule and any later shifts caused by a previous step being moved.
* **failed**: An error prevented the contact from entering the campaign. This could be due to invalid contact information or a system issue.
* **not\_launched**: The contact wasn't launched into the campaign because they didn't meet certain requirements.

## Viewing Contact Details

<img alt="Campaign History contact details panel" />

Click any row to see more information about that contact:

* The reason the campaign step occurred
* When the contact was created
* Their complete contact information (name, email, phone)
* Opportunities associated with this contact

## What You Can Use This For

The Campaign History helps you:

* **See a Contact's Full Journey**: Filter by a contact's name to view every campaign they've been part of, in order, in one continuous timeline
* **See Who Enters and Exits**: Track which contacts join your campaigns and which ones leave
* **Understand Why**: See the reasons contacts enter or exit campaigns
* **Track Message Delivery**: Know exactly which messages were sent to each contact, and which were skipped
* **Debug Skipped Messages**: When a message is skipped (via scheduled\_step\_not\_created), the event details point straight at the cause — broken [snippets](/how-to-use-hatch/campaigns/snippets), missing contact fields, compliance gaps, or after-hours rules — so you can fix the underlying issue without guesswork
* **Confirm Holiday & Weekend Behavior**: When scheduled\_step\_rescheduled fires, you can verify that your [configured holidays](/how-to-use-hatch/account-settings/holidays) and weekend rules are being honored, and trace why a contact received a message on a different day than originally planned
* **Monitor Timing**: See when each message was delivered

<Tip>
  The Campaign History is your single source of truth for *what happened and why* across all of your campaigns. If you're investigating why a specific contact didn't get a message — or got it later than expected — start here before digging into the campaign setup. The skipped-message and rescheduled events surface the underlying cause directly.
</Tip>

## Navigating Your History

If you have a lot of activity, use the page controls at the bottom of the table to browse through it. History loads more events as you page through, so even very busy workspaces stay responsive.

***

**Note**: The History tab shows the last 90 days of contact activity across your campaigns.


# Create a Campaign
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/create-a-campaign

Creating a campaign is easy with campaign templates. We'll walk through how to make a campaign from start to finish.

### Step by Step

#### <img alt="" />

####

####

#### Step 1 - Navigate to the Campaigns Page

Hit the campaigns tab to see all the campaigns associated with your workspace. On the campaigns page, you can edit your messaging cadence, rename, delete or duplicate your campaigns, and see how many contacts are active in a campaign.

To create a new campaign, click 'create campaign'.

<img alt="" />

#### Step 2 - Create Campaign

From the campaign templates, you can decide if you want to build a campaign from scratch or use one of the templates provided, aligned with Hatch marketing best practices, across a range of use cases.

#### Step 3 - Write your verbiage and pick your cadence

<img alt="" />

If you are using a campaign template, take a look through  *all* the messages to ensure they're aligned with your marketing needs. Snippets make sure that every campaign will adapt to the information you have in Hatch—\[\[Details Company Name]] will say your company name for the end user!

If you're starting from scratch, you'll need to determine what types of messages need to go out (and when). We recommend multiple touch points across text, email, and calls on different days, but it all depends on the type of campaign you'd like to run.

#### Step 4 - Adjust message send times

Text, emails, and voicemail drops can be sent at any time you like.<img alt="" />

*If you choose 'Launch' for send time* , contacts will start receiving messages as soon as they meet the criteria for an audience in an active workflow. For example, if an at-launch campaign is paired in a workflow with an audience tied to lead source like Angi, as soon as Hatch receives the new contact information from Angi, the first message will go out.

*If you choose a specific send time* , the message will go out the when that time rolls around again. If contact information comes in from at Angi at 3pm today, but the first message in the campaign isn't until 9am, the first message will send at 9am tomorrow.

#### Step 5 - Adjust Details + Create Campaign

Choose if you would like this campaign to **send messages on the weekend** or **on holidays**. Your organization's holiday list is managed in [Account Settings → Holidays](/how-to-use-hatch/account-settings/holidays).

For an at-launch campaign, you can also select separate messages to go out outside of your [workspace's business hours](/how-to-use-hatch/business-hours-features/workspace-level-business-hours). If you'd like to notify a contact that you've received their information, and plan to send them a message in the morning, you simply toggle the 'after business hours response'.

<img alt="Screenshot 2025-01-13 at 11.44.13 AM" />Once you have reviewed your changes and made any adjustments, click Create Campaign. If you ever want to make additional edits to the campaign, simply click back into the campaign from the Campaigns page.

> **Note** : any contacts that are **actively in campaign** when changes are made will receive the campaign messages that were set  *before* the changes were made. Any contacts that are put into campaign after changes were made will receive the new messages.


# Launching Contacts Into Campaigns
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/launching-contacts-into-campaigns



Once a [campaign has been created](/how-to-use-hatch/campaigns/create-a-campaign), then it's time to engage your contacts.

In order to receive a high response rate and quality engagement from your contacts, it's important to make sure that you are picking the right people to put into the campaign.

<Note>
  **Note** : Confirm that your [CRM integration is set up](/integrations/crm-field-management-systems) and recently synced before launching a campaign. That way contacts in Hatch are always up to date with the most recent details and statuses.
</Note>

### Picking Contacts for Campaign

It's important to keep some things in mind when deciding who to put into campaign.

From the contacts page, you can filter down your contacts based on CRM status, month, year, name, and more. To see a full list of what you can search for, [click here](/how-to-use-hatch/contacts/how-do-i-search-in-hatch).

Let's say we want to send out a Sales Follow Up campaign to any contact that had an appointment within the last 24 hours.

**Here are some questions to ask yourself** :

1. What status will those contacts have?
2. What month or year should the contacts have?
3. Do you want to engage with customers that were recently put into campaign?
4. Are you running a text-only campaign? You might want to filter down to only show contacts that have mobile numbers.
5. Are there any other contact details that you might want to target off of?

### Launching Contacts into Campaign

Once you have decided who to launch into campaign...

1. Navigate to the [Contacts Page](/how-to-use-hatch/contacts/contacts-basics).
   <img alt="Screen Shot 2022-08-15 at 12.39.20 PM" />

*Click on the contacts icon in the left nav.*

2. **Pick your contacts** by clicking on box located on the left hand side of their contact card.
   *Select contacts by clicking on their contact cards or clicking Select All.*

3. **Select your campaign** from the dropdown.

*Pick which campaign you want to launch. You will be able to preview the message before it is sent out to the contacts.*

4. Confirm that the messaging is correct and is sending when you want it to send out, and hit **Launch Campaign**.

*Once you have confirming your the campaign, click Launch and the campaign will begin to run immediately.*

### Responding to Messages

If messages are sending out on launch, expect to see responses start rolling in within 10-15 minutes–sometimes sooner! Remember, these customers are used to texting and are ready to get the conversation started as soon as possible.

> Please **DO NOT** attempt to remove contacts from a campaign by deleting the campaign.

If you need to delete a campaign with active contacts in it, you must remove the contacts first, then delete the campaign. Otherwise, you will not be able to immediately add the contacts to a new campaign.


# Removing Contacts from Campaign
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/removing-contacts-from-campaigns



Sometimes you might want to remove contacts from a campaign. The easiest way to do this is to go to the Campaigns Page.

1. From the campaigns page, click into the campaign card, and click **In Campaign**.
2. Here, you can see all the contacts that are in campaign. To remove someone from campaign, click on the **trash can icon**. To remove everyone from campaign, click **Remove All.**
3. To confirm the change, click **Remove Contacts**.

**Please DO NOT attempt to remove contacts from a campaign by deleting the campaign.**

If you need to delete a campaign with active contacts in it, you must remove the contacts first, then delete the campaign. Otherwise, you will not be able to immediately add the contacts to a new campaign.


# Snippets
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/snippets

Personalize campaign messages with snippets to dynamically reference your contacts information 

<img alt="Snippets" />

### Using Snippets

Snippets are a feature in Hatch that allow you to dynamically insert information into your campaign messages to make them more personalized, like:

* Contact First Name
* User First Name
* Details Company Name
* Appointment Date
* Address
* And more

When [creating a campaign](/how-to-use-hatch/campaigns/create-a-campaign), the Snippet dropdown allows you to view all of the Snippets available from your sources, and insert them into your message.

#### How Snippets are Populated

Snippets are formatted differently depending on the field you are targeting.

<Tip>
  **Updated May 2025** : We updated the formatting of snippets to *include* the name of the source. Any snippets added to campaigns prior to this change are formatted as \[\[ Details `field_name` ]], and populate from the latest opportunity.
</Tip>

* **Contact Information:** Snippets that pull Contact-Information, like the contact's First Name, begin with `Contact`
* **User Information (*your* information)**: Snippets that pull User-Information, like your First Name, begin with `User`
* **Opportunity Information** : Snippets that pull Opportunity-Information, such as the information from an Integration or CSV Import, begin with `Details` and include the `Source_Name`

When you choose a snippet from the dropdown with Opportunity Information, it will be formatted to include the Source Name in quotes. For example, a snippet to pull in Appointment Date from Service Titan will be formatted as `[[Details "Service-Titan" AppointmentDate]]`

Opportunity-Information is populated from the most recent opportunity from that source. In the example above, the `[[Details "Service-Titan" AppointmentDate]]` will always populate from the **most recent** Opportunity from Service Titan.

For cases where you want to be *even more specific* in targeting, you can specify [the **model** of the Opportunity](/getting-started/hatch-assistant/hatch-assistant-servicetitan-calendar-integration#data-storage) you want to pull from. Some integrations provide different types of opportunities (Like Service Titan, which offers Calls, Jobs, and Membership Opportunities). If you want to ensure that a Snippet pulls from the most recent Opportunity from a certain source and a specific model, you can include the model in quotes after the source. Example: `[[Details "Service-Titan" "Job" AppointmentDate]]`.

#### Contacts that don't have a value for a Snippet

Sometimes, the Contact receiving the message does not have information to populate the Snippet you’re using.

For example:

* You have a Campaign Message that references the Contact’s `Appointment Date`, and a Contact with *no* `Appointment Date` enters that Campaign
* You have a Campaign Message that references the Contact’s `First Name`, and that Contact’s information is accidentally missing from their record

When this happens, Hatch will leave the missing value blank by default — so instead of a customer getting a message that says “Hi \[\[Contact First Name]]!”, they’ll get a message without the name filled in. You can also use Snippet Fallbacks to further customize this behavior, like swapping in a fallback value, or choosing not to send the message at all.

*(As an aside, this is why we highly recommend creating audiences that require a value for each field you use as a snippet—more on that below)*

### Snippet Fallbacks

<Tip>
  Currently Snippet Fallbacks are only available for the `[[Contact First Name]]` Snippet
</Tip>

Snippet Fallbacks improve the verbiage and deliverability of messages when certain dynamic information is missing from that message. Read on to understand what that means and how to use this feature.

#### What are Snippet Fallbacks?

With Snippet Fallbacks, you can configure certain Snippets to change behavior if the information it’s looking to reference in a message is missing. In particular, it can:

* Become blank
* Swap in a Fallback Value

This allows for messages to still be sent - and make sense to your recipient - even when that message is missing a value. Note that you’ll still have the option to not send the message.

Here’s what that looks like in the Campaign Builder:

<img alt="" />

#### How to use Snippet Fallbacks

Let's say you have a Campaign Message that says:

> *Hi **\[\[Contact first name]]** , this is \[\[User First Name]] with \[\[Details Company Name]]. Thanks for texting us! Can you tell me more about what you need help with?*

If the Contact **has a value** for First Name, the message would be formatted as:

> *Hi **Tim** , this is **Benji** with **Best Home Improvement**. Thanks for texting us! Can you tell me more about what you need help with?*

If the Contact **does not have a value** for First Name, you can use Snippet Fallback Logic to handle this message in the following ways:

| **Snippet Fallback Setting** | **Message**                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Leave Blank (Default)        | *Hi, this is **Benji** with **Best Home Improvement**. Thanks for texting us! Can you tell me more about what you need help with?*       |
| Fallback Value \[ "there" ]  | *Hi there, this is **Benji** with **Best Home Improvement**. Thanks for texting us! Can you tell me more about what you need help with?* |
| Don't Send Message           | The message will not be sent                                                                                                             |

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why would First Name be missing for some of my Contacts?">
    Certain lead sources only provide contact information like Phone Number and Email to contact a lead, and don't provide a Name.
  </Accordion>

  <Accordion title="What about Fallbacks for Other Snippets?">
    Today we only offer Fallbacks for the <code>\[\[Contact First Name]]</code> Snippet because it's the easiest and most logical snippet to <em>write around</em>. It would be challenging to write a message that can account for leaving a snippet like "Estimate Amount" blank, or fallback to a default value. But we are excited to find new ways to use this feature! If you have an idea, reach out to [support@usehatchapp.com](mailto:support@usehatchapp.com).
  </Accordion>
</AccordionGroup>


# The Sender Identification Requirement in Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/the-sender-identification-requirement-in-hatch

All SMS messages in your Hatch Campaign sequences must include Sender-Identification

<Note>
  All SMS messages in Hatch Campaigns were updated to include the `[[Details Company Name]]` snippet **on April 10.**
</Note>

Due to TCPA rules, all SMS messages in a Hatch Campaign sequence must include the `[[Details Company Name]]` snippet as a form of Sender-Identification.

### Opt-Out Language Requirement

In addition to sender identification, the **first SMS message** in every campaign must include an opt-out instruction using one of the following keywords in all caps: **STOP**, **STOPALL**, **UNSUBSCRIBE**, **CANCEL**, **END**, or **QUIT**.

For example: *"Reply END to stop texts."*

Hatch will show an error in the campaign builder if the first text message is missing this opt-out instruction.

### FAQs

<AccordionGroup>
  <Accordion title="Are any other snippets required?">
    No! The only requirement is that the <code>\[\[Details Company Name]]</code> snippet (which inserts your company name) is included in the message as a form of <b>sender-identification</b>. Additional snippets like <code>\[\[User First Name]]</code> (the name on your Hatch Board) or <code>\[\[Contact First Name]]</code> (the name of the contact you are messaging) are totally optional.
  </Accordion>

  <Accordion title="Does this apply to all texts?">
    No! The requirement <b>only affects SMS messages sent before a contact responds</b> —specifically, your <b>Hatch Campaigns.</b><br /><br />
    Once a contact <b>replies</b>, you are having an ongoing conversation and you’re no longer required to include your company name as a form of Sender Identification.<br /><br />

    <img alt="FAQ on Campaigns" />

    <br />

    All SMS (text) messages in <i>each step</i> of the sequence for a campaign need the <code>\[\[Details Company Name]]</code> snippet, see image above.
  </Accordion>

  <Accordion title="Do emails and voicemails require Sender-Identification too?">
    No! This only applies to SMS.
  </Accordion>

  <Accordion title="Why is Sender-Identification Required?">
    Mobile carriers have recently increased enforcement of SMS self-identification rules—meaning all messages must clearly state your company name before a contact responds. Messages that don’t comply will either be blocked or your number could be deactivated.
  </Accordion>

  <Accordion title="What if I didn't update my campaigns prior to this change?">
    Hatch updated all Campaigns that were missing the required snippet on your behalf on April 10th, 2025, to ensure TCPA compliance! These updates were made using AI to incorporate the snippet into your messages in a logical, conversational way.<br /><br />
    Now that your messages were updated to include the snippet, feel free to revisit them and make any changes you see fit.<br /><br />
    Any SMS messages that already had the snippet were not re-written.
  </Accordion>

  <Accordion title="Who can I reach out to for help?">
    You can email <a href="mailto:support@usehatchapp.com">[support@usehatchapp.com](mailto:support@usehatchapp.com)</a> or contact <a href="https://www.usehatchapp.com/contact-me">your Account Manager here</a>.
  </Accordion>
</AccordionGroup>


# Update a Campaign
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/update-a-campaign



Once you have [created a campaign](/how-to-use-hatch/campaigns/create-a-campaign), it’s easy to go back and adjust campaign messages.

<Note>
  **Note** : Any contacts that were already put into campaign before making campaign edits will receive the original campaign verbiage.
</Note>

### Step by Step

To start editing a campaign, simply click the pencil icon for the relevant campaign on the campaigns page.

<img alt="" />

Once you're in the campaign, you can see all the campaign messages that will send out each day. To make edits to the campaign, simply click on the message you want to edit and make your adjustments. You can change what time a message goes out, change the content of your messages, or any other changes you deem relevant.

To save your changes, click **Update Campaign**.

<img alt="" />


# Using Voicemail Drops in Campaigns
Source: https://docs.usehatchapp.com/how-to-use-hatch/campaigns/using-voicemail-drops-in-campaigns

Voicemails can be a powerful way to add personalization to your campaigns. In this tutorial, we'll walk through how to add voicemail drops to your campaigns. 

### Step by Step

#### Step 1 - Navigate to the Campaigns Page

On the campaigns page, you can see all the Campaigns that were created in the Workspace. You can add voicemails to previously created Campaigns or brand new ones. For this tutorial, let's add a voicemail drop to our Appointment Confirmations campaign. Click the three dots to the right of the Campaign to get to the Campaign Builder.![Screen\_Shot\_2021-06-11\_at\_5.04.36\_PM.png](https://help.usehatchapp.com/hc/article_attachments/4402868697357/Screen_Shot_2021-06-11_at_5.04.36_PM.png)

#### Step 2 - Select Day.

Within the Campaign Builder, select the day when you'd like to add a voicemail drop. For this example we're going to add a voicemail to Day 2, which is the day before the scheduled appointment. This is a great way to get customers to respond if they need to make any last minute changes.

#### Step 3 - Click the Voicemail icon.

Here you'll see options to "Select what type of message" to add another. Click on the 3rd circle with the voicemail icon.

After clicking the icon, a new message box appears prompting you to Record a voicemail. You can also see under "Day 2" that there is a voicemail icon on that date showing when this voicemail will be sent.

#### Step 4 - Update the time

Before recording your voicemail, if you'd like to adjust the time when it will be sent, you can do so now.

#### Step 5 - Record your voicemail.

Click the "Start Recording" button to record your voicemail. We recommend leaving this generic for all contacts who will receive it.

For our example a good voicemail could be  *"Hi there - This is Susan from Wally's Window World. We're excited to see you tomorrow for your appointment. If you need to reschedule for any reason, please call us at 804-123-4566. Thanks!"*

Once you're done, click "Stop Recording". You will see the length of time the message was recorded. You can record a voicemail up to **1 minute in length**.

At this point you can replay your message to make sure it says what you want. If you'd like to record it again, just click "Record Again". If you later decide you don't want a voicemail drop at all, just click "Remove".

#### Step 6 - Update Campaign

Don't forget to click the Update Campaign button in the bottom right after recording your voicemail so you don't lose it!


# Adding and Importing Contacts
Source: https://docs.usehatchapp.com/how-to-use-hatch/contacts/adding-and-importing-contacts



### Adding Contacts with a CSV File

The easiest way to get started is to import contacts through a **CSV**. This can be exported from your CRM, or wherever you keep customer information.

A basic CSV should contain the following information fields:

1. First Name
2. Last Name
3. Email
4. Phone Number
5. Status - such as “Sold” “No-Show” “Demo-Set” etc
6. Created or Updated Date

If your CSV contains more fields, we will enter those as well as contact details for easy reference. Use [our Template](https://docs.google.com/spreadsheets/d/1Lh3H-kFJ3qVdWlXsAJ_AbzV_Eaho8ROaSJN5KUPZKkY/edit?usp=sharing) to get started

### Adding Contacts through a CRM

For the long term, you will probably want to set up an integration with your CRM. We offer several integrations with our partners. See our [full list of our integrations here](https://www.usehatchapp.com/integrations), and contact our team to set one up!


# Contacts Page
Source: https://docs.usehatchapp.com/how-to-use-hatch/contacts/contacts-page

Documentation for Contacts Page

### Navigating to the Contacts Page

When you log into Hatch, by default you will be on a Salesboard to which you are assigned. On the left-hand side of the screen (to the right of the workspace tiles), you will see a navigation bar that allows you to go to other pages.

<img alt="" />

In order to get to the Contacts page, click the person icon <img alt="" />. It is the second-highest icon in the navigation bar.

### The Full Contacts Page

Below is the entire contacts page and in the sections below we will cover a series of sections in depth.

<img alt="" />

### Header Section

<img alt="Screen Shot 2022-10-03 at 1.48.07 PM" />

* **A: Search**
  * Use the Search Type drop-down to select what field to search by (Full Name, First Name, Last Name, Phone, or Email), then enter a search term and either hit Enter or click the magnifying glass to return matching contacts.

* **B: Audiences Drop-down**
  * This is a list of all audiences that exist on the workspace.
  * The default is "All Contacts".
  * If an audience is selected, the contacts list will filter to contacts that currently fit that audience.
  * An audience must be selected to enable the *Edit an Audience* or *Duplicate an Audience* features.

* **C:** **Edit an Audience shortcut**
  * Clicking this will open a query editor that is populated with the selected audience's criteria.

* **D: Total Contacts**
  * This is a count of all the contacts that exist in the current workspace.

* **E: Total in Audience**
  * This is a count of all the contacts that fit the criteria of the selected audience.
    * If no audience is selected, this will be 0.

* **F: Selected Contacts**
  * This is a count of all the contacts that are currently selected (the checkbox by their name is ticked).

### Actions Section

This menu is on the right-side of the Contacts page. This area of the screen is also where the query editor lives when opened.

* **A: Upload CSV**
  * <img alt="Screen Shot 2022-10-03 at 1.59.51 PM" />Clicking this button will lead to an option to download a CSV template or upload an existing CSV to add contacts to Hatch manually
* **B: Create Audience**
  * Clicking this will open the Audience Builder where you can create and save a new audience.
* **C: Duplicate Audience**
  * Once an audience is selected, this option will be available and you will be able to duplicate the selected audience.
* **D: Edit Audience**
  * Once an audience is selected, this option will be available and you will be able to edit the query of the selected audience.
* **E: Launch into Campaign**
  * When this is clicked, you will be able to select a campaign from that workspace and a preview of the messaging will show up.
  * When contacts are selected, you will then be able to manually kick off the selected campaign for the selected contacts.
* **F: Create a Contact**
  * Clicking this opens a form to input
    * First Name
    * Last Name
    * Phone Number
    * Email Address
  * Clicking save will create a new contact or will add an opportunity to an existing contact if that phone number or email is already associated with a contact.

### Contacts Table Section

<img alt="" />

The contacts table displays the following columns: First Name, Last Name, Email, Phone Number, and Tags.

* **Tags**
  * Tags indicate the following about a contact:

    * If the contact is currently in a campaign, the campaign name is shown
    * If the contact has been opted out, the tag will specify the type:
      * **Opted Out** — The contact is fully opted out of all communication
      * **Text Opt-Out** — The contact has opted out of SMS only (they can still receive emails)
      * **Email Unsubscribed** — The contact has unsubscribed from emails only (they can still receive texts)

  * If a contact is in a campaign or opted out of the relevant channel, that contact cannot be selected to launch into a campaign
* **Rows Per Page**
  * This allows you to choose the amount of contacts that appear per page to scroll through
  * The count next to this is which range within the contacts the current page is on


# How do I Search in Hatch?
Source: https://docs.usehatchapp.com/how-to-use-hatch/contacts/how-do-i-search-in-hatch

The true power of Hatch is being able to segment your customers to make sure to provide them with the right messaging at the right time. You can accomplish this by filtering your contacts before you put them in campaign. 

**Where is my search bar?**

The search bar is located at the top of the page of the contacts page. Here you can pull the customers you wish to automate and funnel into your sales board.

<img alt="" />

* **A: Search**

  * Use the Search Type drop-down to select what field to search by: Full Name, First Name, Last Name, Phone, or Email. Type a term into the search box and either hit Enter/Return on your keyboard or click the magnifying glass icon to run the search.
* **C: Audiences**

  * This drop-down provides a list of audiences that exist on the current workspace. Selecting an audience will filter the contact table to only show contacts that fit the audience at that time.
  * When you select an audience, you will also be able to see/modify the query by clicking the pencil icon next to the Audiences drop-down.


# Importing Contacts with a CSV
Source: https://docs.usehatchapp.com/how-to-use-hatch/contacts/importing-contacts-with-a-csv

The easiest way to get started is to import contacts into Hatch is through a .CSV file. This can be exported from your CRM, or wherever you keep customer information. 

A basic .CSV is required to have the following information fields (columns) in or

| **Field Name** | **Example**                                                     | **Notes**                                                                            |
| -------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| First Name     | Sarah                                                           | Column Required, but contact will still import if not available for certain contacts |
| Last Name      | Stevens                                                         | Column Required, but contact will still import if not available for certain contacts |
| Email          | [sarah@longhouseroofing.com](mailto:sarah@longhouseroofing.com) | A contact must have either a phone number and/or email to be imported.               |
| Phone Number   | 401-017-1947                                                    | A contact must have either a phone number and/or email to be imported.               |
| Status         | Working                                                         | Column Required, but contact will still import if not available for certain contacts |

Hatch directly supports the following additional fields. We recommend you add the following if they are readily available:

| **Field Name** | **Example**                                                                      | **Notes**                                                                                                                                                         |
| -------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created Date   | 2/15/2020                                                                        | This field can be used for contact created date, or appointment created date.                                                                                     |
| Updated Date   | 2/20/2020                                                                        | This is often a 'Last Modified Date' or a 'Last Updated Date/Time' field                                                                                          |
| External ID    | 10710393                                                                         | If the contact as an ID associated, such as appointment or opportunity ID. This field will take place of that.                                                    |
| Other Details  | Representative Name, House Color, Address, Spouse Name, Appointment Time, Source | All other details will still import into Hatch. They will show up in the contact as details. There details can still be used for targeting and campaign language. |

If you need an example, copy [our Template](https://docs.google.com/spreadsheets/d/1Lh3H-kFJ3qVdWlXsAJ_AbzV_Eaho8ROaSJN5KUPZKkY/edit?usp=sharing) to get started.

### Creating Campaigns with Imported Contacts

#### Creating a List for Campaign

Contacts can be launched into a campaign using any details that were added upon import. To learn more about Campaign in general, [click here](/how-to-use-hatch/campaigns/launching-contacts-into-campaigns).

*If you like to segment contacts prior to importing into Hatch, we recommend adding a 'tag' upon import to easily find contacts for launch.*

1. When creating your CSV, **add a column** called "Campaign Tag". For each contact, add a value that will be unique for that list of contacts. For example "Rehash21024" or "HomeshowOctober". Here you can see a tag of "HomeshowOctober" was added to the contact record. We will use that to search for later in Hatch.
2. **Go to the Contacts Page within Hatch and click Import CSV.** Make sure fields have matched up appropriately, and confirm the import.

**Import your CSV, and then confirm all the fields are matching up appropriately. Fields that don't match will still come through as Details.**

3. Once contacts are imported you can locate the list in the audience builder by selecting the Imported as the source option on the contacts page within the Audience Builder and selecting the column name you decided on your tag. Using this criteria you can also save the audience for these contacts and use that audience to automatically launch contacts into the campaign via workflow.

**Using the tag we've added on in the CSV, we can now search for our unique list of contacts in Hatch.**

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="I do not see an option to export a .CSV from my CRM. Are there other formats I can use to import my data?">
    Currently Hatch only supports the importing of **.CSV** files.

    However, many common spreadsheet formats can easily be converted to a .CSV using Google Sheets or Microsoft Excel. If you can export as a .XLS, .XLSX, or a .TSV these formats can be saved as a .CSV with little to no data loss.
  </Accordion>

  <Accordion title="I want to launch every contact in a campaign on this .CSV I am importing. How do I find the contacts easily once I import the .CSV?">
    We recommend adding a unique tag on the CSV that you can search for later in Hatch. [Click here](/how-to-use-hatch/contacts/importing-contacts-with-a-csv) to learn more.
  </Accordion>

  <Accordion title="My .CSV has the customer's First Name and Last Name combined into one field/column. Can I use this column when I import the .CSV?">
    While Hatch will not stop you from importing your .CSV, it's important that these are two separate fields.

    Our recommended messaging is built around only using the customer's First Name. If these two fields are joined, then the customer will always be called by their Full Name.
  </Accordion>

  <Accordion title="I have multiple columns containing phone numbers. Will Hatch know to grab phone numbers from different columns?">
    Hatch only supports matching **one phone number** to a contact. If you have multiple columns of phone numbers, we recommend mapping the Hatch Field to any mobile numbers columns you have available.

    If you wish to target different kinds of phone numbers for different customers located across multiple columns, you'll have to combine those columns together so every contact has a phone number in Hatch.
  </Accordion>

  <Accordion title="My question isn't here!">
    Reach out to us at [support@usehatchapp.com](mailto:support@usehatchapp.com) so we can get it answered for you!
  </Accordion>
</AccordionGroup>


# Looking at Contact Information
Source: https://docs.usehatchapp.com/how-to-use-hatch/contacts/looking-at-contact-information



On the Contacts Page, contacts will show the first and last name of the contact as well as the **most recent** Status and Created Date. If you open a contact card, you can find all the information that was pulled in through the import in the **Contact Details**.

This can include fields like Address, Sales Representative, or Quote Amount. Whatever we can pull through the import or integration is what shows here.

### Understanding Opportunities

Contacts are made up of *multiple opportunities*. This varies depending on how you manage your contacts.

If you have multiple opportunities, we will show the most recent opportunity.

<img alt="" />

You can see this contact has two opportunities. One created in January, and another created or updated in July.

If you always update the same opportunity or lead with new information, we will take the most recent information and show that.


# Conversations Page
Source: https://docs.usehatchapp.com/how-to-use-hatch/conversations/conversations

A real-time log of every AI and human conversation across your organization.

The Conversations page is a real-time log of all customer interactions across your organization. Use it to find, review, and audit conversations without digging through individual contacts or boards.

<img alt="Conversations" />

Each row is a single conversation, created whenever a new interaction occurs. A conversation starts when a contact initiates an inbound action — replying to a campaign, or calling in — and ends when a disposition is applied to close it.

## Getting there

Go to **Conversations** in the left-hand sidebar.

<img alt="Navigation" />

Conversations update in real time. Refresh the page to pull in the latest activity.

## Voice and Text tabs

The page is split into two tabs, because a phone call and a text thread aren't reviewed the same way.

* **Voice**: phone calls, including every call handled by your Voice AI agent. Voice conversations carry the richest data — a recording, a transcript, an AI-generated summary, and the full set of [Conversation Metrics](/how-to-use-hatch/conversations/glossary) such as Category, Booking Status, and Handling.
* **Text**: SMS and email conversations, including those handled by your AI text agents. Text conversations show the message thread and the disposition that closed it out, but not the voice-specific metrics.

<Note>
  Conversation Metrics are currently available for Voice AI conversations only. Text AI conversations show the conversation record and its disposition.
</Note>

Within either tab, use the **Agent Type** filter to separate **AI (chatbot)** conversations from **human-handled** ones.

## Using the filters

Narrow the log down to the conversations you actually care about.

**Search** by contact **name**, **phone number**, or **email**.

Click **Add filter** to see more options. You can filter by:

* **Organization**
* **Workspace**
* **Agent**
* **Agent Type** — AI (chatbot) or human
* **Date range**
* **Flagged** — show only conversations with an active, unresolved flag. See [Flagging a Call](/how-to-use-hatch/conversations/flagging-a-call).

A few filter combinations worth saving for your daily review:

* **Voice + AI + Flagged** — the calls your team has reported a problem on.
* **Voice + AI + Booking Status: Not booked** — bookable calls the agent didn't close, which is where most coaching opportunities live.
* **Voice + AI + Handling: Transferred** — calls the agent handed off, to check whether it should have handled them itself.

## Downloading your results

Use the download button in the **bottom right** of the page to export the current results as a **CSV**. Whatever filters and search terms you have applied carry over, so you can narrow the log down first and export exactly the set you want.

## Related Articles

* [Glossary](/how-to-use-hatch/conversations/glossary): what each AI-generated call metric means and how it's calculated.
* [How to Review Conversations](/how-to-use-hatch/conversations/reviewing-conversations): opening a conversation, listening to the recording, and flagging an issue.
* [Review your new AI Agent](/getting-started/hatch-assistant/review-your-new-ai-agent): where to start once a new Voice or Text AI agent goes live.


# Flagging a Call (Beta)
Source: https://docs.usehatchapp.com/how-to-use-hatch/conversations/flagging-a-call

Report an AI conversation that went wrong, and track it through to resolution.

<Note>
  Talk to your Account Manager to help get this feature set up for you.
</Note>

If an AI conversation doesn't go the way you expect, flag it right from the call. Your Hatch team sees the flag, works it, and closes it out — so you're not tracking bad calls in a spreadsheet or waiting on an email thread to find out whether anything happened.

Flagging is the right tool for problems with the agent itself: a conversational flow that went wrong, poor voice quality, the agent ignoring its instructions, or a scheduler or integration error that stopped a lead being booked.

## Where you can flag a call

There are three places to raise a flag, and they all do the same thing:

1. **From the Conversations page** — click any AI conversation, then flag it from the side drawer.
2. **From the Contact Record** — open the Conversations drawer on the contact card and flag any AI conversation there.
3. **While listening to a recording** — flag directly from the recording view, whether you opened it from the Contact Record or the Conversations page.

## Raising the flag

Flagging asks for one thing: a **note** describing what went wrong. It's required and free text, so be specific — the note is what your Hatch team uses to diagnose the problem. "Agent offered a Saturday slot we don't service" is far more actionable than "bad call."

On submit, the conversation is marked **Flagged**, and the flag is recorded with your name and the time you raised it.

<Note>
  Flags can't be edited after they're submitted. If you need to add something, raise a new flag on the same conversation or tell your Hatch account team.
</Note>

## Finding your flagged conversations

**Flagged** is a filter on the [Conversations page](/how-to-use-hatch/conversations/conversations). Apply it to see only conversations with an active, unresolved flag — which makes it a natural review queue.

This works well as a group exercise: flag calls across the week, then sit down with your Hatch team and work through the filtered list together, rather than trading links one at a time.

## Getting notified about new flags

<Note>
  Flag notifications are currently in beta and need to be switched on for your organization and for each person being notified. Ask your Hatch account team to enable it.
</Note>

Once enabled, notifications are set up through **Automations** in the left-hand sidebar:

<Steps>
  <Step title="Create a new automation">
    Go to **Automations**, then click **+ New Automation**.
  </Step>

  <Step title="Set the trigger">
    Set the trigger to **AI Conversation Flagged**.
  </Step>

  <Step title="Set the action">
    Set the action to **Send Notification**, and choose who to notify. Email notifications require the recipient to be a user of that organization.
  </Step>
</Steps>

## What happens after you flag something

Your Hatch account team picks the flag up, works it, and closes it out. Each flag carries a status through to resolution, so issues don't disappear into an inbox.

A few things worth knowing about how this works today:

* **You aren't notified automatically when a flag is resolved.** Your account team will close the loop with you directly.
* **Resolving flags is currently an internal action.** You can't mark your own flag resolved yet.
* **You can't tag a specific moment in the transcript.** Describe the moment in the note instead.
* **Flags aren't support tickets.** They route to your Hatch account team, not to Support, and there's no SLA attached.

<Tip>
  Flagging is most valuable during onboarding and pilots, when your agent is still being tuned. Reviewing calls and flagging the ones that miss is the fastest way to get your Voice AI agent behaving the way you want.
</Tip>

## Related Articles

* [How to Review Conversations](/how-to-use-hatch/conversations/reviewing-conversations): opening a conversation and reviewing the call.
* [Conversations Page](/how-to-use-hatch/conversations/conversations): finding the conversations worth reviewing.
* [Glossary](/how-to-use-hatch/conversations/glossary): what Category, Booking Status, and Handling mean.


# Glossary
Source: https://docs.usehatchapp.com/how-to-use-hatch/conversations/glossary

What every AI conversation metric means — on the Conversations page and on the Voice AI Scorecard.

Click a conversation on the [Conversations page](/how-to-use-hatch/conversations/conversations) to see all the metrics for that call.

<Note>
  You can't change which metrics show on the Conversations page at this point.
</Note>

<img alt="Conversation Metrics" />

<Note>
  These are LLM-generated metrics, which means they are not fully deterministic. Aggregate KPIs exclude irrelevant calls such as spam and no-response.
</Note>

***

## Metrics on the Conversations page

Every AI Voice call is labelled against four metrics.

<AccordionGroup>
  <Accordion title="Category">
    <p>The caller's primary intent during the call — what they actually rang up about.</p>
    <p><strong>Possible values:</strong> Schedule Service, Reschedule, Appointment Confirmation, Emergency, Technical Support, Billing Inquiry, Warranty, Cancellation, Quote Request, Transfer Request, Follow Up, Complaint, General Question, Spam, No Response, Other.</p>
  </Accordion>

  <Accordion title="Booking Status">
    <p>Whether the call should have produced a booking, and whether it did. This is a single status combining two underlying judgements: was the call <em>bookable</em>, and was it <em>booked</em>.</p>
    <p>A call is <strong>bookable</strong> when a real customer calls in with a serviceable need and intent that the agent is configured to book. Calls from disqualified callers (for example, someone who isn't the homeowner) and calls about job types the agent isn't configured for (for example, emergencies or same-day work) are <strong>not</strong> bookable.</p>
    <p><strong>Possible values:</strong></p>

    <ul>
      <li><strong>Booked</strong> — the call was bookable and the agent completed the booking.</li>
      <li><strong>Not booked</strong> — the call was bookable, but no booking was made. These are your missed opportunities, and the most useful calls to review.</li>
      <li><strong>Not bookable</strong> — the call was never bookable in the first place, so no booking was expected. Nothing went wrong here.</li>
    </ul>

    <p>If a <a href="/getting-started/hatch-assistant/commands-calendar">calendar</a> is not set up, "Booked" is based on the agent's ability to confirm an appointment with the caller rather than on a real calendar write.</p>
  </Accordion>

  <Accordion title="Handling">
    <p>Whether your Voice AI agent handled the call on its own, handed it off, or never got the chance.</p>
    <p><strong>Possible values:</strong></p>

    <ul>
      <li><strong>Contained</strong> — the agent handled the call independently, start to finish.</li>
      <li><strong>Transferred</strong> — the agent passed the call to a person or an external number. See <a href="/getting-started/hatch-assistant/voice-at-live-transfers">Live Transfers</a>.</li>
      <li><strong>Abandoned</strong> — the contact ended the call before it reached a resolution.</li>
    </ul>
  </Accordion>

  <Accordion title="Disposition">
    <p>The outcome label applied when the conversation closed. For an AI agent, this is simply the disposition configured on the <code>/end</code> commands in that bot's instructions — so the values you see here are the ones your team set up.</p>
    <p>See <a href="/how-to-use-hatch/board-contact-card/dispositions-in-hatch">Dispositions in Hatch</a> for how to manage the list, and <a href="/how-to-use-hatch/reporting-settings/configuring-dispositions">Configuring Dispositions</a> for reporting settings.</p>
  </Accordion>
</AccordionGroup>

***

## Scorecard metrics

These metrics appear on the [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard) rather than on the Conversations page. They go a level deeper — explaining *why* a bookable call didn't book, and *where* in the call a handoff or hang-up happened.

<AccordionGroup>
  <Accordion title="Not Booked Reason">
    <p>Why the agent didn't book a call that was bookable. Hatch analyses every bookable call that didn't result in a booking and groups them by reason, so you can see what's actually costing you bookings rather than inferring it from a conversion rate.</p>
    <p><strong>Possible values:</strong></p>

    <ul>
      <li><strong>No Availability</strong> — the agent didn't return any relevant times.</li>
      <li><strong>Declined Availability</strong> — the caller rejected the availability the agent offered.</li>
      <li><strong>Pricing</strong> — fees, or an issue with pricing.</li>
      <li><strong>Human Requested</strong> — the caller asked for a human in the middle of being booked by the agent.</li>
      <li><strong>Customer Gave Up</strong> — the caller abandoned the call and hung up.</li>
      <li><strong>Tool Error</strong> — the agent hit a tool error (a lookup, the scheduler, and so on) that stopped the lead booking.</li>
      <li><strong>Other</strong></li>
    </ul>
  </Accordion>

  <Accordion title="Handling Stage">
    <p>Where in the call a handoff or an abandonment happened — how far the conversation got before it stopped.</p>
    <p><strong>Possible values, in the order a call moves through them:</strong></p>

    <ol>
      <li><strong>Intake</strong> — the opening of the call, before anything has been established.</li>
      <li><strong>Contact Confirmation</strong> — confirming who the caller is and their details.</li>
      <li><strong>Issue Qualification</strong> — working out what the caller needs and whether it's something the agent can serve.</li>
      <li><strong>Task Resolution</strong> — handling a request that isn't a booking.</li>
      <li><strong>Scheduling</strong> — finding and confirming an appointment time.</li>
      <li><strong>Completed</strong> — the call reached its end state.</li>
    </ol>

    <p><strong>Task Resolution</strong> and <strong>Scheduling</strong> are mutually exclusive — a call goes down one branch or the other after Issue Qualification, never both. So a call that handed off at <strong>Issue Qualification</strong> never progressed to either.</p>
  </Accordion>

  <Accordion title="Handoff Classification">
    <p>Why the call was transferred, and whether that handoff was working as intended or points at a gap in the agent's setup.</p>
    <p><strong>Possible values:</strong></p>

    <ul>
      <li><strong>Escalated</strong> — the caller specifically asked for a human part-way through working with the agent.</li>
      <li><strong>Qualified</strong> — the agent passed the lead off properly, exactly as configured. These calls are usually not bookable.</li>
      <li><strong>Requested</strong> — the caller asked for someone at the very start of the call.</li>
      <li><strong>No Handoff</strong> — there was no handoff.</li>
    </ul>

    <p>Read this alongside <strong>Handling Stage</strong>. An agent configured to hand leads off will show a <strong>Qualified</strong> handoff at the <strong>Issue Qualification</strong> stage — that's the system working as intended, not a failure.</p>
  </Accordion>
</AccordionGroup>

***

## Rates

Two aggregate rates roll up from the metrics above and are the quickest read on how an agent is performing.

<AccordionGroup>
  <Accordion title="Bookable to Booked">
    The percentage of bookable calls where the agent successfully completed a booking. This is the headline performance number for an inbound booking agent, because it ignores the calls that were never bookable and measures only the ones the agent was configured to win.
  </Accordion>

  <Accordion title="Containment">
    The percentage of calls the agent saw through on its own. A call is **not** contained if it was **transferred** or **abandoned**, so containment is everything left over once those two are taken out — it's the share of calls with a **Handling** value of Contained. A falling containment rate usually means the agent is hitting questions or job types it isn't configured for, or that callers are hanging up mid-conversation.
  </Accordion>
</AccordionGroup>

***

## Related Articles

* [Conversations Page](/how-to-use-hatch/conversations/conversations): where these metrics appear, and how to filter by them.
* [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard): where the Scorecard metrics live.
* [How to Review Conversations](/how-to-use-hatch/conversations/reviewing-conversations): open a call, listen to the recording, and flag an issue.


# How to Review Conversations
Source: https://docs.usehatchapp.com/how-to-use-hatch/conversations/reviewing-conversations

Open a conversation, listen to the call, jump to the contact, and flag anything that went wrong.

The [Conversations page](/how-to-use-hatch/conversations/conversations) tells you which conversations are worth a closer look. This page covers what to do once you've found one.

<CardGroup>
  <Card title="Opening a conversation" href="#opening-a-conversation">
    The side drawer — recording, transcript, summary, and Context tab.
  </Card>

  <Card title="Jumping to the Contact Record" href="#jumping-to-the-contact-record">
    See the contact's full history across every channel and agent.
  </Card>

  <Card title="Flagging a Call (Beta)" href="/how-to-use-hatch/conversations/flagging-a-call">
    Report a conversation that went wrong and track it to resolution.
  </Card>
</CardGroup>

## Opening a conversation

Click any row on the Conversations page to open it in the side drawer, without losing your place in the list.

<img alt="Open Card" />

For a **Voice** conversation, the drawer gives you:

* **The recording** — play back the call from the drawer.
* **The transcript** — read the full back-and-forth instead of listening.
* **An AI-generated summary** — a short account of what the caller wanted and what happened, so you can triage without playing anything.
* **The Context tab** — the [Conversation Metrics](/how-to-use-hatch/conversations/glossary) for that call, including Category, Booking Status, and Handling, alongside the call's key details.

For a **Text** conversation, the drawer shows the message thread and the disposition that closed it out.

## Jumping to the Contact Record

Use the arrow at the top of the drawer to open the full [Contact Record](/how-to-use-hatch/board-contact-card/contact-card-basics) for that contact.

This is where you go when the single conversation doesn't tell you enough — the Contact Record carries the contact's full history across every channel and every agent, including earlier calls and text threads.

## Flagging an issue

If a conversation didn't go the way it should, flag it with a note and your Hatch team will work it through to resolution. You can flag from the side drawer, the Contact Record, or while listening to a recording.

See [Flagging a Call](/how-to-use-hatch/conversations/flagging-a-call) for the full walkthrough, including how to find your flagged conversations and set up notifications.

## Related Articles

* [Flagging a Call (Beta)](/how-to-use-hatch/conversations/flagging-a-call): report a conversation that went wrong.
* [Conversations Page](/how-to-use-hatch/conversations/conversations): finding the conversations worth reviewing.
* [Glossary](/how-to-use-hatch/conversations/glossary): what Category, Booking Status, and Handling mean.
* [Review your new AI Agent](/getting-started/hatch-assistant/review-your-new-ai-agent): where to start with a newly launched agent.


# CSR and Agents Table
Source: https://docs.usehatchapp.com/how-to-use-hatch/dashboard/csr-and-agents-table

Every column in the AI Agents and Human Agents tables on the Dashboard.

The [Dashboard](/how-to-use-hatch/dashboard/dashboard-overview) lists everyone handling conversations in your organization across two tables — **AI Agents** and **Human Agents**. They carry different columns, because an AI agent and a CSR are judged on different things.

<img alt="Dashboard" />

<Tip>
  Most columns have an ⓘ tooltip in the app. Hover a column header for a quick definition without leaving the page.
</Tip>

## AI Agents

| Column                             | What it means                                                                                                                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Type**                           | The kind of agent — for example a Voice or Text agent.                                                                                                                                                                             |
| **Conversations**                  | How many conversations the agent handled in the selected period.                                                                                                                                                                   |
| **Success**                        | The percentage of those conversations that closed with a disposition you've marked as successful. See [Configuring Dispositions](/how-to-use-hatch/reporting-settings/configuring-dispositions).                                   |
| **Avg. Duration**                  | How long a typical conversation ran. **Median**, not mean.                                                                                                                                                                         |
| **Bookable to Booked**             | The percentage of **bookable** calls the agent booked — the headline conversion number, since it ignores calls that were never bookable. **AI agents only.** See [Conversation Metrics](/how-to-use-hatch/conversations/glossary). |
| **Containment**                    | How much the agent saw through on its own. On **voice**, the percentage of calls that were neither **transferred** nor **abandoned**. On **text**, the percentage of conversations a human user took over.                         |
| **Trigger**                        | What starts the agent — for example an inbound call to a workspace, or a response to a campaign.                                                                                                                                   |
| **Appointments · Sales · Revenue** | The outcomes attributed to that agent's conversations.                                                                                                                                                                             |

## Human Agents

A CSR may work both channels, so the middle of this table splits into **Voice** and **Text** groups.

| Column                             | Channel | What it means                                                                      |
| ---------------------------------- | ------- | ---------------------------------------------------------------------------------- |
| **Conversations**                  | Both    | Total conversations handled across both channels.                                  |
| **Calls**                          | Voice   | How many calls the CSR took.                                                       |
| **Avg. Duration**                  | Voice   | **Median** call length.                                                            |
| **Avg. Score**                     | Voice   | The average score across the CSR's calls.                                          |
| **Conv.**                          | Text    | How many text conversations the CSR handled.                                       |
| **Avg. Duration**                  | Text    | **Median** length of a text conversation.                                          |
| **Resp. Time**                     | Text    | How quickly the CSR sent the **first response to a new campaign lead**. Text only. |
| **Appointments · Sales · Revenue** | Both    | The outcomes attributed to that CSR's conversations.                               |

## How metrics are calculated

**Success** is based on the **dispositions** applied at the end of each conversation. You mark specific dispositions as successful, and Hatch uses that configuration to calculate every success-related metric on both tables. Set this under [Settings → Dispositions](/how-to-use-hatch/reporting-settings/configuring-dispositions).

<Note>
  If your success numbers look low or empty, check your disposition configuration first. A conversation that was never closed out with a disposition can't be counted as a success. See [Dispositions in Hatch](/how-to-use-hatch/board-contact-card/dispositions-in-hatch).
</Note>

**Duration and response-time** columns use the **median**, not the mean. A median tells you what a typical conversation looked like; an average would be dragged around by outliers such as a call left connected for an hour.

## Filtering

Both tables respect the Dashboard filters — **organization**, **workspace**, and **time period**. Each table also has its own **Agent** picker for jumping straight to one agent.

## Going deeper

Click any AI agent to open its [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard), or click through to the [Conversations page](/how-to-use-hatch/conversations/conversations) to read the conversations behind any number.

## Related Articles

* [Dashboard Overview](/how-to-use-hatch/dashboard/dashboard-overview): the Dashboard and how its metrics are calculated.
* [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard): per-agent Voice AI performance.
* [Glossary](/how-to-use-hatch/conversations/glossary): what makes a call bookable, and what Handling means.


# Dashboard Overview
Source: https://docs.usehatchapp.com/how-to-use-hatch/dashboard/dashboard-overview

Real-time visibility into how your AI and human agents are performing across Hatch.

The Dashboard is your control center for monitoring activity and performance across Hatch. It gives you real-time visibility into how your AI and human agents are performing across workspaces and organizations.

<img alt="Dashboard" />

## Getting there

Go to **Dashboard** in the left-hand sidebar.

## The two tables

The Dashboard lists every agent in your organization across two tables:

* **AI Agents** — your Voice and Text AI agents, with AI-specific measures such as Bookable to Booked and Containment.
* **Human Agents** — your CSRs, split into Voice and Text columns since a CSR may work both channels.

See [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table) for what every column means and how each metric is calculated.

## What you can do

* See which of your AI agents are currently turned on or off.
* Track how many conversations each agent is handling, and how much of it is landing.
* Filter by **organization**, **workspace**, or **time period**, or jump to a specific agent.
* Open the [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard) for a single Voice AI agent, using the **Scorecard** button.
* Click into any agent to view the specific conversations they have had.

Everything on the page updates in real time, so you can monitor performance as conversations happen.

## Going deeper

The Dashboard tells you *how much* and *how often*. When you need to know *why*:

* Open the [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard) for booking performance, not booked reasons, handling, and call categories on a single agent.
* Click through to the [Conversations page](/how-to-use-hatch/conversations/conversations) to read the individual conversations behind any number.

## Related Articles

* [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table): every column in both tables.
* [Voice AI Scorecard](/how-to-use-hatch/dashboard/voice-ai-scorecard): per-agent Voice AI performance.
* [Conversations Page](/how-to-use-hatch/conversations/conversations): the individual conversations behind the numbers.
* [Configuring Dispositions](/how-to-use-hatch/reporting-settings/configuring-dispositions): set which dispositions count as successful.


# Voice AI Scorecard
Source: https://docs.usehatchapp.com/how-to-use-hatch/dashboard/voice-ai-scorecard

Per-agent call performance for your Voice AI agents — booking conversion, not booked reasons, handling, and call categories.

The Voice AI Scorecard shows call performance for a **single Voice AI agent**. Where the [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table) compares every agent side by side, the Scorecard goes deep on one — showing not just how it's converting, but where it's losing calls and why.

<Card title="Glossary: every Scorecard metric defined" icon="book-open" href="/how-to-use-hatch/conversations/glossary#scorecard-metrics">
  Not Booked Reason, Handling Stage, and Handoff Classification — with every possible value and what it means.
</Card>

## Getting there

Click the **Scorecard** button on the [Dashboard](/how-to-use-hatch/dashboard/dashboard-overview) view.

You'll see the Scorecard for any agent you can already see on the Dashboard — there's no separate permission to request.

<img alt="Dashboard" />

<Note>
  The Scorecard covers **Voice AI agents** today. Support for AI Text and outbound agents is on the way.
</Note>

## What it shows

Insights update in real time as calls come in.

<AccordionGroup>
  <Accordion title="Booking performance">
    How many calls are being booked, and how many were never bookable in the first place. Separating the two matters — a low booking count is only a problem if those calls were winnable. See [Conversation Metrics](/how-to-use-hatch/conversations/glossary) for what makes a call bookable.
  </Accordion>

  <Accordion title="Not Booked Reasons">
    Hatch automatically analyses every bookable call the agent **didn't** book and groups them by reason. This is the fastest way to find out what's actually costing you bookings, rather than guessing from a conversion rate.
  </Accordion>

  <Accordion title="Handling">
    Where calls are transferring during the booking process. Use this to work out whether a handoff was a proper escalation or a gap in the agent's setup — and therefore where to put your attention next.
  </Accordion>

  <Accordion title="Call Categories">
    What callers are actually ringing about. If the category mix doesn't match what your agent is configured for, that mismatch is usually worth fixing before anything else.
  </Accordion>
</AccordionGroup>

## Drilling into the calls

Most visuals on the Scorecard drill down to the specific calls behind them. Click through from any figure to see real examples on the [Conversations page](/how-to-use-hatch/conversations/conversations), where you can play the recording, read the transcript, and check the Context tab.

<video>
  <source type="video/mp4" />
</video>

A rate on its own doesn't tell you what to change — the calls do. When you find one that went wrong, [flag it](/how-to-use-hatch/conversations/flagging-a-call) so your Hatch team can work it through to resolution.

## Metrics glossary

<Tip>
  Every metric on the Scorecard — **Not Booked Reason**, **Handling Stage**, **Handoff Classification**, and the rest — is defined value by value in the [Glossary](/how-to-use-hatch/conversations/glossary#scorecard-metrics).
</Tip>

## Questions it answers

* How is this specific agent performing?
* What's driving its bookable-to-booked conversion?
* Where are the problem areas, and what should I fix first?

## Related Articles

* [Glossary](/how-to-use-hatch/conversations/glossary#scorecard-metrics): every Scorecard metric, value by value.
* [Dashboard Overview](/how-to-use-hatch/dashboard/dashboard-overview): the Dashboard and how its metrics are calculated.
* [CSR and Agents Table](/how-to-use-hatch/dashboard/csr-and-agents-table): compare every agent side by side.
* [Review your new AI Agent](/getting-started/hatch-assistant/review-your-new-ai-agent): where to start with a newly launched agent.


# Reset Password
Source: https://docs.usehatchapp.com/how-to-use-hatch/frequently-asked-questions/reset-password



There are two ways to reset your password.

### Reset Password When Signed Out

If you are signed out of Hatch and forgot your password, follow these steps.

<Note>
  **Note** : Using Mobile Number to reset an account is only available if you have added a mobile number to your Profile Settings in Hatch. If you do not receive the text, or you aren't sure if you added a mobile number, use the **Reset with Email** instead.
</Note>

Reset with Email

1. Visit `<https://app.usehatchapp.com/password/reset>` or click **Forgot Password** from the [Login Page](https://app.usehatchapp.com/).
2. **Enter your email address** and hit **Continue**. Make sure it is the one you used to sign up with Hatch.
3. Check your email inbox for a new message from Hatch. Copy the 6 digit code, and head back to Hatch.
4. Enter the 6 digit verification code\*\*\*\* and click **Continue.**
5. Create and Confirm a new password and click**Submit**.
6. You will see a confirmation screen. Click **Continue to Login** , and log in using your email and your newly set password.

Reset with Mobile Number

1. Visit` <https://app.usehatchapp.com/password/reset>` or click **Forgot Password** from the [Login Page](https://app.usehatchapp.com/).
2. Check the box that says **Send Code to my phone number.**
3. Check your text message for your verification code.
4. Enter the 6 digit verification code and click **Continue**.
5. Create and Confirm a new password and click**Submit**.
6. You will see a confirmation screen. Click **Continue to Login** , and log in using your email and your newly set password.

### Reset Password When Signed In

If you are signed into Hatch and want to Reset your password, follow these steps.

1. Navigate to your [Profile Settings](https://app.usehatchapp.com/users/00000763/settings/profile) in Hatch.

![profilesettings.png](https://help.usehatchapp.com/hc/article_attachments/360059848872/profilesettings.png)

*Click on your profile icon to access Profile Settings.*

2. Under General, you will see the option to **Change Password**.

![changepassword.png](https://help.usehatchapp.com/hc/article_attachments/360060015791/changepassword.png)

*Change password can be found under the General Section in Profile Settings.*

3. Create and Confirm a new password and click**Save**.
4. The next time you go to login, use your email and your newly set password.


# 'The message From/To pair violates a blacklist rule' when sending messages
Source: https://docs.usehatchapp.com/how-to-use-hatch/frequently-asked-questions/the-message-from-to-pair-violates-a-blacklist-rule-when-sending-messages



ssage From/To pair violates a blacklist rule" when sending messages

Have you ever tried to send a message in Hatch and received this error “Error sending message: the message from/to pair violates a blacklist rule”?

Through our text service provider, Twilio, contacts are automatically unsubscribed from receiving any additional messages when they send the following:

* STOP
* STOPALL
* UNSUBSCRIBE
* CANCEL
* END
* QUIT

When you go to send a message in Hatch if they have sent any of these terms, the message will fail to send and you will receive the error.

“Error sending message: the message from/to pair violates a blacklist rule”.

If you ever receive this error, go ahead and **opt them out** of Hatch.

### How to Opt Out

1. From inside the contact card, click the **ellipsis** (three dots) next to the contact's name.
2. Click **Opt out.**
3. **Confirm** you would like to opt them out.

At this time, we can not change the terms that trigger the unsubscribe. To learn more about our service with Twilio, [click here](https://help.twilio.com/articles/223133627-Error-21610-The-message-From-To-pair-violates-when-sending-SMS).


# Legacy Reporting FAQ
Source: https://docs.usehatchapp.com/how-to-use-hatch/legacy-reporting/legacy-reporting-faq

Permissions, blank reports, attribution, and response time calculations.

Common questions about [Legacy Reporting](/getting-started/reporting/legacy-reporting).

<AccordionGroup>
  <Accordion title="Why can I see a report but another user can't?">
    Users may only see reports for organizations they have permission to access. If a user has access to multiple Hatch organizations, they'll have the option to apply a filter to view the data of the organizations they're interested in.
  </Accordion>

  <Accordion title="Why are certain areas of my reports displayed as blank or &#x22;null&#x22;?">
    Blank reporting sections indicate a lack of results. Two scenarios are likely:

    <ul>
      <li>
        <b>Filters have been applied that narrow results to no values.</b> Remove any selected filters and expand the date range to test whether filters are the cause.
      </li>

      <li>
        <b>Hatch still needs to be configured with the CRM field names that indicate sales and appointment values.</b> See <a href="/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports#before-these-reports-will-populate">Before these reports will populate</a> for what your Account Manager needs from you.
      </li>
    </ul>
  </Accordion>

  <Accordion title="What is the difference between &#x22;Sales/Appointments from Hatch&#x22; and &#x22;Total Sales/Appointments&#x22;?">
    Total figures reflect **all** sales or appointments in your CRM within the given filter parameters. Attributed figures are only those Hatch communication can be shown to have driven.

    See [Attributed vs. total](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports#attributed-vs-total) for the exact criteria.
  </Accordion>

  <Accordion title="How is &#x22;first response time&#x22; calculated?">
    First response time is how fast a user responds to a contact after that contact responds to a campaign. It runs continuously — it doesn't pause around business hours — and replies over 60 hours are excluded as outliers.

    See [How first response time is calculated](/how-to-use-hatch/legacy-reporting/user-and-trend-reports#users) for the full detail.
  </Accordion>

  <Accordion title="Have questions?">
    If you have any questions about your reporting, <a href="https://www.usehatchapp.com/contact-me">click here to have your Account Manager reach out to you</a>.
  </Accordion>
</AccordionGroup>

## Related Articles

* [Sales and Appointments Reports](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports)
* [Messaging and Campaign Reports](/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports)
* [User and Trend Reports](/how-to-use-hatch/legacy-reporting/user-and-trend-reports)
* [Attribution Settings](/how-to-use-hatch/reporting-settings/attribution-settings)


# Messaging and Campaign Reports
Source: https://docs.usehatchapp.com/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports

Message volume by channel, campaign response rates, and opt-out tracking.

These dashboards in [Legacy Reporting](/getting-started/reporting/legacy-reporting) cover the activity your campaigns generate: how many messages moved in each direction, how many contacts replied, and how many opted out.

## Messaging

This dashboard displays metrics for every communication type — SMS, emails, voice calls, and voicemails. Totals are divided into **inbound** (a person → Hatch) and **outbound** (Hatch → a person).

* **Total Calls — Outbound**: calls sent to a contact by campaign automation
* **Total Calls — Inbound**: calls received by Hatch as a result of the campaign
* **Total Emails — Outbound**: emails sent to a contact by campaign automation
* **Total Emails — Inbound**: emails received by Hatch as a result of the campaign
* **Total Texts — Outbound**: SMS messages sent to a contact by campaign automation
* **Total Texts — Inbound**: SMS messages received by Hatch as a result of the campaign
* **Total Voicemails — Outbound**: voicemail drops sent to a contact by campaign automation
* **Total Voicemails — Inbound**: voicemails received by Hatch as a result of the campaign

**Common questions answered by messaging reports:**

* How much inbound activity does Hatch generate?
* What communication methods do our customers prefer?

## Campaigns

Use this dashboard to analyze the performance of specific campaigns — how many contacts entered and completed a campaign, and what proportion responded.

* **Contacts Launched**: the count of unique contacts launched into the campaign.
* **Contacts Responded**: the count of unique contacts that responded to a message from the campaign. A contact counts if they were launched into that campaign *and* responded while in it.
* **Response Rate**: the percentage of launched contacts that also responded.
  * `(Contacts Responded / Contacts Launched) * 100`

**Common questions answered by campaign reports:**

* How many contacts are in each stage of campaign communication?
* Which campaigns generate the most responses, or the best response rate?
* Can we learn from the language being used in these high-performing campaigns?

## Opt-Outs

This dashboard shows the count and proportion of contacts opting out in response to campaign communication.

* **Opt-Out Rate**: the percentage of contacts responding to an outbound message with a mandatory opt-out word (End, unsubscribe, stop).
  * `(Inbound Opt-Outs / Outbound Messages) * 100`
* **Carrier Limit**: carriers set requirements for businesses sending promotional language. If your opt-out percentage exceeds a given threshold of overall messages, you risk being labelled as spam or blocked from further messaging.

**Common questions answered by opt-out reports:**

* Which of our campaigns are more prone to opt-out responses?
* What are the targeting criteria or verbiage for each of these campaign types?

<Warning>
  Opt-out rate is the metric most likely to cost you deliverability. Watch it per campaign rather than only in aggregate — a single aggressive campaign can drag an otherwise healthy account toward the carrier limit.
</Warning>

## Related Articles

* [Sales and Appointments Reports](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports): attributed sales and bookings.
* [User and Trend Reports](/how-to-use-hatch/legacy-reporting/user-and-trend-reports): response times, month-over-month trends, and the funnel.
* [Hatch Delivery Status](/getting-started/messaging/hatch-delivery-status): what happens to a message after it's sent.
* [Legacy Reporting FAQ](/how-to-use-hatch/legacy-reporting/legacy-reporting-faq): permissions, blank reports, and common questions.


# Sales and Appointments Reports
Source: https://docs.usehatchapp.com/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports

Analyze the sales and appointments in your CRM, and see which were driven by Hatch.

The Sales and Appointments dashboards in [Legacy Reporting](/getting-started/reporting/legacy-reporting) show the revenue and bookings sitting in your CRM, and separate out the portion Hatch communication is responsible for.

## Sales

Use this dashboard to analyze the **count** and **total value** of sales within your organization's CRM.

* A sale is **attributed** to Hatch communication if it meets specific criteria for campaign timing (see [Attributed vs. total](#attributed-vs-total) below).
* A sale is included in **overall sale totals** if it is reflected as a sale in the CRM within the given filter parameters.

You can examine sale patterns by **campaign**, **workspace**, and **data source**, and download a full list of attributed sales in a variety of formats for further analysis.

**Common questions answered by sales reports:**

* What campaigns are providing the best ROI?
* What lead sources are resulting in sales?
* Which sales reps are emerging as top performers?

## Appointments

Use this dashboard to analyze the **count** of appointments within your organization's CRM.

* A booked appointment is **attributed** to Hatch communication if it meets specific criteria for campaign timing.
* An appointment is included in **overall appointment totals** if it is reflected in the CRM within the given filter parameters.

You can examine scheduled appointments by **campaign**, **workspace**, and **data source**, and download a full list of attributed appointments for further analysis.

**Common questions answered by appointment reports:**

* What campaigns are resulting in the most scheduled appointments?
* What lead sources result in customers booking an appointment?

## Attributed vs. total

Total sale and appointment figures reflect **all** sales or appointments in your CRM within the given filter parameters. The attributed figures are narrower — they're the ones Hatch can demonstrate it drove.

<AccordionGroup>
  <Accordion title="A sale is attributed to Hatch communication if:">
    <ul>
      <li>The contact was launched into the particular campaign</li>
      <li>The contact has one or more sales</li>

      <li>
        One of the sales on the contact was created:

        <ul>
          <li>After a message was sent from the particular campaign</li>
          <li>Before a message was sent from any other campaign</li>
          <li>Within 365 days of the message from the particular campaign</li>
        </ul>
      </li>
    </ul>
  </Accordion>

  <Accordion title="An appointment is attributed to Hatch communication if:">
    <ul>
      <li>The contact was launched into the particular campaign</li>
      <li>The contact has one or more appointments</li>

      <li>
        One of the appointments on the contact was created:

        <ul>
          <li>After a message was sent from the particular campaign</li>
          <li>Before a message was sent from any other campaign</li>
          <li>Within 365 days of the message from the particular campaign</li>
        </ul>
      </li>
    </ul>
  </Accordion>
</AccordionGroup>

## Before these reports will populate

Sales and appointments are recorded based on fields and values inside **your** CRM, so Hatch needs to know which fields to read. If these dashboards are blank, that configuration is usually the reason.

See [Attribution Settings](/how-to-use-hatch/reporting-settings/attribution-settings) to set the fields, and work with your Account Manager to confirm:

* The field names and values that indicate the date a sale is made, and the statuses that indicate a sale
* The field names and values that indicate the date an appointment is set, and the statuses that indicate a scheduled appointment

Changes are processed nightly and populate at the start of the following day.

## Related Articles

* [Messaging and Campaign Reports](/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports): message volume, response rates, and opt-outs.
* [User and Trend Reports](/how-to-use-hatch/legacy-reporting/user-and-trend-reports): response times, month-over-month trends, and the funnel.
* [Attribution Settings](/how-to-use-hatch/reporting-settings/attribution-settings): map your CRM fields so these reports populate.
* [Legacy Reporting FAQ](/how-to-use-hatch/legacy-reporting/legacy-reporting-faq): permissions, blank reports, and common questions.


# User and Trend Reports
Source: https://docs.usehatchapp.com/how-to-use-hatch/legacy-reporting/user-and-trend-reports

First response times by user, month-over-month trends, and the contact funnel.

These dashboards in [Legacy Reporting](/getting-started/reporting/legacy-reporting) cover how quickly your team responds, how your metrics are moving over time, and where contacts drop out of the journey.

## Users

Use this dashboard to analyze average **first response times** across communication types, Hatch users, campaign types, and workspaces. Metrics include the number of first responses by communication method, average first response time by user, and response times for each campaign and workspace.

* **First Response Time**: how fast a user responds to a contact after that contact responds to a campaign.

<Accordion title="How first response time is calculated">
  A contact is put into a campaign, then responds to it and pops onto the board. The reply time clock starts. It stops when the **user** replies back to that contact for the first time after a campaign response.

  Reply time is **continuous** — it does not pause and resume around business hours. Replies exceeding **60 hours** are excluded from calculations, to avoid outliers that would inflate the average.
</Accordion>

**Common questions answered by user reports:**

* Which Hatch users are responding to contacts most quickly?
* Which campaigns require the highest volume of responses, and how might that affect which messages users prioritize?

## Month-over-Month

This dashboard contains trend data and monthly comparisons for the core metrics:

* Total Sales
* Total Appointments
* Total Messages and Message Types
* Campaign Response Rates
* Total Campaign Launches and Replies
* Opt-Out Rates
* First Response Times

**Common questions answered by the month-over-month report:**

* How are metrics performing over time?
* What strategies have been effective in improving these metrics monthly or quarterly?
* How have internal or external factors impacted these trends?

## Funnel

Use this dashboard to examine aggregate contact journey data, from initial contact through to final sale.

**Common questions answered by the funnel report:**

* How many contacts reach each stage of the process?
* Where can my organization improve its conversion rate?

## Related Articles

* [Sales and Appointments Reports](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports): attributed sales and bookings.
* [Messaging and Campaign Reports](/how-to-use-hatch/legacy-reporting/messaging-and-campaign-reports): message volume, response rates, and opt-outs.
* [Legacy Reporting FAQ](/how-to-use-hatch/legacy-reporting/legacy-reporting-faq): permissions, blank reports, and common questions.


# Changing or Adding your Mobile Number in Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/profile-settings/changing-or-adding-your-mobile-number-in-hatch



### Overview

You may want to change or associate your Hatch account with your mobile number for two reasons.

* Unread message notifications
* Resetting your password via sms

Associating your Hatch account with your mobile number is easy!

1\. Log in to your Hatch account and navigate to your **Profile Settings**.
![mceclip0.png](https://help.usehatchapp.com/hc/article_attachments/4422752018573/mceclip0.png)

2\. On the **General** tab, click **Update User Profile**.

![mceclip1.png](https://help.usehatchapp.com/hc/article_attachments/4422745491213/mceclip1.png)

3\. Enter your mobile number in the **Phone number field** and click **Save**.

![mceclip2.png](https://help.usehatchapp.com/hc/article_attachments/4422739680269/mceclip2.png)

4\. If successful, you should see the message “**Successfully updated profile** ”.

![mceclip3.png](https://help.usehatchapp.com/hc/article_attachments/4422739696141/mceclip3.png)

**Reminder:** If you've added your number to receive text notifications for unread messages, be sure to select the workspaces you'd like to receive them for.

![mceclip0.png](https://help.usehatchapp.com/hc/article_attachments/4423276459021/mceclip0.png)


# Notifications
Source: https://docs.usehatchapp.com/how-to-use-hatch/profile-settings/notifications

Notifications in Hatch help you track conversations across different workspaces, or send text and email reminders when you're away from your computer

#### Web notifications

Hatch's sidebar shows you when a given salesboard has an unread message, or when a call step is required for a [campaign with a call step.](/getting-started/messaging/calling-in-campaigns) Text and email notifications are blue, while phone-related notifications are green.

<img alt="" />

Besides unread messages, Hatch also has a notifications area on the sidebar, for notifications  *specific to you* , rather than all the users in a workspace. When the notifications bell is red, you have an unread notification!

Currently, you can receive three types of notifications in this area:

* *When you [set a reminder for a contact](/how-to-use-hatch/board-contact-card/contact-card-basics), and the reminder date / time is reached.*

<img alt="Screenshot 2025-05-06 at 3.37.46 PM" />

* *When another user in your workspace assigns a conversation to you*

<img alt="Screenshot 2025-05-06 at 3.27.00 PM" />

* *When a [Hatch AI Agent](/getting-started/hatch-assistant/hatch-assistant-setup-guide) assigns a conversation to you*

<img alt="Screenshot 2025-05-06 at 3.42.10 PM" />

We plan to expand web notifications to include other events in the near future—[write to the product team](mailto:product@usehatchapp.com) with any events in Hatch you'd like to receive notifications for!

#### Text and email notifications

Customers expect a quick response time when texting, and speed is a huge part of what makes Hatch a useful tool. If you're not actively working in Hatch, and want to know when there's a conversation to follow up on in one of your workspaces, you can turn on **text and email notifications**.

1. Navigate to your **Profile Settings** in Hatch.

<img alt="" />

*Click on your profile icon to access Profile Settings.*

2. Navigate to the Notifications tab, and select which boards you'd like to receive text or email notifications for
3. You can receive email and text notifications for two types of conversations: either for  *all new messages* that come into a board, or for  *conversations that are assigned to you*(either by another user, or by a bot)
   <img alt="" />
   *In this example, the user will be notified over email and text for any new messages to the Dallas salesboard, and by email and text for any conversations **assigned to them** on the Atlanta salesboard*
4. If you can't select text notifications, navigate over to the General tab and add the cell number where you'd like to receive notifications
5. Depending on your preferences, you'll receive reminders when an inbound message hits one of your boards, or a conversation is assigned to you, reminding you to hop back into Hatch!

Also on the notifications page, you'll notice you can select whether you'd like to hear a ringing sound to notify you for incoming calls to  *any* of your Hatch workspaces, or just the one in which you're currently active.


# Signing into Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/profile-settings/signing-into-hatch



Hatch has added new options to make signing in easier and more secure for your organization.

<Frame>
  <img alt="Screenshot 2026 04 13 At 7 38 40 PM" />
</Frame>

#### *Single sign-on*

Single sign-on (SSO) lets you log in to an application using an account you already have with a trusted provider (in our case, Google or Microsoft) instead of creating and remembering a separate username and password for all your software tools.                                       

**How it works:**   

1. Click "Sign in with Google" (or Microsoft)
2. You're redirected to Google/Microsoft to confirm it's really you
3. Google/Microsoft confirms that you are who you say you are
4. You're logged in — no new password needed                                                                

It's one less password to remember and manage, with login security is handled by Google/Microsoft, which have robust protections built-in.

#### *Multi-factor Authentication*                                                                                              

MFA adds a second step to the login process beyond just your password. The idea is that even if someone steals your password, they still can't get in without access to the second piece of your login.

The two supported methods are:

**Authenticator App (TOTP)** \
An app like [Google Authenticator](https://apps.apple.com/us/app/google-authenticator/id388497605), [Authy](https://www.authy.com/), or [1Password](https://1password.com/) generates a 6-digit code that refreshes every 30 seconds. After entering your password, you open the app and enter the current code to Hatch. The code is tied to your specific account and can't be reused.               

**SMS**

A one-time code is sent to your phone number via text message. After entering your password, you enter the code from the text. Codes expire after a short window and can only be used once.                                                                                                 

For now, MFA isn't required on your Hatch account, so you can skip setting it up. But for security reasons (hackers try to get into Hatch all the time!), we will be mandating MFA set-up in the near future, if you're logging in with your email and password. If you're logging in with Google or Microsoft, MFA is not required, because Google/Microsoft have already verified your identity through their own security process.

#### *Managing log-in*

You can always reset your MFA settings, reset your password, or change the phone number associated with your account on the Profile Settings page, accessible by clicking your avatar, in the bottom left corner of Hatch.

<Frame>
  <img alt="Screenshot 2026 04 13 At 7 48 06 PM" />
</Frame>

<Frame />


# Removal Rule Templates
Source: https://docs.usehatchapp.com/how-to-use-hatch/removal-rules-templates

Create and Manage Removal Rules across Multiple Workflows using Templates

<img alt="" />

[Workflows](/how-to-use-hatch/workflows/workflows-overview) are the feature in Hatch that allow automatic launching of audiences into campaigns.

Removal Rules allow you to specify a set of conditions in which Contacts should be removed from a Campaign even if they meet the audience criteria. For example, you may have an audience to target contacts with `open` estimates, but if at any point in time their estimate is updated to `sold`, you want to remove them from the campaign.

When setting Removal Rules for a workflow, you can *either* create a unique set of conditions that only apply to that Workflow, or you can apply a Template.

### Removal Rule Templates

Removal Rule Templates allow you to apply a single set of conditions across multiple workflows. This allows you to make changes to a single Template in a central location, which will apply to all workflows using that template.

For example, you may want to remove contacts from any Speed-to-Lead Campaign if the Contact has an Appointment starting in the next 7 days. You can create a Removal Rule Template called "Remove Upcoming Appointments" with a condition that checks for contacts with Appointments between 0 and 7 days in the future, and apply it to all of your Speed-to-Lead related workflows. If at any point in time you want to increase the window to remove people with appointments in the next 14 days, you only need to make that change to the template, and the updates will apply everywhere!

### Creating and Using Templates

When creating or editing a Workflow, Step 4 allows you to set Removal Rules. Once you've applied a set of conditions in the "Create from Scratch" tab, you'll see a "Save as Template" button in the top right. Once you click Save, you'll set a Name for this template and your done! This Workflow will already be using your newly created template.

<img alt="" />

The next time you create a Workflow, you can use the "Use Template" tab to see all of your templates. Choose the Template you want to use, and you'll see a preview of what conditions it contains.

<img alt="" />

### Editing a Template

Removal Rule Templates are only accessible within Workflows. To Edit a Template, you have to navigate to a Workflow using that template (or just create a New Workflow). Once you've selected the Template, you'll see an "Edit" button in the Top Right. Once you click edit, you can rename the template, add new conditions, remove conditions, or edit existing conditions. Once your done, click save.

**Important Note: These changes will apply to all Workflows using that template, instantly.**

### ![](https://www.usehatchapp.com/hs-fs/hubfs/Create%20Workflow%20_%20Any%20Conditions%20_%20Removal%20Rules%20\(5\)-png.png?width=1444\&height=933\&name=Create%20Workflow%20_%20Any%20Conditions%20_%20Removal%20Rules%20\(5\)-png.png)


# Attribution Settings
Source: https://docs.usehatchapp.com/how-to-use-hatch/reporting-settings/attribution-settings

Report on client outcomes, based on your own unique CRM setup.

Hatch looks for attribution based on a contact's integrated data. Hatch can read the full information relating to a contact/opportunity, but needs to be configured based on your own CRM's setup.

Click the gear icon in the bottom left of Hatch and go to the "Settings Page".

<img alt="Attribution settings" />

Here you can set the specific fields from your own CRM to track outcomes, dates, and statuses.

## Filling out fields

Work with your Account Manager to have these filled out. Many CRMs have duplicated fields (see image above), and need to be indexed.

* *These are fields are case and space sensitive*

## Better Attribution Reporting

Track *appointments* and *sales* for client's that have been launched into Hatch campaigns. These settings feed metrics in the [Sales and Appointments reports](/how-to-use-hatch/legacy-reporting/sales-and-appointments-reports).

Changes will be processed every night and will populate in the Attribution Tab of Reporting at the start of the day.


# Configuring Dispositions
Source: https://docs.usehatchapp.com/how-to-use-hatch/reporting-settings/configuring-dispositions

Create custom dispositions and define what counts as success.

Dispositions tell Hatch how a conversation ended. Set them up to keep reporting accurate and to define what success means for your team.

Click the gear icon in the bottom left of Hatch and go to the "Settings Page".

<img alt="Dispositions settings" />

Here you can create, delete, and manage your organization-wide dispositions.

## Mark successful outcomes

Use the **Successful** toggle to mark which dispositions represent a win. These settings feed success metrics in the [Dashboard](/how-to-use-hatch/dashboard/dashboard-overview).


# Workflows Overview
Source: https://docs.usehatchapp.com/how-to-use-hatch/workflows/workflows-overview



### Overview

Workflows are the feature in Hatch that allow automatic launching of audiences into campaigns.

Once you have an audience (who to launch) and a campaign (what you want to say to those contacts), the role of the workflow is to launch the contacts either on a specific schedule, or as soon as a contact enters Hatch and fits the criteria for that audience.

The workflow is also responsible for removing contacts from campaigns automatically if they fit certain criteria.

**Example** :

* You have a Speed to Lead campaign, but you'd like contacts to be automatically removed from that campaign once they have an appointment booked.
* You set up a workflow with a removal rule that checks for appointment status from your CRM.
* Once a contact in that campaign books an appointment, the workflow automatically removes them so they stop getting messages.

### Creating a Workflow

You can create workflows directly from the Workflows page by clicking the **Create Workflow** button. The workflow builder walks you through the following steps:

1. **Select an Audience** — Choose which audience of contacts should be launched into the campaign.
2. **Select a Campaign** — Choose which campaign those contacts will receive.
3. **Set the Frequency** — Choose how often the workflow should launch contacts:
   * **Immediately** — Launches contacts as soon as they enter the audience (available for Speed to Lead / instant campaigns).
   * **Daily** — Launches contacts once per day.
   * **Weekly** — Choose specific days of the week.
   * **Monthly** — Choose a specific day of the month.
4. **Set the Send Size** — Control how many contacts are launched per interval (up to 150 by default).
5. **Configure Removal Rules** — Define conditions for automatically removing contacts from the campaign (e.g., when an appointment is booked or a status changes in your CRM).
6. **Name your Workflow** — Give it a descriptive name for easy reference.
7. **Review and Confirm** — Review your settings and activate the workflow.

### The Workflows Page

You can get to the workflows page by clicking "Workflows" on the sidebar. Here you will find all of the workflows that exist on a specific workspace, as well as if those workflows are enabled, disabled, or have been archived. You can also see who is currently active in the campaign and contacts that have completed the campaign (clicking the *Active* or  *Completed* number will give you the list of contacts associated with the workflow).

<img alt="" />

Clicking the  *Show More* button on a workflow will allow you to see a recap of all aspects of the workflow, including:

* Campaign
* Audience
* Launch Frequency
* Conditions for Removal

#### Enabling and Disabling

If you attempt to disable a workflow that has active contacts in it, you will be given the option to either remove those active contacts from the campaign, or let the active contacts continue through the campaign. Choosing either of these options will prevent *future* launches until the workflow is enabled.

#### Other Options

By clicking the pencil icon for a specific workflow, you can edit the details of a workflow—whether that's the name of the workflow, or conditions, or swapping in new audiences or campaigns. You can also deactivate a workflow by hitting the trash can icon, which will remove all active workflow contacts from the attached campaign and prevent contacts from being launched in the future.

#### Additional Resources

Video walkthrough (old UI):

<iframe title="Workflows Overview Video Walkthrough" />

Help Center Articles: [Campaigns](/how-to-use-hatch/campaigns)

Help Center Articles: [Audiences](/how-to-use-hatch/audience-builder-v2)


# Features
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/features

Enable and manage the features available in your workspace.

Access the Features tab by going to **Workspace Configs** and clicking **Features** in the tab bar.

<Frame>
  <img alt="Features" />
</Frame>

### Voicemail Greeting

Record or upload a custom greeting that plays when a call to your workspace goes unanswered and call forwarding is not configured. See [Voicemail Greeting](/how-to-use-hatch/workspace-settings/voicemail-greeting) for details.

### Call Forwarding

Redirect all incoming calls for this workspace to another phone number. See [Call Forwarding](/how-to-use-hatch/workspace-settings/how-to-setup-call-forwarding-for-your-workspace) for details.

### Suggested Responses

Save reusable message templates your reps can insert while chatting with contacts. See [Suggested Responses](/how-to-use-hatch/board-contact-card/suggested-responses) for details.

### Call Recording

Turn on call recording by default for all human-to-human calls in this workspace. See [Recording Calls in Hatch](/how-to-use-hatch/workspace-settings/recording-calls-in-hatch) for details.


# General Settings
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/general-settings

Configure your workspace's core identity — its name, contact details, image, and timezone.

<Note>
  You must have **Manager** permissions to edit General Settings. Members with rep-level access can view these settings but cannot save changes.
</Note>

Access Workspace Configs by clicking the settings icon in your workspace navigation, then select the **General** tab.

<Frame>
  <img alt="General Settings" />
</Frame>

### Workspace Name

The name that identifies this workspace across Hatch — in the left sidebar, in notification items, and in reporting. Choose something that makes it easy for your team to know which workspace they're in (for example, the location or line of business it covers).

### Workspace Company Name

The company name associated with this workspace. This is used in certain message templates and customer-facing contexts. If left blank, Hatch will fall back to the organization name.

### Email

Each workspace has a dedicated email address used for email-based conversations. You can customize the prefix (the part before the `@`).

### Number

The dedicated phone number for this workspace. This is the number contacts will see when you call or text them from this workspace. The number is assigned during workspace setup and is read-only — contact support if you need it changed.

### Hatch Chat Image

Upload an image to represent this workspace in the [Hatch Chat](https://docs.usehatchapp.com/integrations/lead-sources/hatch-chat-overview#hatch-chat-overview-2) widget. Click **Change Image** to upload a new one, or the trash icon to remove the current image.

### Workspace Initial

A short label (up to 5 characters) displayed on the workspace button in the left sidebar. This is what you'll see on the square button you click to navigate to this workspace. It is automatically uppercased.

### Time Zone

Sets the timezone for this workspace. Campaigns and scheduled messages will go out at the times you configure, interpreted in this timezone. Make sure this matches the timezone where your team and contacts are located.

After making any changes, click **Save**. To discard your edits, click **Cancel**.

### Business Hours

Set the days and times your workspace is open, and configure an automatic SMS reply for contacts who reach out outside those hours. See [Workspace-Level Business Hours](/how-to-use-hatch/business-hours-features/workspace-level-business-hours) for details.


# Call Forwarding
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/how-to-setup-call-forwarding-for-your-workspace

Redirect all incoming calls for a workspace to another phone number — useful if your team uses a call center or a dedicated office line.

Each workspace in Hatch has a dedicated phone number. Call forwarding lets you route all inbound calls for that workspace to a different number, so you never miss a call even if your team isn't actively monitoring Hatch.

### Setting up call forwarding

1. Go to **Workspace Configs** and click the **Features** tab.
2. Find the **Call Forwarding** card.
3. Enter the phone number you want calls forwarded to.
4. Click **Save**.

Once saved, the Call Forwarding card will show as enabled and all calls coming into this workspace will be redirected to that number.

<Frame>
  <img alt="Call Forwarding" />
</Frame>

### Removing call forwarding

To turn off call forwarding, click the trash icon next to the saved number. Calls will return to ringing in Hatch as normal.


# Overview
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/overview

Configure your workspace's name, hours, features, and team from Workspace Configs.

Access Workspace Configs by clicking the settings icon in your workspace navigation. Settings are organized into three tabs — General, Features, and Team.

<CardGroup>
  <Card title="General Settings" href="/how-to-use-hatch/workspace-settings/general-settings">
    Name, company name, email, phone number, workspace image, initials, and timezone.
  </Card>

  <Card title="Business Hours" href="/how-to-use-hatch/business-hours-features/workspace-level-business-hours">
    Set open hours per day and configure an automatic after-hours SMS reply.
  </Card>

  <Card title="Voicemail Greeting" href="/how-to-use-hatch/workspace-settings/voicemail-greeting">
    Record or upload a custom greeting for unanswered calls.
  </Card>

  <Card title="Call Forwarding" href="/how-to-use-hatch/workspace-settings/how-to-setup-call-forwarding-for-your-workspace">
    Redirect incoming calls to another phone number.
  </Card>

  <Card title="Suggested Responses" href="/how-to-use-hatch/board-contact-card/suggested-responses">
    Save reusable message templates your reps can insert while chatting with contacts.
  </Card>

  <Card title="Recording Calls" href="/how-to-use-hatch/workspace-settings/recording-calls-in-hatch">
    Turn on call recording by default for all human-to-human calls in this workspace.
  </Card>

  <Card title="Team" href="/how-to-use-hatch/workspace-settings/team">
    View team members and their notification settings for this workspace.
  </Card>
</CardGroup>


# Recording calls in Hatch
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/recording-calls-in-hatch



Recording your calls gives you a reliable reference you can go back to anytime — no more scrambling to remember what was said or relying on hastily scribbled notes. It makes it easy to review conversations for training, go back to listen for details like street addresses, resolve disputes with confidence, and ensure your team stays compliant with company and regulatory standards.

You can record all calls that take place in Hatch, here's how:

### Recording disclosures

State-level regulations on call recording differ between locations, so you may want to ensure call recording is disclosed before you or an AI agent start speaking to a contact. Go to the 'compliance' tab of your organization's settings page to switch on recording disclosure for all your workspaces. With this setting switched on, Hatch will play a short pre-recorded message before all inbound calls that informs them the call may be recorded for quality assurance purposes.

<Frame>
  <img alt="Screenshot 2026 04 22 At 11 29 10 AM" />
</Frame>

### Recording human-to-human calls

All voice AI calls in Hatch are recorded: the agent relies on a live recording to determine what a given contact is saying.

For human-to-human calls, Hatch gives you control over when and whether a given call is being recorded. When the 'REC' button is red on the calling toolbar, the call is being recorded, clicking the button at any time will start recording. Clicking the button again pauses recording—you may want to do this in cases where a customer is sharing sensitive information, like a credit card number. Clicking again restarts the recording.

<Frame>
  <img alt="Screenshot 2026 04 22 At 11 39 12 AM" />
</Frame>

You don't need to click this button constantly! Going to 'workspace configs' and switching recording on by default will start recording all your human-to-human calls as soon as they start.

<Frame>
  <img alt="Screenshot 2026 04 22 At 11 33 09 AM" />
</Frame>

Once an AI voice or human-to-human call is complete, you can navigate to the right hand side of the contact card to listen back to the recording, and read the transcript (if applicable)

<Frame>
  <img alt="Screenshot 2026 04 22 At 11 47 43 AM" />
</Frame>

Happy calling!


# Team
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/team

View your workspace's team members and their notification settings at a glance.

The **Team** tab in Workspace Configs shows everyone who has access to this workspace, along with a summary of their notification preferences.

### What you'll see

The team table lists each member with three columns:

* **Name** — the member's full name and email address.
* **Email** — whether they have email notifications enabled for this workspace.
* **Text** — whether they have SMS notifications enabled for this workspace.

The indicators show each person's current state — this is a read-only view in Workspace Configs.

<Frame>
  <img alt="Team" />
</Frame>

### Changing notification settings

Notification settings are personal — each team member controls their own. To update your own settings, click the **profile** link in the Team tab description, or go to your profile and open the **Notifications** section. From there you can turn email and text notifications on or off per workspace.

### Adding or removing members

Team membership is managed from **Account Settings**, not Workspace Configs. To add or remove a user from this workspace, see [Add or Remove a Member from a Workspace](/how-to-use-hatch/account-settings/add-or-remove-member-from-workspace).


# Voicemail Greeting
Source: https://docs.usehatchapp.com/how-to-use-hatch/workspace-settings/voicemail-greeting

Record or upload a custom voicemail greeting that plays when a call to your workspace goes unanswered.

When a contact calls your workspace's phone number and no one answers — and call forwarding is not configured — Hatch plays your voicemail greeting and records a message from the contact. Setting a custom greeting makes the experience feel more professional and on-brand.

### Setting up your voicemail greeting

1. Go to **Workspace Configs** and click the **Features** tab.
2. Find the **Voicemail Greeting** card.
3. Record a new greeting directly in the browser, or upload an audio file.
4. Click **Save** to apply it.

Once saved, the Voicemail Greeting card will show as enabled, confirming your greeting is active.

<Frame>
  <img alt="Voicemail Greeting" />
</Frame>

### Removing a greeting

To remove your voicemail greeting and revert to the default, click the trash icon on the Voicemail Greeting card and confirm. Contacts who call after removal will hear the default Hatch voicemail prompt.


# Hover Integration
Source: https://docs.usehatchapp.com/integrations/contractor-tools/hover-integration



### Overview

The Hover integration allows you to add a Hover capture link to any Hatch campaign message. The Hover link will be unique for each customer that receives the Hatch campaign message.

* If the customer has an existing link in your Hover account, that is the one they will be sent
* If the customer does not have an existing Hover link, one will be generated for them and sent to them

<img alt="" />

When the customer receives the link, they will be prompted to download the Hover app and provide pictures of their home so a 3D model can be created.

<img alt="" />

Since the contacts are in Hatch, you can contact those folks at any time to follow up (or automate the follow-up with your campaign sequence!)

In your Hover account, you will see a new job created for this contact:

<img alt="" />

### Activating the Hover-Hatch Integration

1. Navigate to the Hatch app marketplace
2. Click connect on the Hover integration (can be found under *Other Tools*)
3. Click the connect button, and sign in to your Hover account

<img alt="" />

4\. Once that's completed, return to the Hatch integration screen. The connection bubble will turn blue once connected successfully. Click Finish to save.

### How to add the Hover link to Hatch campaign messaging

1. Navigate to the Campaigns page.

2. Find the campaign you’d like to add the link to, select the three dots icon, and select Edit from the menu that appears.<img alt="" />

3. In the campaign verbiage, wherever you’d like the Hover URL to appear, place  *exactly* this:

> \[\[hover\_capture\_url]]

<img alt="" />*This is how the snippets appear in campaign verbiage. For the contact that receives the message, this snippet will be transformed into their unique Hover link*

4. Once you’re done editing, click  *Update Campaign*.


# AccuLynx
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/acculynx-integration

What is Hatch's AccuLynx integration, how it works, and where to begin.

### What does the AccuLynx integration do?

Hatch offers a native integration with [AccuLynx](https://acculynx.com/) that you can activate within the App Marketplace (located in your Hatch workspace). This integration syncs contact data from AccuLynx to Hatch. While active, the integration will sync new and updated AccuLynx data every **15 minutes.**

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

### How do you set up the integration?

#### Requirements

You will need the following to set up the integration:

* Hatch account with Manager privileges
* AccuLynx account with location administrator *or* company administrator privileges

#### Setup Steps

The following is the set of steps required to activate the integration:

1. In Hatch, open the **App Marketplace** and head to the **Apps** tab.
2. Using the CRMs filter, click the AccuLynx **Connect** button.
3. In the window that appears, click the **Start Setup** button.
4. Follow the steps of the setup, clicking the **Next** button after each screen is completed.
   1. The necessary API key can be generated in AccuLynx: Account Settings > Add-ons and Integrations > API Keys
5. In the final screen of the setup, click the **Finish** button.
6. If successfully activated, a 90 day back-sync of your AccuLynx data will automatically initiate.

<img alt="Screenshot 2024-03-05 190039" />

#### Suggested Implementation

A given AccuLynx account may contain multiple individual locations, which largely operate independently. Separate API keys will need to be generated for API access to each individual location. As a result, **individual Hatch integrations will need to be instantiated for each AccuLynx location, as the integration only accepts a single API key.**

The suggested approach in this case is to *mirror the AccuLynx environment* : set up separate Departments within the Hatch Org for each AccuLynx location. Hatch departments each have their own separate set of contact data and their own integrations, which is akin to how their data operates in AccuLynx (contacts are not shared amongst locations).

![Untitled (4)](https://www.usehatchapp.com/hs-fs/hubfs/Untitled%20\(4\).png?width=503\&height=440\&name=Untitled%20\(4\).png)

### What AccuLynx data is available in Hatch?

#### When is a Hatch opportunity created or updated?

A new or updated Hatch opportunity will be created when an AccuLynx `Job` is created or modified. The integration does not capture stand-alone AccuLynx `Contacts` or `Leads`.

#### Standard field mapping

The Hatch standard Contact fields are mapped from the AccuLynx Detail fields as specified below.

<Note>
  Note that the base object of the Hatch opportunity model is the AccuLynx `job`. Therefore, (as an example) the Id field below would indicate the ID of the AccuLynx job record.
</Note>

| **Hatch Standard Field** | **AccuLynx Detail Field**          |
| ------------------------ | ---------------------------------- |
| `Email`                  | `Contact:JobContacts:1:Email1`     |
| `External ID`            | `Id`                               |
| `External Contact ID`    | `Contact:JobContacts:1:ContactID`  |
| `External Created At`    | `CreatedDate`                      |
| `External Updated At`    | `LastTouched`                      |
| `First Name`             | `Contact:JobContacts:1:FirstName`  |
| `Last Name`              | `Contact:JobContacts:1:LastName`   |
| `Phone Number`           | `Contact:JobContacts:1:HomePhone1` |
| `Status`                 | `CurrentMilestone`                 |

### Does Hatch sync information back to AccuLynx?

Hatch events and/or communications can be sync’d to AccuLynx in the following scenarios. These options are configurable during the integration setup. If enabled, Hatch will log the push communications as a comment in the Job Messages of the associated AccuLynx Job record.

<Note>
  Keep in mind that push communications occur instantaneously. There must be an AccuLynx record in Hatch at the time of the communication event in order for it to succeed.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact,
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### FAQ

<AccordionGroup>
  <Accordion title="How often does my AccuLynx information sync with Hatch?">
    Every 15 minutes.
  </Accordion>

  <Accordion title="In AccuLynx my contact is in the current status &#x22;Dead&#x22;--why is it showing in Hatch as &#x22;Cancelled&#x22;?">
    That's how the data is returned via the AccuLynx API. In Hatch, you should adjust your targeting for contacts in the current status/milestone of "Dead" by targeting "Cancelled" instead.
  </Accordion>

  <Accordion title="What will the communication records look like once pushed to AccuLynx?">
    Keeping in mind that the push communications are configurable, they might look something like this in your Job messages:

    <br />

    <img alt="Screenshot 2024-07-29 121614-1" />
  </Accordion>
</AccordionGroup>


# AccuLynx v2
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/acculynx-v2-integration

What Hatch's AccuLynx v2 integration is, how it works, and where to begin.

### What does the AccuLynx v2 integration do?

Hatch offers a native integration with AccuLynx that you can activate within the App
Marketplace (located in your Hatch workspace). This integration syncs AccuLynx jobs — along with the contacts,
estimates, calendar appointments, representatives, and job financials attached to them — into Hatch so you can target
them in campaigns, and logs Hatch activity back into AccuLynx as job messages.

AccuLynx v2 combines two delivery paths:

* **Real-time updates** — AccuLynx notifies Hatch when a contact is created or updated, and when a job is
  updated.
* **Scheduled reads** — Hatch reads jobs, estimates, calendar appointments, representatives, users, and job
  financials from AccuLynx every **5 minutes**.

When the integration is first installed, Hatch automatically runs a 90 day back-sync of your AccuLynx data.

The AccuLynx **job** is the center of the model. Every other record Hatch reads is tied back to the job it belongs
to, and to that job's primary contact — that contact's name, phone, and email are what Hatch campaigns reach.

### How do you set up the integration?

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* AccuLynx account with location administrator *or* company administrator privileges
* An AccuLynx API key for the location you want to connect

#### **Setup Steps**

1. In Hatch, open the **App Marketplace**.
2. Under the **CRMs** filter, click the Connect button for **AccuLynx v2**.
3. In the setup window, click **Install**.
4. AccuLynx authenticates with an API key (not OAuth). Paste the API key for the AccuLynx location you are
   connecting.
   1. The necessary API key can be generated in AccuLynx: Account Settings > Add-ons and Integrations > API Keys
5. Enable the objects Hatch will read — **Contacts**, **Jobs**, **Estimates**, **Calendar Appointments**,
   **Representatives**, **Users**, and **Job Financials**.
6. On the **Select Fields** step, confirm the field selections for each object. Required fields are pre-selected for
   you; all remaining AccuLynx fields, **including your custom fields**, must be enabled by checking them off. To
   enable all fields for an object, choose "Select all optional fields."
7. Review your configuration, then click **Create Integration** to finish.
8. Once activated, a 90 day back-sync of your AccuLynx data will automatically initiate.
9. After the back-sync completes, set up your audience and campaign workflow to launch your AccuLynx contacts into a
   campaign.

### When does Hatch sync data to/from AccuLynx?

#### AccuLynx → Hatch

AccuLynx data reaches Hatch three ways:

* **Real time** — when an AccuLynx **contact** is created or updated, or an AccuLynx **job** is updated, AccuLynx
  notifies Hatch and the record is ingested immediately.
* **Every 5 minutes** — Hatch reads **jobs**, **estimates**, **calendar appointments**, **representatives**,
  **users**, and **job financials** that have changed since the last read.
* **On install** — a 90 day back-sync of all object types runs automatically.

#### Hatch → AccuLynx

**Sync Communications**

Hatch events and communications can be synced to AccuLynx based on the configuration options selected on the
integration. When enabled, Hatch logs the activity as a comment in the **Job Messages** of the AccuLynx job the
activity belongs to.

<Note>
  Push communications occur instantaneously. There must be an AccuLynx job opportunity in Hatch at the time of the
  communication event in order for it to succeed — activity that isn't attached to an AccuLynx job is not logged.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### What AccuLynx data is available in Hatch?

#### Selecting Object Resources

Object selection happens during setup. Hatch reads the AccuLynx resources below, and for each one a small set of
required fields is pre-selected (the fields Hatch maps to its standard fields). Every other field AccuLynx returns
for those objects, **including your custom fields**, can be enabled during setup.

<Note>
  AccuLynx object names and Hatch object names differ. An AccuLynx **job** is an `opportunity` in Hatch, and AccuLynx
  **representatives** and **users** are both `employee` records in Hatch. The detail field prefixes below follow the
  AccuLynx names.
</Note>

| AccuLynx Resource       | Detail Prefix     | What it contains                                                       |
| ----------------------- | ----------------- | ---------------------------------------------------------------------- |
| Jobs                    | `job:`            | The AccuLynx job record, plus any custom fields defined on the job     |
| Contacts                | `contact:`        | The AccuLynx contact record, plus any custom contact fields            |
| Estimates               | `estimate:`       | The job's estimates, their sections, and their financials              |
| Calendar Appointments   | `appointment:`    | Appointments on the AccuLynx calendar, tied to their job               |
| Representatives / Users | `representative:` | The people assigned to the job, and AccuLynx users                     |
| Job Financials          | `financial:`      | Job-level financial totals, such as approved job value and balance due |

#### Available Resource Fields

Every field AccuLynx returns for these resources lands in the matching opportunity's details, under the prefix listed
above. Custom fields are included. Nested values are joined with a colon (`estimate:financials:totalPrice`), and
repeated values are numbered starting at 1 (`contact:phoneNumbers:1:number`). By default a field is treated as
**text**.

The fields listed below are the exception: Hatch recognizes them as **dates, numbers, or true/false values**, so you
can build audience rules on them using date ranges and numeric comparisons rather than text matching. Any AccuLynx
field that isn't on this list — including all of your custom fields — is still available, as text.

| Resource       | Field Name                                             | Data Type |
| -------------- | ------------------------------------------------------ | --------- |
| Job            | `job:contacts:1:isPrimary`                             | Boolean   |
| Job            | `job:createdDate`                                      | Date      |
| Job            | `job:locationAddress:country:id`                       | Number    |
| Job            | `job:locationAddress:state:id`                         | Number    |
| Job            | `job:milestoneDate`                                    | Date      |
| Job            | `job:modifiedDate`                                     | Date      |
| Contact        | `contact:billingAddress:country:id`                    | Number    |
| Contact        | `contact:billingAddress:state:id`                      | Number    |
| Contact        | `contact:mailingAddress:country:id`                    | Number    |
| Contact        | `contact:mailingAddress:state:id`                      | Number    |
| Contact        | `contact:phoneNumbers:1:primary`                       | Boolean   |
| Contact        | `contact:phoneNumbers:1:smsOptOut`                     | Boolean   |
| Estimate       | `estimate:createdBy:role:id`                           | Number    |
| Estimate       | `estimate:createdDate`                                 | Date      |
| Estimate       | `estimate:financials:overheadRate`                     | Number    |
| Estimate       | `estimate:financials:overheadTotal`                    | Number    |
| Estimate       | `estimate:financials:profitRate`                       | Number    |
| Estimate       | `estimate:financials:profitTotal`                      | Number    |
| Estimate       | `estimate:financials:taxRate`                          | Number    |
| Estimate       | `estimate:financials:taxTotal`                         | Number    |
| Estimate       | `estimate:financials:totalCost`                        | Number    |
| Estimate       | `estimate:financials:totalPrice`                       | Number    |
| Estimate       | `estimate:isPrimary`                                   | Boolean   |
| Estimate       | `estimate:modifiedBy:role:id`                          | Number    |
| Estimate       | `estimate:modifiedDate`                                | Date      |
| Estimate       | `estimate:profitMarginRate`                            | Number    |
| Estimate       | `estimate:profitMarginTotal`                           | Number    |
| Estimate       | `estimate:sections:1:createdDate`                      | Date      |
| Estimate       | `estimate:sections:1:modifiedDate`                     | Date      |
| Estimate       | `estimate:sections:1:profitMarginRate`                 | Number    |
| Estimate       | `estimate:sections:1:profitMarginTotal`                | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:overheadRate`   | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:overheadTotal`  | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:profitRate`     | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:profitTotal`    | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:taxRate`        | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:taxTotal`       | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:totalCost`      | Number    |
| Estimate       | `estimate:sections:1:sectionFinancials:totalPrice`     | Number    |
| Appointment    | `appointment:allDay`                                   | Boolean   |
| Appointment    | `appointment:end`                                      | Date      |
| Appointment    | `appointment:start`                                    | Date      |
| Representative | `representative:role:id`                               | Number    |
| Financial      | `financial:approvedJobValue`                           | Number    |
| Financial      | `financial:balanceDue`                                 | Number    |
| Financial      | `financial:worksheetSectionTotals:changeOrderTotal`    | Number    |
| Financial      | `financial:worksheetSectionTotals:discountTotal`       | Number    |
| Financial      | `financial:worksheetSectionTotals:insuranceClaimTotal` | Number    |
| Financial      | `financial:worksheetSectionTotals:supplementTotal`     | Number    |
| Financial      | `financial:worksheetSectionTotals:upgradeTotal`        | Number    |
| Financial      | `financial:worksheetSectionTotals:workNotDoingTotal`   | Number    |
| Financial      | `financial:worksheetSectionTotals:worksheetTotal`      | Number    |

#### Standard Field Mapping

Hatch standard fields are mapped from AccuLynx detail fields as detailed below. Each AccuLynx record Hatch reads
carries the contact information of the job it belongs to, so every record is reachable by a campaign.

**Job Opportunity**

<Note>
  The base object of this opportunity model is the AccuLynx **Job**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the AccuLynx **Job** record.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                    |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| **External ID**                                                | `job:id`                                                 |
| **External Contact ID**                                        | `contact:id` *(the job's primary contact)*               |
| **External Created At**                                        | `job:createdDate`                                        |
| **External Updated At** *(used for Hatch opportunity sorting)* | `job:modifiedDate`                                       |
| **First Name**                                                 | `contact:firstName` *(the job's primary contact)*        |
| **Last Name**                                                  | `contact:lastName` *(the job's primary contact)*         |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*    |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)* |
| **Status**                                                     | `job:currentMilestone`                                   |

**Contact Opportunity**

<Note>
  The base object of this opportunity model is the AccuLynx **Contact**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the AccuLynx **Contact** record.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                    |
| -------------------------------------------------------------- | -------------------------------------------------------- |
| **External ID**                                                | `contact:id`                                             |
| **External Contact ID**                                        | `contact:id`                                             |
| **External Created At**                                        | the time Hatch first received the contact                |
| **External Updated At** *(used for Hatch opportunity sorting)* | the time Hatch last received the contact                 |
| **First Name**                                                 | `contact:firstName`                                      |
| **Last Name**                                                  | `contact:lastName`                                       |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*    |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)* |
| **Status**                                                     | *not set — AccuLynx keeps status on the job*             |

**Estimate, Appointment, Representative, and Financial Opportunities**

<Note>
  The base object of these opportunity models is the AccuLynx **Estimate**, **Calendar Appointment**,
  **Representative**, or **Job Financial** record. AccuLynx links each of these to a job rather than directly to a
  person, so Hatch fills the contact fields from that job's primary contact.
</Note>

| Hatch Standard Field                                           | AccuLynx Detail Field                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **External ID**                                                | the AccuLynx ID of the record itself (`estimate:id`, `appointment:id`, `representative:id`, or the financial record's ID) |
| **External Contact ID**                                        | `contact:id` *(the primary contact of the job the record belongs to)*                                                     |
| **External Created At**                                        | the time Hatch first received the record                                                                                  |
| **External Updated At** *(used for Hatch opportunity sorting)* | the time Hatch last received the record                                                                                   |
| **First Name**                                                 | `contact:firstName` *(the job's primary contact)*                                                                         |
| **Last Name**                                                  | `contact:lastName` *(the job's primary contact)*                                                                          |
| **Phone**                                                      | `contact:phoneNumbers` *(see preference order below)*                                                                     |
| **Email**                                                      | `contact:emailAddresses` *(the address flagged primary)*                                                                  |
| **Status**                                                     | *not set — AccuLynx keeps status on the job*                                                                              |

<Note>
  A contact can hold several phone numbers in AccuLynx, so Hatch picks one using this order of preference: primary
  Mobile, then any Mobile, then primary Home, then primary Work, then primary Unspecified, then any Unspecified.
</Note>

### FAQ

<AccordionGroup>
  <Accordion title="How often does my AccuLynx information sync with Hatch?">
    Contact creates and updates, and job updates, are pushed to Hatch in real time by AccuLynx. On top of that, Hatch
    reads jobs, estimates, calendar appointments, representatives, users, and job financials every 5 minutes so nothing
    is missed.
  </Accordion>

  <Accordion title="Do I need to enable each object in order to sync data?">
    Yes. Objects are enabled during setup, and only the objects you enable — with the fields you select for each —
    are read from AccuLynx. Jobs and contacts are what produce the opportunities you target in campaigns; the remaining
    objects add estimate, appointment, representative, and financial detail you can build audience rules on.
  </Accordion>

  <Accordion title="Are my custom AccuLynx fields available in Hatch?">
    Yes. Every field AccuLynx returns for the objects you enable is available, including custom fields, as long as
    you check the field off during setup. Custom fields come through as text.
  </Accordion>

  <Accordion title="I have multiple AccuLynx locations — how should I connect them?">
    AccuLynx issues a separate API key per location, and a Hatch integration accepts a single API key. Create a
    separate Hatch department for each AccuLynx location and install AccuLynx v2 in each one. That mirrors how AccuLynx
    keeps contact data separate between locations.
  </Accordion>

  <Accordion title="I'm currently using the original AccuLynx integration, can I move to AccuLynx v2?">
    Not yet. Migration from AccuLynx v1 to AccuLynx v2 will be at a later date.
  </Accordion>
</AccordionGroup>


# CertaOne
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/certaone-integration

In this article, we'll cover the basics of our integration with CertaOne. From what it does, to how to get started, and even frequently asked questions.

### **Integration Basics**

CertaOne is a custom CRM developed on Microsoft Dynamics for Certapro franchisees.

#### **What does the integration do?**

**Pull Contacts** : Every **15 minutes** , Hatch will sync with CertaOne to retrieve recently modified **jobs.**

**Push Communications** : Anytime a communication such as a call, text, or email takes place within Hatch, we’ll send that information back to the CertaOne **Job Activities** automatically.

#### **What information does the integration pull into Hatch?**

The integration will pull in any contact details such as Name, Phone Number, and Email from the **Contact Record**. Additionally, the integration will pull in details from the **Jobs, Accounts,** and **Appointments** to create the Hatch opportunity details.

#### **Where do Hatch communications show in CertaOne?**

When communications are sent back to CertaOne, they will show up in **Job Activities**.

We support the following activity types:

* Hatch Inbound Call
* Hatch Outbound Call
* Hatch Inbound SMS
* Hatch Outbound SMS
* Hatch Inbound MMS
* Hatch Outbound MMS
* Hatch Inbound Email
* Hatch Outbound Email
* Hatch Inbound Voicemail
* Hatch Inbound Missed Call

### **Setting Up the Integration**

#### Requirements

Before getting started, a Hatch specific user must be setup in the CertaOne instance. Only these users have the correct authorizations to allow access for the Hatch integration. Contact CertaPro support to get setup with a license.

#### Instructions

1. Navigate to the Hatch app marketplace.
2. Click "Configure" on the CertaPro integration
3. The integration uses OAuth protocol to allow access to the Dynamics APIs, so all you need to do it click *connect* and then  *authorize* on the CertaPro screen that will pop-up. Once authorized, return to the Hatch integration screen and the connection bubble should be blue.

<img alt="" />

4. Adjust any configuration options.
5. Don't forget to click Finish in order to save.

### **Creating Audiences to Add to Campaigns**

After getting a CRM integration set up, the next step is to start working on creating **custom audiences** with your data, and then adding those contacts to campaigns.

Here’s a couple of examples of what we’ll talk about during onboarding...

* Correctly defining contacts statuses in your CRM
* Identifying your call type statues
* Deciding what contact details to use in campaign language

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Will Hatch change contact’s statuses in CertaOne?">
    Hatch does not update any status in CertaOne through the integration. However, if you change the status in CertaOne, Hatch will update that contact’s information next time it syncs.
  </Accordion>

  <Accordion title="How often does the CRM sync?">
    Hatch syncs with CertaOne every 15 minutes.
  </Accordion>

  <Accordion title="What information is pushed back to CertaOne?">
    The only thing pushed back to CertaOne is the communications that occurred in Hatch. This can include texts, emails, or calls.
  </Accordion>
</AccordionGroup>


# How to switch to the Hatch application of ServiceTitan
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/how-to-switch-to-the-hatch-application-of-servicetitan

Get the steps and all your questions answered here

### What exactly do I need to do and why?

You need to switch “hosts” for your ServiceTitan account, so that you are using the Hatch-hosted version. As an official ServiceTitan partner, Hatch customers can (and must) now access ServiceTitan through a Hatch-specific connection, which allows us to better serve you.

### If I switch, will all of the data in my current instance be lost?

No, all of your ServiceTitan and Hatch data will remain intact. The only thing that is changing is the connection that is used to access your ServiceTitan data in Hatch.

### How is this new Hatch version of the ServiceTitan application version different from the one I'm currently using?

The main difference is that the application and API scopes are all contained in Hatch. This ensures that all integrations are activated with the necessary scopes to power it, requires less setup by users, and makes future upgrades a simple, one-click process.

### Do I have to switch?

Yes, this is a required action.

### **When is the deadline for switching over?**

The deadline is August 1.

### What happens if I don’t switch?

Your Hatch account may lose connection to ServiceTitan, and without the latest data, your messaging may have inaccurate information or may reach the wrong contacts.

### Do I need special permissions to update the integration?

In Hatch: You will need the "Manager" role in order to access the integrations marketplace.

In ServiceTitan: You will need access to the Integrations>API Application Settings.

### **How do I switch?**

The process takes 90 seconds. Here's a video walking through the steps, and below it are written instructions with screenshots.

1. In ServiceTitan, click on Integrations in the left-hand panel and then click \*\*API Application Settings
   <img alt="hatch-servicetitan integration migration step 1" />

2. Click **Connect new app** , click **Hatch Official,** then click **connect**

   <img alt="hatch-servicetitan integration migration step 2" />

   <img alt="hatch-servicetitan integration migration step 3" />

3. Click **Allow Access.** This just enables Hatch and ServiceTitan to talk to each other.
   <img alt="servicetitan-migration-04-allow-access" />

4. Click **Accept** on the Terms and Conditions
   <img alt="servicetitan-migration-05-terms-conditions" />

5. This will then bring you to the Application Details screen. At the top where it says “Client ID,” click **Copy**.
   <img alt="hatch-servicetitan integration migration step 6" />

6. Open Hatch, and click on the second icon up from the bottom in the light purple column to go to the **App Marketplace**
   <img alt="hatch-servicetitan integration migration step 7" />

7. Once you’re in the Marketplace, you can easily find ServiceTitan by clicking on **Installed** and **CRM** to easily filter. When you locate ServiceTitan, click on it.
   <img alt="hatch-servicetitan integration migration step 8" />

8. Click **Configure.<img alt="hatch-servicetitan integration migration step 9" />**

9. In the upper right, click **Reconfigure
   <img alt="hatch-servicetitan integration migration step 10" />**

10. Click **Next**

11. Flip the "**use Hatch application** " toggle from disabled to **enabled.**(Purple means it is enabled)
    **<img alt="hatch-servicetitan integration migration step 12" />**

12. Paste your **Client Id** from ServiceTitan (which you copied from Step #5) and paste into the Hatch integration field
    <img alt="hatch-servicetitan integration migration - step 13" />

13. Return back to ServiceTitan. Where it says “Client Secret,” click **Generate** and **Yes continue.
    <img alt="hatch-servicetitan integration migration - step 14" />**

14. Click **Copy** to copy the Client Secret.
    <img alt="hatch-servicetitan integration migration - step 15" />

15. Return back to Hatch and paste in the Client Secret.
    <img alt="hatch-servicetitan integration migration - step 16" />

16. Click **Next** through the remaining configuration pages (these are unrelated to the specific task at hand) until you reach the end of configuration
    <img alt="hatch-servicetitan integration migration step 11" />

17. Hit **Finish** in order to save your new configuration.


# Hubspot
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/hubspot-integration

In this article, we'll cover the basics of our integration with Hubspot. From what it does, to how to get started, and even frequently asked questions.

### **Integration Basics**

#### **What does the integration do?**

**Pull Contacts** : Every 15 minutes, Hatch will sync with Hubspot to retrieve recently modified records. Hatch will create a contact & opportunity based on the Hubspot contact and/or deal records.

**Push Communications** : Anytime a communication such as a call, text, or email takes place within Hatch, the integration will automatically send that information back to Hubspot's **Contact Activities**.

#### **What information does the integration pull into Hatch?**

We pull in the Contact’s name, phone number, and email address to get started. This is typically what we use to put contacts into a campaign. We  *also* pull in any properties related to the contact or deal you may have in Hubspot. This can include things like Address, Quote Amount, Sales Representative. With these details, you can make your messaging extremely customized.

**Where do Hatch communications show in Hubspot?**

When communications are sent back to Hubspot, they will show up in the **Contact Activities** as a **note.**

The integration supports the following activity types:

* Hatch Inbound Call
* Hatch Outbound Call
* Hatch Inbound SMS
* Hatch Outbound SMS
* Hatch Inbound MMS
* Hatch Outbound MMS
* Hatch Inbound Email
* Hatch Outbound Email
* Hatch Inbound Voicemail
* Hatch Inbound Missed Call

### **Setting Up the Integration**

Here’s what we need to get started:

1. Navigate to the Hatch app marketplace.
2. Click "Configure" on the Hubspot integration
3. The integration uses OAuth protocol to allow access to the Hubspot APIs, so all you need to do it click *connect* and then *authorize* on the Hubspot screen that will pop-up. Once authorized, return to the Hatch integration screen and the connection bubble should be blue.

<img alt="" />

4. Adjust any configuration options.
5. Don't forget to click Finish in order to save.

#### Configuration Options

* Enable/Disable push communications

### **Creating Audiences to Add to Campaigns**

After getting a CRM integration set up, the next step is to start working on creating **custom audiences** with your data, and then adding those contacts to campaigns.

Here’s a couple of examples of what we’ll talk about during onboarding...

* Correctly defining contacts statuses in your CRM
* Building your Customer Segments
* Deciding what contact details to use in campaign language

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Will Hatch change contact’s statuses in Hubspot?">
    The Hatch integration does not update any status in Hubspot. However, if you change the status <b>in Hubspot</b>, Hatch will update that contact’s information next time we sync every 15 minutes.
  </Accordion>

  <Accordion title="How often does the integration sync?">
    Our integration syncs every 15 minutes.
  </Accordion>

  <Accordion title="What information is pushed back to Hubspot?">
    Communications that have occurred in Hatch can be pushed back to Hubspot. This can include texts, emails, or calls. These will populate in Hubspot under the Contact Record's Activities.<br /><br />
    Check out our <a href="/integrations/hatch-webhooks/webhooks-basics">webhooks</a> to see what additional options might be available to create a custom integration.
  </Accordion>

  <Accordion title="Are you able to import Custom Fields?">
    We will pull in custom properties from Hubspot if they are on the Contact or Deal object.
  </Accordion>
</AccordionGroup>


# HubSpot v2
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/hubspot-v2-integration

What Hatch's HubSpot v2 integration is, how it works, and where to begin.

### What does the HubSpot v2 integration do?

Hatch offers a native integration with Hubspot that you can activate within the App
Marketplace (located in your Hatch workspace). This integration syncs HubSpot contacts, companies, and deals into
Hatch so you can target them in campaigns, and logs Hatch activity back into HubSpot as notes.

The Hubspot v2 integration syncs contacts, companies, and deals from HubSpot every **5 minutes** via scheduled reads.

When the integration is first installed, Hatch automatically runs a 90 day back-sync of your HubSpot
data.

### How do you set up the integration?

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* HubSpot account with permission to install apps and grant access to contacts, companies, and deals

#### **Setup Steps**

1. In Hatch, open the **App Marketplace**.
2. Under the **CRMs** filter, click the Connect button for **HubSpot v2**.
3. In the setup window, click **Install**.
4. Hatch uses OAuth to connect with HubSpot. Log in to your HubSpot account, choose the HubSpot portal you want to
   connect, and authorize the connection.
5. Review the objects Hatch will read — **Contacts**, **Companies**, and **Deals** — and confirm the field selections
   for each. Required fields are pre-selected for you; all remaining HubSpot properties, **including your custom
   properties**, must be manually enabled by checking off each field. To enable all fields, check "Select all fields."
6. Answer the optional mapping prompts so Hatch knows which HubSpot property to treat as each value (see
   **Configuration Options** below).
7. **For each object**, ensure to select "Install" (or "Save" if not the first object being installed) to setup the integration. When finished, a green checkmark will appear next to the object.
8. Once activated, a 90 day back-sync of your HubSpot data will automatically initiate.
9. After the back-sync completes, set up your audience and campaign workflow to launch your HubSpot contacts into a
   campaign.

#### Configuration Options

During setup you are asked to point a handful of Hatch values at the HubSpot property that holds them. These prompts
exist because HubSpot has no standard property for these values, and every portal models them differently:

* **Contact status** — the contact property Hatch should read as the opportunity status.
* **Company email** — the company property to use as the email address for contacts generated from a company.
* **Company first name** and **Company last name** — the company properties to use as the name for contacts
  generated from a company.
* **Company status** — the company property Hatch should read as the opportunity status.
* **Deal status** — the deal property Hatch should read as the opportunity status (commonly the deal stage).

### When does Hatch sync data to/from HubSpot?

#### HubSpot → Hatch

HubSpot data reaches Hatch two ways:

* **Every 5 minutes** — Hatch reads contacts, companies, and deals that have changed since the last read.
* **On install** — a 90 day back-sync of all three object types runs automatically.

#### Hatch → HubSpot

**Sync Communications**

When a Hatch communication occurs on a HubSpot-sourced opportunity, Hatch writes it into HubSpot as a **Note**
engagement and associates that note with the HubSpot record the communication belongs to — the contact, the company,
or the deal.

* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact

<Note>
  Push communications occur instantaneously. There must be a HubSpot-sourced opportunity in Hatch at the time of the
  communication event in order for it to succeed.
</Note>

### What HubSpot data is available in Hatch?

#### Selecting Object Resources

Object selection happens during setup. Hatch reads three HubSpot resources — **Contacts**, **Companies**, and
**Deals** — and for each one a small set of required fields is pre-selected (the fields Hatch maps to its
standard fields). Every other field HubSpot returns for those objects, **including your custom properties**, can be enabled during setup.

<Note>
  HubSpot object names and Hatch object names differ. A HubSpot **company** is an `account` in Hatch, and a HubSpot
  **deal** is an `opportunity` in Hatch. The detail field prefixes below follow the Hatch names.
</Note>

#### Available Resource Fields

Every HubSpot property returned for a contact, company, or deal lands in the matching opportunity's details, under
the `contact:`, `account:`, or `opportunity:` prefix. Custom properties are included. By default a property is
treated as **text**.

The properties listed below are the exception: Hatch recognizes them as **dates, numbers, or true/false values**, so
you can build audience rules on them using date ranges and numeric comparisons rather than text matching. Any HubSpot
property that isn't on this list — including all of your custom properties — is still available, as text.

| Resource           | Field Name                                                 | Data Type |
| ------------------ | ---------------------------------------------------------- | --------- |
| Account (Company)  | `account:annualrevenue`                                    | Number    |
| Account (Company)  | `account:closedate`                                        | Date      |
| Account (Company)  | `account:createdate`                                       | Date      |
| Account (Company)  | `account:days_to_close`                                    | Number    |
| Account (Company)  | `account:engagements_last_meeting_booked`                  | Date      |
| Account (Company)  | `account:facebookfans`                                     | Number    |
| Account (Company)  | `account:first_contact_createdate`                         | Date      |
| Account (Company)  | `account:first_conversion_date`                            | Date      |
| Account (Company)  | `account:first_deal_created_date`                          | Date      |
| Account (Company)  | `account:hs_analytics_first_timestamp`                     | Date      |
| Account (Company)  | `account:hs_analytics_first_visit_timestamp`               | Date      |
| Account (Company)  | `account:hs_analytics_last_timestamp`                      | Date      |
| Account (Company)  | `account:hs_analytics_last_visit_timestamp`                | Date      |
| Account (Company)  | `account:hs_analytics_latest_source_timestamp`             | Date      |
| Account (Company)  | `account:hs_analytics_num_page_views`                      | Number    |
| Account (Company)  | `account:hs_analytics_num_visits`                          | Number    |
| Account (Company)  | `account:hs_created_by_user_id`                            | Number    |
| Account (Company)  | `account:hs_is_enriched`                                   | Boolean   |
| Account (Company)  | `account:hs_is_target_account`                             | Boolean   |
| Account (Company)  | `account:hs_last_booked_meeting_date`                      | Date      |
| Account (Company)  | `account:hs_last_logged_call_date`                         | Date      |
| Account (Company)  | `account:hs_last_open_task_date`                           | Date      |
| Account (Company)  | `account:hs_last_sales_activity_timestamp`                 | Date      |
| Account (Company)  | `account:hs_lastmodifieddate`                              | Date      |
| Account (Company)  | `account:hs_num_blockers`                                  | Number    |
| Account (Company)  | `account:hs_num_child_companies`                           | Number    |
| Account (Company)  | `account:hs_num_contacts_with_buying_roles`                | Number    |
| Account (Company)  | `account:hs_num_decision_makers`                           | Number    |
| Account (Company)  | `account:hs_num_open_deals`                                | Number    |
| Account (Company)  | `account:hs_object_id`                                     | Number    |
| Account (Company)  | `account:hs_parent_company_id`                             | Number    |
| Account (Company)  | `account:hs_total_deal_value`                              | Number    |
| Account (Company)  | `account:hs_updated_by_user_id`                            | Number    |
| Account (Company)  | `account:hubspot_owner_assigneddate`                       | Date      |
| Account (Company)  | `account:is_public`                                        | Boolean   |
| Account (Company)  | `account:notes_last_contacted`                             | Date      |
| Account (Company)  | `account:notes_last_updated`                               | Date      |
| Account (Company)  | `account:notes_next_activity_date`                         | Date      |
| Account (Company)  | `account:num_associated_contacts`                          | Number    |
| Account (Company)  | `account:num_associated_deals`                             | Number    |
| Account (Company)  | `account:num_contacted_notes`                              | Number    |
| Account (Company)  | `account:num_conversion_events`                            | Number    |
| Account (Company)  | `account:numberofemployees`                                | Number    |
| Account (Company)  | `account:recent_conversion_date`                           | Date      |
| Account (Company)  | `account:recent_deal_amount`                               | Number    |
| Account (Company)  | `account:recent_deal_close_date`                           | Date      |
| Account (Company)  | `account:total_revenue`                                    | Number    |
| Account (Company)  | `account:twitterfollowers`                                 | Number    |
| Contact            | `contact:closedate`                                        | Date      |
| Contact            | `contact:createdate`                                       | Date      |
| Contact            | `contact:days_to_close`                                    | Number    |
| Contact            | `contact:engagements_last_meeting_booked`                  | Date      |
| Contact            | `contact:first_conversion_date`                            | Date      |
| Contact            | `contact:first_deal_created_date`                          | Date      |
| Contact            | `contact:hs_analytics_average_page_views`                  | Number    |
| Contact            | `contact:hs_analytics_first_timestamp`                     | Date      |
| Contact            | `contact:hs_analytics_first_visit_timestamp`               | Date      |
| Contact            | `contact:hs_analytics_last_timestamp`                      | Date      |
| Contact            | `contact:hs_analytics_last_visit_timestamp`                | Date      |
| Contact            | `contact:hs_analytics_num_event_completions`               | Number    |
| Contact            | `contact:hs_analytics_num_page_views`                      | Number    |
| Contact            | `contact:hs_analytics_num_visits`                          | Number    |
| Contact            | `contact:hs_analytics_revenue`                             | Number    |
| Contact            | `contact:hs_contact_enrichment_opt_out`                    | Boolean   |
| Contact            | `contact:hs_contact_enrichment_opt_out_timestamp`          | Date      |
| Contact            | `contact:hs_content_membership_email_confirmed`            | Boolean   |
| Contact            | `contact:hs_content_membership_follow_up_enqueued_at`      | Date      |
| Contact            | `contact:hs_content_membership_registered_at`              | Date      |
| Contact            | `contact:hs_content_membership_registration_email_sent_at` | Date      |
| Contact            | `contact:hs_created_by_user_id`                            | Number    |
| Contact            | `contact:hs_email_bad_address`                             | Boolean   |
| Contact            | `contact:hs_email_bounce`                                  | Number    |
| Contact            | `contact:hs_email_click`                                   | Number    |
| Contact            | `contact:hs_email_delivered`                               | Number    |
| Contact            | `contact:hs_email_first_click_date`                        | Date      |
| Contact            | `contact:hs_email_first_open_date`                         | Date      |
| Contact            | `contact:hs_email_first_reply_date`                        | Date      |
| Contact            | `contact:hs_email_first_send_date`                         | Date      |
| Contact            | `contact:hs_email_last_click_date`                         | Date      |
| Contact            | `contact:hs_email_last_open_date`                          | Date      |
| Contact            | `contact:hs_email_last_reply_date`                         | Date      |
| Contact            | `contact:hs_email_last_send_date`                          | Date      |
| Contact            | `contact:hs_email_open`                                    | Number    |
| Contact            | `contact:hs_email_optout`                                  | Boolean   |
| Contact            | `contact:hs_email_quarantined`                             | Boolean   |
| Contact            | `contact:hs_email_replied`                                 | Number    |
| Contact            | `contact:hs_email_sends_since_last_engagement`             | Number    |
| Contact            | `contact:hs_first_closed_order_id`                         | Number    |
| Contact            | `contact:hs_first_engagement_object_id`                    | Number    |
| Contact            | `contact:hs_first_order_closed_date`                       | Date      |
| Contact            | `contact:hs_is_enriched`                                   | Boolean   |
| Contact            | `contact:hs_is_unworked`                                   | Boolean   |
| Contact            | `contact:hs_last_sales_activity_timestamp`                 | Date      |
| Contact            | `contact:hs_latest_disqualified_lead_date`                 | Date      |
| Contact            | `contact:hs_latest_open_lead_date`                         | Date      |
| Contact            | `contact:hs_latest_qualified_lead_date`                    | Date      |
| Contact            | `contact:hs_latest_sequence_ended_date`                    | Date      |
| Contact            | `contact:hs_latest_sequence_enrolled`                      | Number    |
| Contact            | `contact:hs_latest_sequence_enrolled_date`                 | Date      |
| Contact            | `contact:hs_latest_source_timestamp`                       | Date      |
| Contact            | `contact:hs_lifecyclestage_customer_date`                  | Date      |
| Contact            | `contact:hs_lifecyclestage_evangelist_date`                | Date      |
| Contact            | `contact:hs_lifecyclestage_lead_date`                      | Date      |
| Contact            | `contact:hs_lifecyclestage_marketingqualifiedlead_date`    | Date      |
| Contact            | `contact:hs_lifecyclestage_opportunity_date`               | Date      |
| Contact            | `contact:hs_lifecyclestage_other_date`                     | Date      |
| Contact            | `contact:hs_lifecyclestage_salesqualifiedlead_date`        | Date      |
| Contact            | `contact:hs_lifecyclestage_subscriber_date`                | Date      |
| Contact            | `contact:hs_membership_has_accessed_private_content`       | Number    |
| Contact            | `contact:hs_membership_last_private_content_access_date`   | Date      |
| Contact            | `contact:hs_object_id`                                     | Number    |
| Contact            | `contact:hs_recent_closed_order_date`                      | Date      |
| Contact            | `contact:hs_registered_member`                             | Number    |
| Contact            | `contact:hs_sa_first_engagement_date`                      | Date      |
| Contact            | `contact:hs_sales_email_last_clicked`                      | Date      |
| Contact            | `contact:hs_sales_email_last_opened`                       | Date      |
| Contact            | `contact:hs_sales_email_last_replied`                      | Date      |
| Contact            | `contact:hs_sequences_enrolled_count`                      | Number    |
| Contact            | `contact:hs_sequences_is_enrolled`                         | Boolean   |
| Contact            | `contact:hs_time_to_first_engagement`                      | Number    |
| Contact            | `contact:hs_updated_by_user_id`                            | Number    |
| Contact            | `contact:hs_v2_date_entered_customer`                      | Date      |
| Contact            | `contact:hs_v2_date_entered_evangelist`                    | Date      |
| Contact            | `contact:hs_v2_date_entered_lead`                          | Date      |
| Contact            | `contact:hs_v2_date_entered_marketingqualifiedlead`        | Date      |
| Contact            | `contact:hs_v2_date_entered_opportunity`                   | Date      |
| Contact            | `contact:hs_v2_date_entered_other`                         | Date      |
| Contact            | `contact:hs_v2_date_entered_salesqualifiedlead`            | Date      |
| Contact            | `contact:hs_v2_date_entered_subscriber`                    | Date      |
| Contact            | `contact:hs_v2_date_exited_customer`                       | Date      |
| Contact            | `contact:hs_v2_date_exited_evangelist`                     | Date      |
| Contact            | `contact:hs_v2_date_exited_lead`                           | Date      |
| Contact            | `contact:hs_v2_date_exited_marketingqualifiedlead`         | Date      |
| Contact            | `contact:hs_v2_date_exited_opportunity`                    | Date      |
| Contact            | `contact:hs_v2_date_exited_other`                          | Date      |
| Contact            | `contact:hs_v2_date_exited_salesqualifiedlead`             | Date      |
| Contact            | `contact:hs_v2_date_exited_subscriber`                     | Date      |
| Contact            | `contact:hubspot_owner_assigneddate`                       | Date      |
| Contact            | `contact:hubspotscore`                                     | Number    |
| Contact            | `contact:lastmodifieddate`                                 | Date      |
| Contact            | `contact:notes_last_contacted`                             | Date      |
| Contact            | `contact:notes_last_updated`                               | Date      |
| Contact            | `contact:notes_next_activity_date`                         | Date      |
| Contact            | `contact:num_associated_deals`                             | Number    |
| Contact            | `contact:num_contacted_notes`                              | Number    |
| Contact            | `contact:num_conversion_events`                            | Number    |
| Contact            | `contact:num_notes`                                        | Number    |
| Contact            | `contact:num_unique_conversion_events`                     | Number    |
| Contact            | `contact:recent_conversion_date`                           | Date      |
| Contact            | `contact:recent_deal_amount`                               | Number    |
| Contact            | `contact:recent_deal_close_date`                           | Date      |
| Contact            | `contact:total_revenue`                                    | Number    |
| Opportunity (Deal) | `opportunity:amount`                                       | Number    |
| Opportunity (Deal) | `opportunity:amount_in_home_currency`                      | Number    |
| Opportunity (Deal) | `opportunity:closedate`                                    | Date      |
| Opportunity (Deal) | `opportunity:createdate`                                   | Date      |
| Opportunity (Deal) | `opportunity:days_to_close`                                | Number    |
| Opportunity (Deal) | `opportunity:engagements_last_meeting_booked`              | Date      |
| Opportunity (Deal) | `opportunity:hs_acv`                                       | Number    |
| Opportunity (Deal) | `opportunity:hs_analytics_latest_source_timestamp`         | Date      |
| Opportunity (Deal) | `opportunity:hs_arr`                                       | Number    |
| Opportunity (Deal) | `opportunity:hs_closed_won_count`                          | Number    |
| Opportunity (Deal) | `opportunity:hs_created_by_user_id`                        | Number    |
| Opportunity (Deal) | `opportunity:hs_deal_stage_probability`                    | Number    |
| Opportunity (Deal) | `opportunity:hs_exchange_rate`                             | Number    |
| Opportunity (Deal) | `opportunity:hs_forecast_amount`                           | Number    |
| Opportunity (Deal) | `opportunity:hs_forecast_probability`                      | Number    |
| Opportunity (Deal) | `opportunity:hs_is_closed`                                 | Boolean   |
| Opportunity (Deal) | `opportunity:hs_is_closed_count`                           | Number    |
| Opportunity (Deal) | `opportunity:hs_is_closed_lost`                            | Boolean   |
| Opportunity (Deal) | `opportunity:hs_is_closed_won`                             | Boolean   |
| Opportunity (Deal) | `opportunity:hs_is_open_count`                             | Number    |
| Opportunity (Deal) | `opportunity:hs_lastmodifieddate`                          | Date      |
| Opportunity (Deal) | `opportunity:hs_mrr`                                       | Number    |
| Opportunity (Deal) | `opportunity:hs_num_of_associated_line_items`              | Number    |
| Opportunity (Deal) | `opportunity:hs_object_id`                                 | Number    |
| Opportunity (Deal) | `opportunity:hs_projected_amount`                          | Number    |
| Opportunity (Deal) | `opportunity:hs_projected_amount_in_home_currency`         | Number    |
| Opportunity (Deal) | `opportunity:hs_tcv`                                       | Number    |
| Opportunity (Deal) | `opportunity:hs_updated_by_user_id`                        | Number    |
| Opportunity (Deal) | `opportunity:hubspot_owner_assigneddate`                   | Date      |
| Opportunity (Deal) | `opportunity:notes_last_contacted`                         | Date      |
| Opportunity (Deal) | `opportunity:notes_last_updated`                           | Date      |
| Opportunity (Deal) | `opportunity:notes_next_activity_date`                     | Date      |
| Opportunity (Deal) | `opportunity:num_associated_contacts`                      | Number    |
| Opportunity (Deal) | `opportunity:num_contacted_notes`                          | Number    |
| Opportunity (Deal) | `opportunity:num_notes`                                    | Number    |

#### Standard Field Mapping

Hatch standard fields are mapped from HubSpot detail fields as detailed below.

**Contact Opportunity**

<Note>
  The base object of this opportunity model is the HubSpot **Contact**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the HubSpot **Contact** record.
</Note>

| Hatch Standard Field                                           | HubSpot Detail Field                                               |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| **External ID**                                                | `contact:id`                                                       |
| **External Contact ID**                                        | `contact:id`                                                       |
| **External Created At**                                        | `contact:createdate`                                               |
| **External Updated At** *(used for Hatch opportunity sorting)* | `contact:lastmodifieddate`                                         |
| **First Name**                                                 | `contact:firstname`                                                |
| **Last Name**                                                  | `contact:lastname`                                                 |
| **Phone**                                                      | `contact:phone`                                                    |
| **Email**                                                      | `contact:email`                                                    |
| **Status**                                                     | the contact property you mapped to **Contact status** during setup |

**Account Opportunity**

<Note>
  The base object of this opportunity model is the HubSpot **Company**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the HubSpot **Company** record.
</Note>

| Hatch Standard Field                                           | HubSpot Detail Field                                                                                          |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **External ID**                                                | `account:id`                                                                                                  |
| **External Contact ID**                                        | the associated contact's `contact:id`, or `account:id` when the company has no contacts                       |
| **External Created At**                                        | `account:createdate`                                                                                          |
| **External Updated At** *(used for Hatch opportunity sorting)* | `account:hs_lastmodifieddate`                                                                                 |
| **First Name**                                                 | the company property mapped to **Company first name**, otherwise the associated contact's `contact:firstname` |
| **Last Name**                                                  | the company property mapped to **Company last name**, otherwise the associated contact's `contact:lastname`   |
| **Phone**                                                      | `account:phone`, falling back to the associated contact's `contact:phone`                                     |
| **Email**                                                      | the company property mapped to **Company email**, falling back to the associated contact's `contact:email`    |
| **Status**                                                     | the company property you mapped to **Company status** during setup                                            |

**Opportunity**

<Note>
  The base object of this opportunity model is the HubSpot **Deal**. Therefore, (as an example) the **External ID**
  field would indicate the ID of the HubSpot **Deal** record.
</Note>

| Hatch Standard Field                                           | HubSpot Detail Field                                                                            |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **External ID**                                                | `opportunity:id`                                                                                |
| **External Contact ID**                                        | the associated contact's `contact:id`, or the associated company's `account:id`                 |
| **External Created At**                                        | `opportunity:createdate`                                                                        |
| **External Updated At** *(used for Hatch opportunity sorting)* | `opportunity:hs_lastmodifieddate`                                                               |
| **First Name**                                                 | the associated contact's `contact:firstname`, or the company's mapped first name                |
| **Last Name**                                                  | the associated contact's `contact:lastname`, or the company's mapped last name                  |
| **Phone**                                                      | the associated contact's `contact:phone`, or the associated company's phone                     |
| **Email**                                                      | the associated contact's `contact:email`, or the associated company's mapped email              |
| **Status**                                                     | the deal property you mapped to **Deal status**, falling back to the associated record's status |

### FAQ

<AccordionGroup>
  <Accordion title="How often does my HubSpot information sync with Hatch?">
    The HubSpot v2 integration syncs data every 5 minutes.
  </Accordion>

  <Accordion title="Do I need to install each object in order to sync data?">
    For each object, you must select "Install" (or "Save") in the top right corner of the integration configuration, in order to sync data for that object.
  </Accordion>

  <Accordion title="Are my custom HubSpot properties available in Hatch?">
    Yes. Hatch captures every property HubSpot returns for contacts, companies, and deals, including custom
    properties.
  </Accordion>

  <Accordion title="I'm currently using the original HubSpot integration, can I migrate to HubSpot v2?">
    We will be offering migrations to HubSpot v2 at a later date. Once available, we will provide more information!
  </Accordion>
</AccordionGroup>


# improveit360 (i360)
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/improveit360-i360

An automatic and bi-directional sync between Hatch and improveit360

### Overview

* **Type:** CRM
* **Version:** Prismatic/Hatch App Marketplace
* **Set-Up:** Oauth (Credentials)
* **Sync Frequency:** 15 minutes

### **Shared Data**

<img alt="" />

### Objects that Sync with Hatch

* Appointment
* Production Activity
* Project
* Prospect

*Any fields or values under these objects will be syncing in Hatch and are available in the Hatch product.*

### **Sync Rules:** How a Hatch contact gets updated by i360

The following **TRIGGERS** cause the listed sync **ACTIONS** :

* **TRIGGER:** An improveit360 Appointment object is updated within the last 15 minutes before the sync began
  * **ACTION:** All improveit360 Appointment object fields/values are sync’d
  * **ACTION:** If there is an associated improveit360 Prospect object, that Prospect object’s fields/values are sync’d
* **TRIGGER:** An improveit360 Project object is updated within the last 15 minutes before the sync began
  * **ACTION:** All improveit360 Project object fields/values are sync’d
  * **ACTION:** If there are associated improveit360 Production Activity objects, those Production Activity objects’ fields/values are sync’d
  * **ACTION:** If there is an associated improveit360 Prospect object, that Prospect object’s fields/values are sync’d
* **TRIGGER:** An improveit360 Prospect object is updated within the last 15 minutes before the sync began and was not associated with an improveit360 Appointment object or an improveit360 Project object during the sync
  * **ACTION:** All improveit360 Prospect object fields/values are sync’d

### i360 to Hatch Opportunities

**Creating a Hatch Opportunity**

Sync’d improveit360 objects will be joined into a single Hatch opportunity in one of the following combinations:

* Appointment
* Appointment + Prospect
* Project
* Project + Prospect
* Project + Production Activity (list)
* Project + Production Activity (list) + Prospect
* Prospect

**Updating a Hatch Opportunity**

The integration will replace an existing Hatch opportunity when:

* The sync’d External ID matches the existing opportunity’s External ID
* The sync’d External Created At matches the existing opportunity’s External Created At

**Adding an additional Hatch Opportunity (Opp Sorting)**

The integration will create an additional (new) Hatch opportunity when:

* The sync’d External ID does not match the existing opportunity’s External ID
* The sync’d External Created At does not match the existing opportunity’s External Created At

**Hatch Opportunities to i360 Field Mapping**

The following Hatch standard fields are mapped from improveit360 data (on every Hatch opportunity):

| **Hatch Field**                            | **i360 Field**                                                                                                                                                                                                                                                  |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                                      | Prospect.Primary\_Email Appointment.Email\_Address (if above is missing) Project.Prospect.i360\_\_Primary\_Email (if above is missing)                                                                                                                          |
| External ID                                | Appointment.Id Project.Id (if above is missing) Prospect.Id (if above is missing)                                                                                                                                                                               |
| External Contact ID                        | Prospect.Id Appointment Prospect.Id (if above is missing) Project.Prospect.Id (if above is missing)                                                                                                                                                             |
| External Created At                        | Appointment.CreatedDate (if most recent) Project.CreatedDate (if most recent) Prospect.CreatedDate (if most recent)                                                                                                                                             |
| External Updated At (Used for Opp Sorting) | Appointment.LastModifiedDate (if most recent) Project.LastModifiedDate (if most recent) Prospect.LastModifiedDate (if most recent)                                                                                                                              |
| First Name                                 | Prospect.Primary\_First\_Name Appointment.Prospect\_First\_Name (if above is missing) Project.Prospect.i360\_\_Primary\_First\_Name (if above is missing)                                                                                                       |
| Last Name                                  | Prospect.Primary\_Last\_Name Appointment.Prospect\_Last\_Name (if above is missing) Project.Prospect.i360\_\_Primary\_Last\_Name (if above is missing)                                                                                                          |
| Phone                                      | Prospect.Phone\_1 Prospect.Phone\_2 (if above is missing) Appointment.Phone\_1 (if above is missing) Appointment.Phone\_2 (if above is missing) Project.Prospect.i360\_\_Phone\_1 (if above is missing) Project.Prospect.i360\_\_Phone\_2 (if above is missing) |
| Status                                     | Appointment.Result Project.Status (if above is missing) Prospect.Prospect\_State (if above is missing)                                                                                                                                                          |

### Hatch → lmproveit360

Users can configure Push Communications in the integration setup. Users have the options to push a record of communications that have occurred in Hatch to one (or both) of the following i360 locations:

* Contact Notes
* Tasks


# improveit360 (i360) Lightning
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/improveit360-i360-lightning

An automatic and bi-directional sync between Hatch and improveit360 

### Overview

* **Type:** CRM
* **Set-Up:** OAuth (Credentials)
* **Sync Frequency:** 15 minutes

### Setting Up the Integration

#### Instructions

Here’s what we need to get started:

1. Navigate to the Hatch app marketplace.
2. Click "Configure" on the improveit360 Lightning integration
3. The integration uses OAuth protocol to allow access to the Salesforce APIs, so all you need to do it click  *connect* and then  *authorize* on the i360 screen that will pop-up. Once authorized, return to the Hatch integration screen and the connection bubble should be blue.

<img alt="" />

4. Continue through the configuration wizard to select the desired data objects and push communication options.
5. Don't forget to click Finish in order to save.

### Objects that Sync with Hatch

* Sales Opportunity (+ Contact + Account)
* Sales Appointment
* Project (and optionally Project Activities)

*Any fields or values under these objects will be syncing in Hatch and are available in the Hatch product.*

### How are Hatch opportunities created?

<Note>
  When an **opportunity** is generated that doesn’t match an existing **contact** , a new **contact** will be created. A new **opportunity** will be added to an existing **contact** if a match is found.
</Note>

The integration will replace an existing Hatch opportunity when:

* The sync’d Hatch External ID matches the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

The integration will create an additional (new) Hatch opportunity when:

* The sync’d Hatch External ID does not match the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

### Hatch → lmproveit360

Hatch events and communications can be sync’d to Improveit360 Lightning in the following scenarios. These options are configured during the integration setup and can be reconfigured at any time.

**Push Events can be configured to appear in Improveit360 in the following locations:**

* A Note related to the Contact

<img alt="" />

* A completed Task related to the Contact (where the event details can be found in a comment)

<img alt="" />

**The following Hatch events are supported:**

* When a Hatch campaign sends an outbound communication to a contact
* When a Hatch user sends an outbound communication to a contact
* When a contact sends an inbound communication to a Hatch workspace
* When specific events occur within a Hatch campaign:
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="I am getting a generic error when attempting to integrate ImproveIt360 with Hatch that just tells me to reach out to a Salesforce Admin. Are there any steps I can take before reaching out?">
    Most of the time this error occurs, it's due to missing API permissions. In particular, it's worth checking to make sure the user you're attempting to authorizing Hatch with [**has Connected Apps OAuth Usage enabled**](https://help.salesforce.com/s/articleView?id=005132365\&type=1).

    On the profile level, there is a new permission that needs to be added to the **custom** Admin Profile regarding Connected Apps:\
     \
    *Setup>Profile( Admin)>Edit>Administrative Permission*\
    \
    In here, check the box that says 'Approve Uninstalled Connected Apps'.

    Afterwards, make sure you saved the changes and attempt to reintegrate with Hatch.
  </Accordion>
</AccordionGroup>


# Jobber
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/jobber-integration

What Hatch's Jobber integration is, how it works, and where to begin.

### What does the Jobber integration do?

Hatch offers a native integration with Jobber that you can activate within the App Marketplace (located in your Hatch workspace). This integration syncs contact data from Jobber to Hatch, and can also sync Hatch events to Jobber.

While active, the Jobber integration will sync new and updated Jobber data every 15 minutes. It will also sync Hatch events back to Jobber as soon as they occur (if you have enabled this feature).

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

### How do you set up the integration?

#### Requirements

You will need the following to set up the integration:

* Hatch account with manager privileges
* Jobber account

#### Setup Steps

The following is the set of steps required to activate the integration:

1. In Hatch, open the **App Marketplace**.
2. Under the **CRMs** tab, click the Jobber **Connect** button.
3. In the window that appears, click the **Start Setup** button.
4. Follow the steps of the setup, clicking the **Next** button after each screen is completed.
   1. The setup will open a new browser tab to connect your Jobber account. You will need to approve the connection in this new tab.
5. In the final screen of the setup, click the **Finish** button.

### When does Hatch sync data to/from Jobber?

#### Jobber→ Hatch

Jobber data can be sync’d to Hatch in the following scenarios. These options are configured during the integration setup.

<Note>
  Keep in mind that syncs occur every 15 minutes.
</Note>

* If a work request record is created or updated in Jobber, Hatch syncs the work request record along with any associated data (see below for specific fields)
* If a quote record is created or updated in Jobber, Hatch syncs the quote record along with any associated data (see below for specific fields)

#### Hatch → Jobber

Hatch events and/or communications can be sync’d to Jobber in the following scenarios. These options are configured during the integration setup. If enabled, Hatch will log the communications in the Notes & Attachments of the associated Jobber Work Request, Quote, or Client record (with options to link to additional objects).

<Note>
  Keep in mind that push communications occur instantaneously. There must be a Jobber record in Hatch at the time of the communication event in order for it to succeed.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact,
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### How is Jobber data stored in Hatch?

#### Opportunity Models

There are two types of Hatch opportunities that the Jobber integration creates:

* **Work Request Opportunity** — Created from Jobber Work Request\*\*\*\* records. Additional related data is also included (see below).
* **Quote Opportunity** — These opportunities are created from Jobber Quote records. Additional related data is also included (see below).

#### Opportunity Creation & Update

<Note>
  When an **opportunity** is generated that doesn’t match an existing **contact** , a new **contact** will be created. A new **opportunity** will be added to an existing **contact** if a match is found.
</Note>

The integration will replace an existing Hatch opportunity when:

* The sync’d Hatch External ID matches the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

The integration will create an additional (new) Hatch opportunity when:

* The sync’d Hatch External ID does not match the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

### What Jobber data is available in Hatch?

#### Detail Field Lists

<Note>
  Some fields below are lists. Data within a list field is sorted by “created date” in descending order. For example, a list of jobs would have the most recently-created job listed first.
</Note>

<Note>
  When accessing a list, you need to provide the index number of the list item that you want. Because this index number will vary, it is shown in the lists below with the placeholder **#**.
</Note>

The following fields are available in the opportunity details:

**Quote Opportunity**

| Field                                                    | Type             |
| -------------------------------------------------------- | ---------------- |
| approved\_at                                             | Date             |
| client                                                   | Object           |
| client:balance                                           | Number           |
| client:billing\_address                                  | Object           |
| client:billing\_address:city                             | String           |
| client:billing\_address:country                          | String           |
| client:billing\_address:pc                               | String           |
| client:billing\_address:province                         | String           |
| client:billing\_address:street                           | String           |
| client:billing\_address:street1                          | String           |
| client:billing\_address:street2                          | String           |
| client:company\_name                                     | String           |
| client:created\_at                                       | Date             |
| client:custom\_field\_values                             | Object           |
| client:custom\_field\_values:`<custom_field_name>`       | List OR String   |
| client:custom\_field\_values:`<custom_field_name>`:`<n>` | String           |
| client:emails                                            | List             |
| client:emails:#                                          | Object           |
| client:emails:#:address                                  | String           |
| client:emails:#:description                              | String           |
| client:emails:#:id                                       | String           |
| client:emails:#:primary                                  | Index 1: Boolean |
| Index >1: String (Boolean)                               |                  |
| client:first\_name                                       | String           |
| client:id                                                | String           |
| client:is\_company                                       | Boolean          |
| client:is\_achieved                                      | Boolean          |
| client:last\_name                                        | String           |
| client:name                                              | String           |
| client:phones                                            | Object           |
| client:phones:Main1                                      |                  |
| client:phones:Mobile1                                    |                  |
| client:phones:Home1                                      |                  |
| client:phones:Work1                                      |                  |
| client:phones:Other1                                     |                  |
| client:phones:Fax1                                       | Object           |
| client:phones:Main1:id                                   |                  |
| client:phones:Mobile1:id                                 |                  |
| client:phones:Home1:id                                   |                  |
| client:phones:Work1:id                                   |                  |
| client:phones:Other1:id                                  |                  |
| client:phones:Fax1:id                                    | String           |
| client:phones:Main1:number                               |                  |
| client:phones:Mobile1:number                             |                  |
| client:phones:Home1:number                               |                  |
| client:phones:Work1:number                               |                  |
| client:phones:Other1:number                              |                  |
| client:phones:Fax1:number                                | String           |
| client:phones:Main1:primary                              |                  |
| client:phones:Mobile1:primary                            |                  |
| client:phones:Home1:primary                              |                  |
| client:phones:Work1:primary                              |                  |
| client:phones:Other1:primary                             |                  |
| client:phones:Fax1:primary                               | String (Boolean) |
| client:phones:Main1:sms\_allowed                         |                  |
| client:phones:Mobile1:sms\_allowed                       |                  |
| client:phones:Home1:sms\_allowed                         |                  |
| client:phones:Work1:sms\_allowed                         |                  |
| client:phones:Other1:sms\_allowed                        |                  |
| client:phones:Fax1:sms\_allowed                          | String (Boolean) |
| client:tags                                              | String           |
| client:updated\_at                                       | Date             |
| cost                                                     | Number           |
| created\_at                                              | Date             |
| custom\_field\_values                                    | List             |
| custom\_field\_values:#                                  | Object           |
| custom\_field\_values:#:created\_at                      | String (Date)    |
| custom\_field\_values:#:name                             | String           |
| custom\_field\_values:#:position                         | String (Number)  |
| custom\_field\_values:#:unit                             | String           |
| custom\_field\_values:#:updated\_at                      | String (Date)    |
| custom\_field\_values:#:value                            | List OR String   |
| custom\_field\_values:#:value\_type                      | String           |
| custom\_field\_values:#:value:#                          | String           |
| deposit\_amount                                          | Number           |
| discount\_amount                                         | Number           |
| id                                                       | String           |
| job\_description                                         | String           |
| jobs                                                     | List             |
| jobs:#                                                   | Object           |
| jobs:#:automatically\_charge\_invoice                    | Index 1: Boolean |
| Index >1: String (Boolean)                               |                  |
| jobs:#:billing\_type                                     | String           |
| jobs:#:client                                            | String           |
| jobs:#:completed\_at                                     | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:created\_at                                       | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:custom\_field\_values                             | List             |
| jobs:#:custom\_field\_values:#                           | Object           |
| jobs:#:custom\_field\_values:#:created\_at               | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:custom\_field\_values:#:name                      | String           |
| jobs:#:custom\_field\_values:#:position                  | Index 1: Number  |
| Index >1: String (Number)                                |                  |
| jobs:#:custom\_field\_values:#:unit                      | String           |
| jobs:#:custom\_field\_values:#:updated\_at               | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:custom\_field\_values:#:value                     | List OR String   |
| jobs:#:custom\_field\_values:#:value\_type               | String           |
| jobs:#:custom\_field\_values:#:value:#                   | String           |
| jobs:#:end\_at                                           | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:id                                                | String           |
| jobs:#:job\_number                                       | Index 1: Number  |
| Index >1: String (Number)                                |                  |
| jobs:#:job\_type                                         | String           |
| jobs:#:line\_items                                       | List             |
| jobs:#:line\_items\_cost                                 | Index 1: Number  |
| Index >1: String (Number)                                |                  |
| jobs:#:line\_items\_name                                 | String           |
| jobs:#:line\_items:#                                     | String           |
| jobs:#:property                                          | String           |
| jobs:#:quote                                             | String           |
| jobs:#:start\_at                                         | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| jobs:#:status                                            | String           |
| jobs:#:total\_value                                      | Index 1: Number  |
| Index >1: String (Number)                                |                  |
| jobs:#:updated\_at                                       | Index 1: Date    |
| Index >1: String (Date)                                  |                  |
| message                                                  | String           |
| quote\_number                                            | Number           |
| quote\_status                                            | String           |
| sent\_at                                                 | Date             |
| transitioned\_at                                         | Date             |
| updated\_at                                              | Date             |
| won\_at                                                  | Date             |

**Request Opportunity**

| Field                                                    | Type             |
| -------------------------------------------------------- | ---------------- |
| client                                                   | Object           |
| client:balance                                           | Number           |
| client:billing\_address                                  | Object           |
| client:billing\_address:city                             | String           |
| client:billing\_address:country                          | String           |
| client:billing\_address:pc                               | String           |
| client:billing\_address:province                         | String           |
| client:billing\_address:street                           | String           |
| client:billing\_address:street1                          | String           |
| client:billing\_address:street2                          | String           |
| client:company\_name                                     | String           |
| client:created\_at                                       | Date             |
| client:custom\_field\_values                             | Object           |
| client:custom\_field\_values:`<custom_field_name>`       | List OR String   |
| client:custom\_field\_values:`<custom_field_name>`:`<n>` | String           |
| client:emails                                            | List             |
| client:emails:#                                          | Object           |
| client:emails:#:address                                  | String           |
| client:emails:#:description                              | String           |
| client:emails:#:id                                       | String           |
| client:emails:#:primary                                  | Index 1: Boolean |
| Index >1: String (Boolean)                               |                  |
| client:first\_name                                       | String           |
| client:id                                                | String           |
| client:is\_company                                       | Boolean          |
| client:is\_achieved                                      | Boolean          |
| client:last\_name                                        | String           |
| client:name                                              | String           |
| client:phones                                            | Object           |
| client:phones:Main1                                      |                  |
| client:phones:Mobile1                                    |                  |
| client:phones:Home1                                      |                  |
| client:phones:Work1                                      |                  |
| client:phones:Other1                                     |                  |
| client:phones:Fax1                                       |                  |
| client:phones:Main1:id                                   |                  |
| client:phones:Mobile1:id                                 |                  |
| client:phones:Home1:id                                   |                  |
| client:phones:Work1:id                                   |                  |
| client:phones:Other1:id                                  |                  |
| client:phones:Fax1:id                                    | Object           |
| client:phones:Main1:number                               |                  |
| client:phones:Mobile1:number                             |                  |
| client:phones:Home1:number                               |                  |
| client:phones:Work1:number                               |                  |
| client:phones:Other1:number                              |                  |
| client:phones:Fax1:number                                | String           |
| client:phones:Main1:primary                              |                  |
| client:phones:Mobile1:primary                            |                  |
| client:phones:Home1:primary                              |                  |
| client:phones:Work1:primary                              |                  |
| client:phones:Other1:primary                             |                  |
| client:phones:Fax1:primary                               | String (Boolean) |
| client:phones:Main1:sms\_allowed                         |                  |
| client:phones:Mobile1:sms\_allowed                       |                  |
| client:phones:Home1:sms\_allowed                         |                  |
| client:phones:Work1:sms\_allowed                         |                  |
| client:phones:Other1:sms\_allowed                        |                  |
| client:phones:Fax1:sms\_allowed                          | String (Boolean) |
| client:tags                                              | String           |
| client:updated\_at                                       | Date             |
| created\_at                                              | Date             |
| custom\_field\_values                                    | List             |
| custom\_field\_values:#                                  | Object           |
| custom\_field\_values:#:created\_at                      | String (Date)    |
| custom\_field\_values:#:name                             | String           |
| custom\_field\_values:#:position                         | String (Number)  |
| custom\_field\_values:#:unit                             | String           |
| custom\_field\_values:#:updated\_at                      | String (Date)    |
| custom\_field\_values:#:value                            | List OR String   |
| custom\_field\_values:#:value\_type                      | String           |
| custom\_field\_values:#:value:#                          | String           |
| id                                                       | String           |
| property                                                 | String           |
| source                                                   | String           |
| status                                                   | String           |
| title                                                    | String           |
| updated\_at                                              | Date             |

#### Standard Field Mapping

Hatch standard fields are mapped from Jobber detail fields as detailed below.

**Quote Opportunity**

<Note>
  The base object of this opportunity model is the Jobber **Quote**. Therefore, (as an example) the **id** field would indicate the ID of the Jobber **Quote** record.
</Note>

In Quote opportunities, the following Hatch standard fields are mapped from Jobber detail fields:

| Hatch Standard Field                 | Jobber Detail Field                                                                                                                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                                | client:emails:1:address                                                                                                                                                                   |
| External ID                          | id                                                                                                                                                                                        |
| External Contact ID                  | client:id                                                                                                                                                                                 |
| External Created At                  | created\_at                                                                                                                                                                               |
| External Updated At                  |                                                                                                                                                                                           |
| (used for Hatch opportunity sorting) | updated\_at                                                                                                                                                                               |
| First Name                           | client:first\_name                                                                                                                                                                        |
| Last Name                            | client:last\_name                                                                                                                                                                         |
| Phone Number                         | client:phones:Main1:number (or, if missing: client:phones:Mobile1:number, client:phones:Work1:number, client:phones:Home1:number, client:phones:Other1:number, client:phones:Fax1:number) |

**Request Opportunity**

<Note>
  The base object of this opportunity model is the Jobber **Request**. Therefore, (as an example) the **id** field would indicate the ID of the Jobber **Request** record.
</Note>

In Request opportunities, the following Hatch standard fields are mapped from Jobber detail fields:

| Hatch Standard Field                 | Jobber Detail Field                                                                                                                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                                | client:emails:1:address                                                                                                                                                                   |
| External ID                          | id                                                                                                                                                                                        |
| External Contact ID                  | client:id                                                                                                                                                                                 |
| External Created At                  | created\_at                                                                                                                                                                               |
| External Updated At                  |                                                                                                                                                                                           |
| (used for Hatch opportunity sorting) | updated\_at                                                                                                                                                                               |
| First Name                           | client:first\_name                                                                                                                                                                        |
| Last Name                            | client:last\_name                                                                                                                                                                         |
| Phone Number                         | client:phones:Main1:number (or, if missing: client:phones:Mobile1:number, client:phones:Work1:number, client:phones:Home1:number, client:phones:Other1:number, client:phones:Fax1:number) |


# JobNimbus
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/jobnimbus-integration

In this article, we'll cover the basics of our integration with JobNimbus. From what it does, to how to get started, and even frequently asked questions.

### **Integration Basics**

#### What does the integration do?

**Pull Contacts** : Every hour, the integration will sync with JobNimbus to retrieve recently modified Contacts and Jobs in order to create a Hatch Contact & Opportunity.

**Push Communications** : Anytime a communication such as a call, text, or email takes place within Hatch, we’ll send that information back to JobNimbus’s **Contact's Notes OR Job Notes.**

#### **What information does the integration pull into Hatch?**

The integration pulls in any contact details such as Name, Phone Number, and Email from the **Contact Record**.

The integration *also* pulls in **Jobs**. Those are added to the Contact Details in Hatch. This will include things like Address, Quote Amount, Sales Representative. With these details, we can make your messaging extremely customized.

Optionally, you can choose also to include the activities from the job or contacts.

#### **Where do Hatch communications show in my CRM?**

Communications from Hatch can be sent back to either the Contact Notes or Job Notes section in JobNimbus. The type of communication, when it occurred, who sent it, etc. can be found in the body of the note.

The integration supports the following Hatch activity types:

* Hatch Inbound Call
* Hatch Outbound Call
* Hatch Inbound SMS
* Hatch Outbound SMS
* Hatch Inbound MMS
* Hatch Outbound MMS
* Hatch Inbound Email
* Hatch Outbound Email
* Hatch Inbound Voicemail
* Hatch Inbound Missed Call

### **Setting Up the Integration**

Here’s what we need to get started:

1. Within JobNimbus, **create an** **API Key** for Hatch. You can do this by logging into JobNimbus, going to **Settings** > **API**.  *The access profile created will need to able to access all jobs and contacts as well as create activities.*
2. In the Hatch Integrations Marketplace, activate the JobNimbus integration.
3. Enter the API key previously created into the Hatch integration.
4. Select your push communication preferences.
5. Don't forget to hit Finish.

### **Creating Audiences to Add to Campaigns**

After getting a CRM integration set up, the next step is to start working on creating **custom audiences** with your data, and then adding those contacts to campaigns.

Here’s a couple of examples of what we’ll talk about during onboarding...

* Correctly defining contacts statuses in your CRM
* Identifying your call type statues
* Deciding what contact details to use in campaign language

### **Frequently Asked Questions**

<AccordionGroup>
  <Accordion title="Will Hatch change contact’s statuses in JobNimbus?">
    The integration does not update any status in JobNimbus through the integration. However, if you change the status <strong>in JobNimbus</strong>, Hatch will update that contact’s information next time it syncs.
  </Accordion>

  <Accordion title="How often does the sync with JobNimbus occur?">
    Hatch syncs with your CRM hourly.
  </Accordion>

  <Accordion title="What information is pushed back to JobNimbus?">
    The only thing Hatch will push back to JobNimbus is the communications that occurred in Hatch. This can include texts, emails, or calls. These will populate in JobNimbus under the contact or job's activities section.

    Check out our [webhooks ](/integrations/hatch-webhooks/webhooks-basics) to see what additional options might be available to create a custom integration.
  </Accordion>
</AccordionGroup>


# JobProgress
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/jobprogress-integration

In this article, we'll cover the basics of our integration with JobProgress. From what it does, to how to get started, and even frequently asked questions.

### Integration Basics

#### **What does the integration do?**

**Pull Contacts** : Every **15 minutes** , Hatch will sync with JobProgress to retrieve recently modified **customers, jobs,** and **appointments** to create a Hatch contact & opportunity.

**Push Communications** : Anytime a communication such as a call, text, or email takes place within Hatch, we’ll send that information back to JobProgress's **Job Notes** automatically.

#### **What information does the integration pull into Hatch?**

The integration will pull in any contact details such as Name, Phone Number, and Email from the **Customer Record**. Additionally, the integration will pull in details from the **Jobs,** and **Appointments** to create the Hatch opportunity details.

**Where do Hatch communications show in JobProgress?**

When communications are sent back to JobProgress, they will show up in **Job Notes**.

We support the following activity types:

* Hatch Inbound Call
* Hatch Outbound Call
* Hatch Inbound SMS
* Hatch Outbound SMS
* Hatch Inbound MMS
* Hatch Outbound MMS
* Hatch Inbound Email
* Hatch Outbound Email
* Hatch Inbound Voicemail
* Hatch Inbound Missed Call

### **Setting Up the Integration**

1. To connect your JobProgress account with your existing Hatch account, in JobProgress go to the **Settings > Developers > Generate Token** and click create a new token for Hatch.
2. Copy your token and head to the Hatch App Marketplace. Filter for CRMs and you will find the JobProgress integration.
3. Proceed through the configuration steps, at which point you will need to provide the token generated from your JobProgress account.
   *Note: JobProgress tokens have a 1 year expiration period.*

### **Creating Audiences to Add to Campaigns**

After getting a CRM integration set up, the next step is to start working on creating **custom audiences** with your data, and then adding those contacts to campaigns.

Here’s a couple of examples of what we’ll talk about during onboarding...

* Correctly defining contacts statuses in your CRM
* Identifying your call type statues
* Deciding what contact details to use in campaign language

### **Frequently Asked Questions**

<AccordionGroup>
  <Accordion title="Will Hatch change contact’s statuses in JobProgress?">
    Hatch does not not update any status in JobProgress through the integration. However, if you change the status <b>in JobProgress</b>, Hatch will update that contact’s information next time it syncs.
  </Accordion>

  <Accordion title="How often does the CRM sync?">
    Hatch syncs with JobProgress every 15 minutes.
  </Accordion>

  <Accordion title="What information is pushed back to JobProgress?">
    The only thing pushed back to JobProgress is the communications that occurred in Hatch. This can include texts, emails, or calls. These will populate in JobProgress under the <b>Job Notes</b>.
  </Accordion>

  <Accordion title="Does this integration pull in sold information?">
    Yes, in order to run Sold Reports on this integration, our team will need to know the fields in JobProgress that reflect the <b>Sold Status</b> and <b>Sold Date</b>. These fields need to be present on the Job object in order to power the report.
  </Accordion>
</AccordionGroup>


# LeadPerfection
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/leadperfection

An automatic and bi-directional sync between Hatch and LeadPerfection

### Overview:

* **Type:** CRM
* **Version:** Prismatic/Hatch App Marketplace
* **Setup:** Enter Credentials
* **Sync Frequency:** 15 minutes

### **Setting Up the Integration**

#### Requirements

Before activating the integration, check that your LeadPerfection user has the correct security permissions to authorize the necessary API access. While it's not required, some organizations will create a specific user to grant access for Hatch.

1. In LeadPerfection, navigate to *Security - > User Access*.

2. Find the provided user and select  *Assign*.

3. Navigate to the  *Function Level Security* tab, select  *APISecurity* from the dropdown list

4. Select  *Check All* and click  *Save*.

![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeQo-uytZU--GUr9OFSEuPhDxs2A7PFLOKDpElg1gjYuXmugaciQ_3QrMjaY4AApTMjvb8olNgsyMOLFdbpoaWiqIheJ9t46Ue4X0TF6Hda6OoXBXHDPcvboJRxx7XWTlNtCQdNEK5xoVUYeznbCMlOLQ?key=EvdOgnnnXUl9CMmxZXXdqg)

#### Instructions

1. Navigate to the Hatch app marketplace
2. Click *Connect* on the LeadPerfection integration
3. Enter your LeadPerfection client id and the credentials of the user that will provide API access
4. Complete additional configurations
5. Click *Finish* to save.

### Objects that Sync with Hatch

Every 15 minutes, Hatch will sync with LeadPerfection to retrieve recently modified records:

* Lead
* Prospect

*Any fields or values under these objects will be syncing in Hatch and are available in the Hatch product.*

### When do LeadPerfection objects sync to Hatch?

The following **TRIGGERS** cause the listed sync **ACTIONS** :

* **TRIGGER:** A LeadPerfection Lead object is updated within the last 20 minutes before the sync began, there is at least one LeadPerfection Prospect object associated with the Lead, and all LeadPerfection fields are available that are mapped to Hatch standard fields (below)
  * **ACTION:** All LeadPerfection Lead object fields/values are sync’d
  * **ACTION:** The associated LeadPerfection Prospect object’s fields/values are sync’d
    * In the rare case that there are multiple LeadPerfection Prospect objects associated with the Lead object, Hatch creates one opportunity for every combination of Lead and Prospect
* **TRIGGER:** A LeadPerfection Prospect object is updated within the last 20 minutes before the sync began, was not associated with a LeadPerfection Lead object during the sync, and all LeadPerfection fields are available that are mapped to Hatch standard fields (below)
  * **ACTION:** All LeadPerfection Prospect object fields/values are sync’d

**KNOWN LIMITATIONS:** A Lead's latest Call Result from LeadPerfection is not considered an update that will trigger a Lead to sync. This is a limitation within their APIs.

### LeadPerfection to Hatch Opportunities

**Creating a Hatch Opportunity**

Sync’d LeadPerfection objects will be joined into a single Hatch opportunity in one of the following combinations:

* Lead + Prospect
* Prospect

**Updating a Hatch Opportunity**

The integration will update an existing Hatch opportunity when:

* The sync’d External ID matches the existing opportunity’s External ID
* The sync’d External Created At matches the existing opportunity’s External Created At

**Adding an additional Hatch Opportunity (Opp Sorting)**

The integration will create an additional (new) Hatch opportunity when:

* The sync’d External ID does not match the existing opportunity’s External ID
* The sync’d External Created At does not match the existing opportunity’s External Created At

**Hatch Opportunities to LeadPerfection Field Mapping**

The following Hatch standard fields are mapped from LeadPerfection data (on every Hatch opportunity):

| **Hatch Field**                            | **LeadPerfection Field**                                                                                                                                                                                                                                                |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                                      | Prospect.email                                                                                                                                                                                                                                                          |
| External ID                                | Prospect.leads\[0].id                                                                                                                                                                                                                                                   |
| External Contact ID                        | Prospect.cst\_id                                                                                                                                                                                                                                                        |
| External Created At                        | Prospect.dateadded                                                                                                                                                                                                                                                      |
| External Updated At (Used for Opp Sorting) | Prospect.lastchanged Prospect.leads\[0].lastchangedon (if above is missing) Prospect.leads\[0].dateentered (if above is missing) Prospect.leads\[0].jobs\[0].contractdate (if above is missing) Prospect.leads\[0].appointments\[0].lastchangedon (if above is missing) |
| First Name                                 | Prospect.firstname                                                                                                                                                                                                                                                      |
| Last Name                                  | Prospect.lastname                                                                                                                                                                                                                                                       |
| Phone                                      | Prospect.phone1                                                                                                                                                                                                                                                         |
| Status                                     | Prospect.leads\[0].disposition                                                                                                                                                                                                                                          |

### What can be customized in LeadPerfection Integration Settings in Hatch:

**User options**

* **Push Communications** — A true/false flag that indicates if the integration should push communication data back to LeadPerfection (default is true)
  * **Push To Call Logs** — A true/false flag that indicates if communication data pushed to LeadPerfection should be created as a Call Log object (default is false)
  * **Push To Notes** — A true/false flag that indicates if communication data pushed to LeadPerfection should be created as a Note on the Prospect object (default is true)
  * **Push To Production Notes** — A true/false flag that indicates if communication data pushed to LeadPerfection should be created as a Note on the first Job object in the Lead object (default is false)

### Hatch → LeadPerfection

**Automatically Book Appointments**

Users of Hatch AI can benefit from our calendar integration to automatically book appointments on your schedule. Learn more about our LeadPerfection calendar bot in our dedicated [Calendar: LeadPerfection](/getting-started/hatch-assistant/commands-leadperfection-calendar) article.

### FAQ

<AccordionGroup>
  <Accordion title="How often does the sync with LeadPerfection occur?">
    Hatch syncs with your CRM every 15 minutes.
  </Accordion>

  <Accordion title="What information is pushed back to LeadPerfection?">
    The only records Hatch will push back to LeadPerfection is the communications that occurred in Hatch. This can include inbound and outbound texts, emails, or calls.

    <br />

    <br />

    Here is an example of what the push communications will look like in LeadPerfection:

    <br />

    <img alt="" />

    <br />

    <br />

    Check out our <a href="/integrations/hatch-webhooks/webhooks-basics">webhooks</a> to see what additional options might be available to create a custom integration.
  </Accordion>
</AccordionGroup>


# MarketSharp
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/marketsharp

An automatic and Bi-Directional sync between Hatch and Marketsharp

### **Integrations**

### Overview:

* **Type:** CRM
* **Version:** App Marketplace
* **Setup Type:** Credentials
* **Sync Frequency:** 1 hour

### **Setting Up the Integration**

#### Instructions

1. Navigate to the Hatch app marketplace
2. Click  *Connect* on the Marketsharp integration
3. Enter your Marketsharp company id and the credentials of the user that will provide API access

   1. *Note: If you use a corporate `<>`child company structure, you will enter the corporate company id and the child company id separately. Reference an example here, if your login company were 1234-1:*

   <img alt="" />
4. Complete additional configurations
5. Click  *Finish* to save.

### **Objects that Sync from MarketSharp Into Hatch**

* **Appointment**
* **Contact**
* **Inquiry**

*Any fields or values under these objects will be syncing in Hatch and are available in the Hatch product.*

### **Sync Rules:** How a Hatch contact gets updated by Marketsharp

The following **TRIGGERS** cause the listed sync **ACTIONS** :

* **TRIGGER:** A MarketSharp Appointment object is updated within the last 60 minutes before the sync began
  * **ACTION:** All MarketSharp Appointment object fields/values are sync’d
  * **ACTION:** The associated MarketSharp Inquiry object’s fields/values are sync’d
  * **ACTION:** The associated MarketSharp Contact object’s fields/values are sync’d
* **TRIGGER:** A MarketSharp Inquiry object is updated within the last 60 minutes before the sync began and was not associated with a MarketSharp Appointment object during the sync
  * **ACTION:** All MarketSharp Inquiry object fields/values are sync’d
  * **ACTION:** The associated MarketSharp Contact object’s fields/values are sync’d

MarketSharp to Hatch Opportunities

**Creating a Hatch Opportunity**

Sync’d MarketSharp objects will be joined and create a single NEW Hatch opportunity in one of the following combinations:

* Appointment + Inquiry + Contact
* Inquiry + Contact

**Updating a Hatch Opportunity**

The integration will update an existing Hatch opportunity when:

* The sync’d External ID matches the existing opportunity’s External ID
* The sync’d External Created At matches the existing opportunity’s External Created At

**Adding an additional Hatch Opportunity (Opp Sorting)**

* The sync’d External ID does not match the existing opportunity’s External ID
* The sync’d External Created At does not match the existing opportunity’s External Created At

**Hatch to MarketSharp Field Mapping**

The following Hatch standard fields are mapped from MarketSharp data (on every Hatch opportunity):

| Hatch Standard Field                   | MarketSharp Field                                                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Email                                  | Contact Email                                                                                                                        |
| External ID                            | Inquiry ID                                                                                                                           |
| External Contact ID                    | Contact ID                                                                                                                           |
| External Created At                    | Inquiry Created Datetime                                                                                                             |
| External Updated At (used for sorting) | Contact Modified Datetime (if most recent) Appointment Modified Datetime (if most recent) Inquiry Modified Datetime (if most recent) |
| First Name                             | Contact First Name                                                                                                                   |
| Last Name                              | Contact Last Name                                                                                                                    |
| Phone                                  | Cell Phone                                                                                                                           |
|                                        | Cell Phone 1 (if above is missing)                                                                                                   |
|                                        | Cell Phone 2 (if above is missing)                                                                                                   |
|                                        | Work Phone (if above is missing)                                                                                                     |
|                                        | Work Phone 1 (if above is missing)                                                                                                   |
|                                        | Work Phone 2 (if above is missing)                                                                                                   |
|                                        | Home Phone (if above is missing)                                                                                                     |
|                                        | Home Phone 1 (if above is missing)                                                                                                   |
|                                        | Home Phone 2 (if above is missing)                                                                                                   |
|                                        | Other Phone (if above is missing)                                                                                                    |
|                                        | Other Phone 1 (if above is missing)                                                                                                  |
|                                        | Other Phone 2 (if above is missing)                                                                                                  |
|                                        | Company Phone (if above is missing)                                                                                                  |
|                                        | Assistant Phone (if above is missing)                                                                                                |
|                                        | Car Phone (if above is missing)                                                                                                      |
|                                        | Pager (if above is missing)                                                                                                          |
| Status                                 | Appointment Result                                                                                                                   |

### **MarketSharp Customizations in Hatch Integration Settings:**

#### User options

* **Filter Contacts by Company ID** — A true/false flag that indicates if the integration should only push contacts that match the parent company ID (if no sub-company ID is provided) or the sub-company ID (if a sub-company ID is provided) (default is false)
* **Push Communications to Activities** — A true/false flag that indicates if the integration should push communication data back to MarketSharp Activities (default is true)
* **Push Communications to Notes** — A true/false flag that indicates if the integration should push communication data back to MarketSharp Notes (default is false)

#### Admin options

* **Employee ID** — The employee ID that the integration will use for MarketSharp Notes and/or Activities created by Hatch (default is the employee ID used to authenticate the integration)


# Salesforce Enterprise
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/salesforce-enterprise

What is the Salesforce Enterprise integration, how it works, and where to begin.

### What is the Salesforce Enterprise integration?

The Salesforce Enterprise integration offers all the same benefits as our legacy Salesforce integration...and more! With increased functionality and customizability, the new integration was designed to support the needs of both small businesses and enterprise users.

### What does the integration do?

The integration is bi-directional: While active, the integration will sync new and updated Salesforce data into Hatch every **15 minutes.** It also allows you to automatically push records of Hatch campaign or communication events back to the associated Salesforce record.

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

### How do I set up the integration?

#### Requirements

* API access is required. The minimum Salesforce plan including [API access](https://help.salesforce.com/s/articleView?id=000385436\&type=1) is the Enterprise edition. If you are on the lower tier Professional edition, you may purchase API access as an add-on.
* Sufficient API bandwidth. Salesforce does place a daily limit on the number of requests to the API that can be made by your Salesforce instance. In most cases, this limit should not be an issue. However, if you have many integrations using the API or are syncing massive amounts of data between Hatch and Salesforce then your API request limit is something to be aware of.
* We generally recommend using Admin credentials when authorizing the integration, to ensure that permissions are granted to all the necessary read/write capabilities. Ideally, you will want to authorize the integration with credentials that will ensure stability.

#### Setup Instructions

Here’s what we need to get started:

1. Navigate to the Hatch app marketplace.
2. Click "Configure" on the Salesforce integration
3. The integration uses OAuth protocol to allow access to the Salesforce APIs, so all you need to do it click *connect* and then  *authorize* on the Salesforce screen that will pop-up. Once authorized, return to the Hatch integration screen and the connection bubble should be blue.

<img alt="" />

4. Continue through the configuration wizard to select the desired data objects and push communication options.
5. Don't forget to click Finish in order to save.

#### Configuration Options

The new and improved Salesforce integration offers a multitude of customization options that users can configure. The next sections will go into further detail on how to configure what data will be synced between Hatch and Salesforce.

### What Salesforce data is available in Hatch?

Hatch has defined three types of opportunities that can be generated by the integration: our standardized default objects, custom objects, and advanced custom objects. Each object that you choose to sync with Hatch generate an individual Hatch opportunity.

#### Standard Objects

Hatch has pre-defined a set of standard Salesforce objects that are readily available to sync with Hatch:

* **Lead**
* **Opportunity**
* **Contact**

All three can be toggled on and off at will. Hatch will pull all fields present on these objects (including custom fields) and automatically map the necessary information into the Hatch Contact schema.

<Tip>
  In some cases, the Contact may be unnecessary as a stand-alone Hatch opportunity. The Lead and Opportunity objects will automatically include the details from the related Contact, as these are necessary to turn the objects into Hatch contacts. Unless there is a specific workflow being used that is reliant on the Contact object, it is recommended to leave this turned off.
</Tip>

#### Custom Objects

In addition to the objects Hatch has pre-defined, the integration allows you to define your own custom objects to sync. This includes both standard Salesforce objects and/or objects that may be fully custom to your organization.

When adding a Custom Object to your integration, you will be able to choose from a dropdown list of the available objects pulled from your Salesforce instance:

<Tip>
  Tip: start typing to scroll through the list of objects!
</Tip>

<img alt="" />

Since Hatch has not defined the data schema for these objects, users will need to map the fields from Salesforce into the Hatch contact schema. In order for your custom object to function correctly, your Salesforce object must include one of the following:

* the fields required to create a Hatch contact (Name, Phone, Email)
* a field with a lookup relationship to the Salesforce contact. The integration will automatically access that lookup and pull in the related contact information.

<Tip>
  If the object you desire does not include this information, please consult with your Salesforce admin on a solution.
</Tip>

Please note that this option does still have some limitations, primarily related to limitations in SOQL. For example:

* The SOQL we are using to pull the object as well as its related Contact cannot support polymorphic fields. [Polymorphic fields](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql_relationships_and_polymorph_keys.htm?_ga=2.178163360.466478859.1722876618-455062872.1687191972) are fields that contain a lookup relationship to more than one object type (for example the relationship can be a Lead *or* a Contact). If you attempt to configure an object and receive the below error, you will need to use the Advanced Custom Object to configure this instead. <img alt="Screenshot 2024-08-05 213348" />

#### Advanced Custom Objects

If you need to enable syncing of a more complex Salesforce model into Hatch contacts, this option may be for you: if a technical user within your org can identify the SOQL query to join the needed data together, then you may create an "object" for Hatch to sync with by directly inputting that SOQL.

SOQL can and should be tested first in your Salesforce dev console. We strongly recommend the assistance of a Salesforce admin or developer for use of this option as it may require advanced knowledge of your Salesforce data model and SOQL syntax.

<Warning>
  If invalid SOQL is used to create a Hatch object, it may cause failures within the integration.
</Warning>

To add an Advanced Custom Object to your integration, the `key` will be the name of the object and should match the API name of the base object in Salesforce (this will allow pushcomms to be sent back to Salesforce). The `value` will be a string containing your SOQL query.

<img alt="" />

Please note that this option does still have some limitations, primarily related to limitations in SOQL. For example:

* SOQL will only allow for a single WHERE clause per query. Since Hatch is using the WHERE clause to control the sync time range, it is not available for use in the custom object model (syncs will fail to complete).

### Defining Custom Objects

In order to sync custom objects into Hatch, those objects need to have certain information mapped from the Salesforce fields into the equivalent Hatch fields. If the fields are not mapped correctly, the integration may fail to create contacts or create contacts with incomplete information.

The integration will pull in all of the available fields from the Salesforce object and an example contact to help visualize the data.

<Tip>
  Tip: The example contact will be the most recently modified record. If you want to use a different example contact, navigating back will refresh the selection
</Tip>

As best practice, the following information should be defined within your custom object:

* **Hatch Contact's First Name**
* **Hatch Contact's Last Name**
* **Hatch Contact's Phone Number**
* **Hatch Contact's Email**
* **Hatch Contact's External ID** (The ID of the Salesforce object record. This is typically a system field name `ID` or `Record ID`)
* **Hatch Contact's External Contact ID**(The ID of the related Salesforce Contact. This is typically a system field name `Contact ID` or `Who ID` )
* **Hatch Contact's External Created At** (The datetime that the record was created in Salesforce. This is typically a system field name `Created Date`)
* **Hatch Contact's External Updated At** (The datetime that the record was created in Salesforce. This is typically a system field name `Last Modified Date`)
* **Hatch Contact's Status**(This is not a required field, but can be useful context. We recommend mapping any available field that might give insight into where this contact is in your customer journey)

### **Creating a Hatch Contact & Opportunity**

Each of the objects defined in the configuration step will create an individual Hatch Opportunity.

<img alt="Screenshot 2024-08-09 174150" />

Hatch determines whether an opportunity should be created or updated based on the External ID field.

If there is an existent Hatch Opportunity with the same External Id, then that Hatch Opportunity will be updated. If not, a new Hatch Opportunity will be created.

A Hatch Contact will be created or updated depending on whether or not the Opportunity's contact information (phone or email) are already found in the system. If one of the contact values matches, a Contact will be updated. If not, a new Contact will be created.

### What information does Hatch sync back to Salesforce?

Hatch events and/or communications can be sync’d to Salesforce in the following scenarios. These options are configurable during the integration setup. If enabled for a particular object, Hatch will log the records as **a completed Salesforce Task** on that object.

<Tip>
  Keep in mind that push communications occur instantaneously. There must be a Salesforce record in Hatch at the time of the communication event in order for the push communication to succeed.
</Tip>

* When a Hatch campaign sends a text/email/voicemail to a contact,
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="I re-authorized the integration connection, and now my custom object configurations are blank--what happened?">
    It's likely that the user who reauthorized does not have access to the custom objects previously configured. Leave the configuration as-is, and have another user with appropriate access re-authorize the connection. Your custom object configurations should reappear once that happens.
  </Accordion>

  <Accordion title="How are the example contacts pulled for the field mapping?">
    If the object has a "lastModified" field, then the field mapper will use the most recently updated record. This should make it easy to sync in a test contact with all the fields you need. If there is no "lastModified" field, then the first record returned by Salesforce is used.
  </Accordion>

  <Accordion title="One of the fields I need to map is not available--what do I do?">
    It's possible that the field is not present on the contact being used as an example. You can try creating or modifying a test record or ideal record to force the integration to use that as the mapping example.
  </Accordion>

  <Accordion title="What will the push communications look like in my Salesforce?">
    Keeping in mind that there are some configurable options here, the Salesforce Tasks might look something like this:

    <br />

    <img alt="" />
  </Accordion>

  <Accordion title="I am getting a generic error when attempting to integrate Salesforce with Hatch that just tells me to reach out to a Salesforce Admin. Are there any steps I can take before reaching out?">
    Most of the time this error occurs, it's due to missing API permissions. In particular, it's worth checking to make sure the user you're attempting to authorizing Hatch with [**has Connected Apps OAuth Usage enabled**](https://help.salesforce.com/s/articleView?id=005132365\&type=1).

    On the profile level, there is a new permission that needs to be added to the **custom** Admin Profile regarding Connected Apps:\
     \
    *Setup>Profile( Admin)>Edit>Administrative Permission*\
    \
    In here, check the box that says 'Approve Uninstalled Connected Apps'.

    Afterwards, make sure you saved the changes and attempt to reintegrate with Hatch.
  </Accordion>
</AccordionGroup>


# Salesforce (legacy)
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/salesforce-legacy

An automatic and bi-directional sync between Hatch and Salesforce.

<Note>
  This article covers an older version of our Salesforce integration that is no longer supported. Our new Salesforce Enterprise integration has many of these same features, plus new features to support customization needed by organizations both large and small. Read more about the new integration [**here**](/integrations/crm-field-management-systems/salesforce-enterprise)!
</Note>

#### **Overview:**

* **Type:** CRM
* **Version:** Prismatic/Hatch App Marketplace
* **Set-Up:** Oauth (Credentials)
* **Sync Frequency:** 15 minutes

**Shared Data:**

<img alt="Screen Shot 2022-09-21 at 7.32.53 AM" />

### **Objects that Sync with Hatch:**

* Contact
* Lead
* Opportunity
* OpportunityContactRole

### Sync Rules: How a Hatch Contact gets updated by Salesforce:

The following **TRIGGERS** cause the listed sync **ACTIONS** :

* **TRIGGER:** A Salesforce Opportunity object is updated within the last 17 minutes before the sync began
  * **ACTION:** All Salesforce Opportunity object fields/values are sync’d
  * **ACTION:** If there is an associated Salesforce Contact object, that Contact object’s fields/values are sync’d
  * **ACTION:** If there is not an associated Salesforce Contact object, the associated Salesforce OpportunityContactRole object’s fields/values are sync’d
* **TRIGGER:** A Salesforce Contact object is updated within the last 17 minutes before the sync began and was not associated with a Salesforce Opportunity object during the sync
  * **ACTION:** All Salesforce Contact object fields/values are sync’d
* **TRIGGER:** A Salesforce Lead object is updated within the last 17 minutes before the sync began
  * **ACTION:** All Salesforce Lead object fields/values are sync’d

### **Salesforce to Hatch Opportunities**

**Creating a Hatch Opportunity**

Sync’d Salesforce objects will be joined into a single Hatch opportunity in one of the following combinations:

* Contact
* Opportunity + Contact
* Opportunity + OpportunityContactRole
* Lead

**Updating a Hatch Opportunity**

The integration will replace an existing Hatch opportunity when:

* The sync’d External ID matches the existing opportunity’s External ID
* The sync’d External Created At matches the existing opportunity’s External Created At

**Adding an Additional Hatch Opportunity**

The integration will create an additional (new) Hatch opportunity when:

* The sync’d External ID does not match the existing opportunity’s External ID
* The sync’d External Created At does not match the existing opportunity’s External Created At

**Hatch Opportunities to Salesforce Field Mapping**

| **Hatch Standard Field**                   | **Salesforce Field**                                                                                                                                                                                                             |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email                                      | Contact.Email Lead.Email (if syncing lead record)                                                                                                                                                                                |
| External ID                                | Opportunity.Id Lead.Id (if syncing lead record)                                                                                                                                                                                  |
| External Contact ID                        | Contact.Id Lead.Id (if syncing lead record)                                                                                                                                                                                      |
| External Created At                        | Opportunity.CreatedDate Lead.CreatedDate (if syncing lead record)                                                                                                                                                                |
| External Updated At (used for opp sorting) | Opportunity.LastModifiedDate Lead.LastModifiedDate (if syncing lead record)                                                                                                                                                      |
| First Name                                 | Contact.FirstName Lead.FirstName (if syncing lead record)                                                                                                                                                                        |
| Last Name                                  | Contact.LastName Lead.LastName (if syncing lead record)                                                                                                                                                                          |
| Phone                                      | Contact.MobilePhone Contact.Phone (if above is missing) Lead.Phone (if syncing lead record) Lead.MobilePhone (if syncing lead record and above is missing) Lead.Mobile\_Phone\_\_c (if syncing lead record and above is missing) |
| Status                                     | Opportunity.StageName Lead.Status (if syncing lead record)                                                                                                                                                                       |

### Salesforce Customizations in Hatch Integration Settings

**User options**

* **Ignore Leads** — A true/false flag that indicates if the integration should process or ignore updated lead records (default is false)
* **Push Communications** — A true/false flag that indicates if the integration should push communication data back to the external application (default is true)

**Admin options**

* **Contact Additional Select** — SQL that will be included in the SELECT statement that retrieves the Salesforce Contact records. It is included in the statement like this: SELECT Fields(ALL), (your value here) FROM Contact … (default is N/A)
* **Custom Lead Select** — SQL that will replace the default SELECT statement that retrieves the Salesforce Lead records. It is included in the statement like this: SELECT (your value here) FROM Lead … (default is N/A)
* **Email Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the Email Hatch field (default is \[Contact:Email])
* **External Contact ID Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the External Contact ID Hatch field (default is \[Contact:Id])
* **External Created At Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the External Created At Hatch field (default is \[Opportunity:CreatedDate])
* **External ID Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the External ID Hatch field (default is \[Opportunity:Id])
* **External Updated At Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the External Updated At Hatch field (default is \[Opportunity:LastModifiedDate])
* **First Name Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the First Name Hatch field (default is \[Contact:FirstName])
* **Last Name Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the Last Name Hatch field (default is \[Contact:LastName])
* **Max Iterations** —
* **Opportunity Additional Select** — SQL that will be included in the SELECT statement that retrieves the Salesforce Opportunity records. It is included in the statement like this: SELECT Fields(ALL), (your value here) FROM Opportunity … (default is N/A)
* **Phone Number Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the Phone Hatch field (default is \[Contact:MobilePhone, Contact:Phone])
* **Status Keys** — A list of field names that the integration will attempt to use (in the order provided) to populate the Status Hatch field (default is \[Opportunity:StageName])
* **Sync Schedule** — The schedule that dictates how often the integration attempts to sync (default is every 15 minutes)

### Salesforce API system limits

* A single sync with a high number of Salesforce objects will fail to import data at very high volumes
  * Importing over \~6,000 total objects from Salesforce at one time will be unstable
  * Importing over \~10,000 total objects from Salesforce at once time will almost definitely fail
  * **SOLUTION:** Customers should attempt to limit updates in their system to fewer than 6,000 in any 15 minute period
* If syncs fail for more than 20 minutes, it is possible that some records will be missed
  * When a sync starts, it only requests customer records updated in the last 20 minutes
  * If 20+ minutes go by without a sync, it is possible that the next successful sync will miss records updated beyond the 20 minute window
  * **SOLUTION:** If syncs fail for a long duration, run a back-sync for the time that the syncs were failing to ensure that all data has been sync’d to Hatch

### Salesforce to Hatch Business Logic and Rules and Settings

**Salesforce→Hatch business logic**

1. Define the sync time range
   1. Start timestamp = 17 minutes before the timestamp that the current sync began
   2. End timestamp = the timestamp that the current sync began
2. Get Contact records from Salesforce that have been modified within the sync time range
   1. Both of these criteria must be true for the contact to be pulled:
      1. The LastModifiedDate field on the Contact record must be greater than the start timestamp
      2. The LastModifiedDate field on the Contact record must be less than or equal to the end timestamp
   2. This is the template used to query Salesforce:

```SQL theme={null}
  SELECT
    FIELDS(ALL)
  FROM Contact
  WHERE
    LastModifiedDate >
    AND LastModifiedDate <=
  ORDER BY LastModifiedDate LIMIT 200 OFFSET
```

3. If contact additional select has been set, this is the template used to query Salesforce (instead of the one above):

```SQL theme={null}
  SELECT
    FIELDS(ALL),
  FROM Contact
  WHERE
    LastModifiedDate >
    AND LastModifiedDate <=
  ORDER BY LastModifiedDate LIMIT 200 OFFSET
```

3. Get Opportunity records from Salesforce that have been modified within the sync time range
   1. Both of these criteria must be true for the contact to be pulled:
      1. The LastModifiedDate field on the Opportunity record must be greater than the start timestamp
      2. The LastModifiedDate field on the Opportunity record must be less than or equal to the end timestamp
   2. This is the template used to query Salesforce:

```SQL theme={null}
  SELECT
    FIELDS(ALL)
  FROM Opportunity
  WHERE
    LastModifiedDate >
    AND LastModifiedDate <=
  ORDER BY LastModifiedDate LIMIT 200 OFFSET
```

3. If opportunity additional select has been set, this is the template used to query Salesforce (instead of the one above):

```SQL theme={null}
  SELECT
    FIELDS(ALL),
  FROM Opportunity
  WHERE
    LastModifiedDate >
    AND LastModifiedDate <=
  ORDER BY LastModifiedDate LIMIT 200 OFFSET
```

4. Look through all the Opportunity records that were retrieved and associate a Contact record (if possible)
   1. If the ContactId property does not exist on the Opportunity record, the integration gets the OpportunityContactRole record from Salesforce for the particular Opportunity record and adds the OpportunityContactRole record data to the Opportunity record
   2. If the ContactId property exists on the Opportunity record, the integration looks to see if it has previously acquired the associated Contact record
      1. If the integration previously acquired the Contact record, it adds the Contact record data to the Opportunity record
      2. If the integration did not previously acquire the Contact record, it gets the Contact record from Salesforce and adds the Contact record data to the Opportunity record
   3. The integration looks to see if the ContactId property exists on the Opportunity record
5. Generate a Hatch opportunity for each Opportunity record (with the added Contact record or OpportunityContactRole record data)
   1. All fields with \_\_r in their name are removed
   2. All fields with :records in their name are removed
6. Generate a Hatch opportunity for each Contact record that was not included in Opportunity record data that was already imported
   1. All fields with \_\_r in their name are removed
   2. All fields with :records in their name are removed
7. End the sync if Ignore Leads is set to true
8. Get Lead records from Salesforce that have been modified within the sync time range
   1. Both of these criteria must be true for the contact to be pulled:
      1. The LastModifiedDate field on the Lead record must be greater than the start timestamp
      2. The LastModifiedDate field on the Lead record must be less than or equal to the end timestamp
   2. This is the template used to query Salesforce:

```SQL theme={null}
  SELECT FIELDS(ALL)
  FROM Lead
  WHERE LastModifiedDate >= ${start}
      AND LastModifiedDate < ${end}
  LIMIT 200
  OFFSET ${offset}
```

3. If Custom Lead Select has been set, this is the template used to query Salesforce (instead of the one above):

```SQL theme={null}
  SELECT ${configVars["Custom Lead Select"]}
  FROM Lead
  WHERE LastModifiedDate >= ${start}
      AND LastModifiedDate < ${end}
  LIMIT 200
  OFFSET ${offset}
```

9. Generate a Hatch opportunity for each Lead record
   1. All fields with \_\_r in their name are removed
   2. All fields with :records in their name are removed
10. End the sync

### Hatch→Salesforce business logic

1. Determine which Salesforce object should receive the communication information
   1. Evaluate the first 3 characters of the externalContactID property
   2. If the characters are 006, the communication should be sent to a Salesforce Opportunity
   3. If the characters are 00Q, the communication be sent to a Salesforce Lead
   4. If the characters are neither of these, end the sync
2. Create a new Task record in Salesforce on the object determined in the last step
3. End the sync

### Frequently Asked Questions

<Accordion title="I am getting a generic error when attempting to integrate ImproveIt360 with Hatch that just tells me to reach out to a Salesforce Admin. Are there any steps I can take before reaching out?">
  Most of the time this error occurs, it's due to missing API permissions. In particular, it's worth checking to make sure the user you're attempting to authorizing Hatch with [**has Connected Apps OAuth Usage enabled**](https://help.salesforce.com/s/articleView?id=005132365\&type=1).

  On the profile level, there is a new permission that needs to be added to the **custom** Admin Profile regarding Connected Apps:\
   \
  *Setup>Profile( Admin)>Edit>Administrative Permission*\
  \
  In here, check the box that says 'Approve Uninstalled Connected Apps'.

  Afterwards, make sure you saved the changes and attempt to reintegrate with Hatch.
</Accordion>


# ServiceMinder
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/serviceminder-integration

What is Hatch's ServiceMinder integration, how it works, and where to begin.

### Overview

* **Type:** CRM
* **Version:** Prismatic/Hatch App Marketplace
* **Setup Type:** Credentials
* **Sync Frequency:** 15 minutes

### Setting Up the Integration

#### Instructions

1. Navigate to the Hatch app marketplace
2. Click *Connect* on the ServiceMinder integration
3. Enter your ServiceMinder API Key, User ID, and desired timezone
   <img alt="" />
4. Select which data objects from ServiceMinder you would like Hatch to retrieve: Appointments, Proposals, Contacts
5. Select whether you would like Hatch to sync customer communications with Contact Notes
6. Click *Finish* to save.

### Objects that Sync from ServiceMinder Into Hatch

* **Appointment**
* **Proposals**
* **Contacts**

*Any fields or values under these objects will be syncing in Hatch and are available in the Hatch product.*

### How is ServiceMinder data stored in Hatch?

#### Opportunity Models

There are three types of Hatch opportunities that the ServiceMinder integration creates:

* **Contact Opportunity** — Created from ServiceMinder Contact records. Includes customer details such as name, email, and phone number.
* **Appointment Opportunity** — Created from ServiceMinder Appointment records. Includes scheduling, service, and billing details.
* **Proposal Opportunity** — Created from ServiceMinder Proposal records. Includes pricing, service, and status details along with any custom fields.

#### Opportunity Creation & Update

<Note>
  When an **opportunity** is generated that doesn't match an existing **contact**, a new **contact** will be created. A new **opportunity** will be added to an existing **contact** if a match is found.
</Note>

The integration will replace an existing Hatch opportunity when:

* The synced Hatch External ID matches the existing opportunity's Hatch External ID (see below for how the External ID is mapped)

The integration will create an additional (new) Hatch opportunity when:

* The synced Hatch External ID does not match the existing opportunity's Hatch External ID (see below for how the External ID is mapped)

### What ServiceMinder data is available in Hatch?

#### Standard Field Mapping

**Contact Opportunity**

<Note>
  The base object of this opportunity model is the ServiceMinder **Contact**. Therefore, (as an example) the `Id` field below would indicate the ID of the ServiceMinder Contact record.
</Note>

| Hatch Standard Field  | ServiceMinder Detail Field                |
| --------------------- | ----------------------------------------- |
| `Email`               | `Email`                                   |
| `External ID`         | `Id`                                      |
| `External Contact ID` | `Id`                                      |
| `External Created At` | `CreatedAt`                               |
| `External Updated At` | `UpdatedAt`                               |
| `First Name`          | `Name` (first portion)                    |
| `Last Name`           | `Name` (last portion)                     |
| `Phone Number`        | `Pri Phone` (or, if missing: `Alt Phone`) |

**Appointment Opportunity**

<Note>
  The base object of this opportunity model is the ServiceMinder **Appointment**. Therefore, (as an example) the `Id` field below would indicate the ID of the ServiceMinder Appointment record.
</Note>

| Hatch Standard Field  | ServiceMinder Detail Field                |
| --------------------- | ----------------------------------------- |
| `Email`               | `Email`                                   |
| `External ID`         | `Id`                                      |
| `External Contact ID` | `Contact Id`                              |
| `External Created At` | `CreatedAt`                               |
| `External Updated At` | `Updated At`                              |
| `First Name`          | `Name` (first portion)                    |
| `Last Name`           | `Name` (last portion)                     |
| `Phone Number`        | `Pri Phone` (or, if missing: `Alt Phone`) |
| `Status`              | `Status`                                  |

**Proposal Opportunity**

<Note>
  The base object of this opportunity model is the ServiceMinder **Proposal**. Therefore, (as an example) the `Id` field below would indicate the ID of the ServiceMinder Proposal record. If a Proposal has an empty status, Hatch will default the status to "Unknown".
</Note>

| Hatch Standard Field  | ServiceMinder Detail Field |
| --------------------- | -------------------------- |
| `Email`               | `Email`                    |
| `External ID`         | `Id`                       |
| `External Contact ID` | `Contact Id`               |
| `External Created At` | `Created`                  |
| `External Updated At` | `Updated`                  |
| `First Name`          | `Name` (first portion)     |
| `Last Name`           | `Name` (last portion)      |
| `Phone Number`        | `Phone`                    |
| `Status`              | `Status`                   |

#### Detail Fields

The following fields are available in the opportunity details for each opportunity model:

**Contact Opportunity**

| Field       | Type   |
| ----------- | ------ |
| `Id`        | Number |
| `Name`      | String |
| `Email`     | String |
| `Pri Phone` | String |
| `Alt Phone` | String |
| `CreatedAt` | Date   |
| `UpdatedAt` | Date   |

**Appointment Opportunity**

| Field                      | Type   |
| -------------------------- | ------ |
| `Id`                       | Number |
| `Contact Id`               | Number |
| `Name`                     | String |
| `Status`                   | String |
| `Scheduled Start`          | String |
| `Scheduled Duration Clock` | String |
| `Address1`                 | String |
| `Address2`                 | String |
| `City`                     | String |
| `State`                    | String |
| `Postal Code`              | String |
| `Email`                    | String |
| `Pri Phone`                | String |
| `Alt Phone`                | String |
| `Service`                  | String |
| `Service Agent`            | String |
| `Additional Agents`        | String |
| `Actual Start`             | String |
| `Actual Finish`            | String |
| `Actual Duration Clock`    | String |
| `Constraints`              | String |
| `GeoZones`                 | String |
| `Flash Message`            | String |
| `Total`                    | String |
| `Tentative`                | String |
| `Accounting Class`         | String |
| `Confirmation`             | String |
| `En Route`                 | String |
| `Canceled At`              | String |
| `Cancel Reason`            | String |
| `Invoice`                  | String |
| `Rework For`               | String |
| `Proposal Id`              | String |
| `Tax`                      | String |
| `Start Distance`           | String |
| `Appt Flash Message`       | String |
| `Created By`               | String |
| `Labor`                    | String |
| `Materials`                | String |
| `Updated At`               | String |
| `Subtotal`                 | String |
| `Channel`                  | String |
| `Campaign`                 | String |
| `Team`                     | String |
| `Service Agent Start`      | String |
| `Service Agent Finish`     | String |
| `Actual Duration Man`      | String |
| `Community`                | String |
| `CreatedAt`                | Date   |

**Proposal Opportunity**

| Field                          | Type   |
| ------------------------------ | ------ |
| `Id`                           | Number |
| `Contact Id`                   | Number |
| `Name`                         | String |
| `Status`                       | String |
| `Date`                         | String |
| `Accepted Date`                | String |
| `Service`                      | String |
| `Title`                        | String |
| `Duration`                     | String |
| `Visits`                       | String |
| `Email`                        | String |
| `Phone`                        | String |
| `Address 1`                    | String |
| `Address 2`                    | String |
| `City`                         | String |
| `State`                        | String |
| `Zip`                          | String |
| `Subtotal`                     | String |
| `Value`                        | String |
| `Deposit`                      | String |
| `Progress %`                   | String |
| `Invoiced %`                   | String |
| `Owner`                        | String |
| `Channel`                      | String |
| `Campaign`                     | String |
| `Last Viewed`                  | String |
| `Sent`                         | String |
| `Created`                      | String |
| `Accounting Class`             | String |
| `Contact Category`             | String |
| `Type`                         | String |
| `Decline Reason`               | String |
| `Decline Date`                 | String |
| `Gross Subtotal`               | String |
| `Accepted By`                  | String |
| `Territory ID`                 | String |
| `Change Order For Proposal Id` | String |
| `Materials`                    | String |
| `Labor`                        | String |
| `Expenses`                     | String |
| `Updated`                      | String |
| `Revenue Category`             | String |
| `Asset Start Date`             | String |
| `Asset Days`                   | String |
| `Managed By`                   | String |
| `Last Printed`                 | String |
| `Options`                      | String |

### Does Hatch sync information back to ServiceMinder?

Hatch events and/or communications can be synced to ServiceMinder in the following scenarios. These options are configurable during the integration setup. If enabled, Hatch will log the push communications as a **Contact Note** on the associated ServiceMinder Contact record.

<Note>
  Keep in mind that push communications occur instantaneously. There must be a ServiceMinder record in Hatch at the time of the communication event in order for it to succeed.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact
* When events occur within a Hatch campaign
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

### FAQ

<AccordionGroup>
  <Accordion title="How often does my ServiceMinder information sync with Hatch?">
    Every 15 minutes.
  </Accordion>

  <Accordion title="Can I choose which ServiceMinder record types to sync?">
    Yes. During the integration setup, you can individually enable or disable syncing for Contacts, Appointments, and Proposals.
  </Accordion>

  <Accordion title="What happens if a Proposal has no status in ServiceMinder?">
    If a ServiceMinder Proposal has an empty status field, Hatch will default the status to "Unknown".
  </Accordion>

  <Accordion title="How does Hatch handle the Name field from ServiceMinder?">
    ServiceMinder provides a single combined Name field. Hatch automatically splits this into separate First Name and Last Name fields.
  </Accordion>

  <Accordion title="What will the communication records look like once pushed to ServiceMinder?">
    When push communications are enabled, Hatch communications will appear as Contact Notes on the associated ServiceMinder Contact record. Each note includes a title describing the communication type and a body with the message content.
  </Accordion>

  <Accordion title="Will Hatch change contact statuses in ServiceMinder?">
    Hatch does not update any status in ServiceMinder through the integration. However, if you change the status in ServiceMinder, Hatch will update that contact's information the next time it syncs (every 15 minutes).
  </Accordion>

  <Accordion title="What timezone should I select during setup?">
    Select the timezone your organization operates in. Hatch uses this setting to correctly convert timestamps when syncing data between ServiceMinder and Hatch.
  </Accordion>
</AccordionGroup>

***


# ServiceMonster
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/servicemonster-integration

In this article, we'll cover the basics of our integration with ServiceMonster. From what it does, to how to get started, and even frequently asked questions.

### Integration Basics

#### What does the integration do?

Pull Contacts: Every 15 minutes, Hatch will sync with ServiceMonster to retrieve updated Contacts in order to create a Hatch contact & opportunity.

Push Communications: Anytime a communication such as a call, text, or email takes place within Hatch, the integration will send that information back to ServiceMonster's Account Record in the Activities Section.

#### What information does the integration pull into Hatch?

It will pull in any contact details such as Name, Phone Number, and Email from the Account Record. It will also pull in Jobs, Orders, and Leads. Those are added to the opportunity details in Hatch.

#### Where do Hatch communications show in ServiceMonster?

When communications are sent back to ServiceMonster, they will show up in the Acccount Record in the Activities Section.

The type of Hatch communication is noted in the Subject of the Log, while the content of the communication can be viewed by clicking on the Activity.

Hatch supports the following activity types:

* Hatch Inbound Call
* Hatch Outbound Call
* Hatch Inbound SMS
* Hatch Outbound SMS
* Hatch Inbound MMS
* Hatch Outbound MMS
* Hatch Inbound Email
* Hatch Outbound Email
* Hatch Inbound Voicemail
* Hatch Inbound Missed Call

### Setting Up the Integration

Here’s how to get started:

Hatch offers a native integration with ServiceMonster that you can activate within the App Marketplace.

In your ServiceMonster, navigate to Settings -> Management -> API Users.

Create a new API User with the Role set to Admin.

You can make the optional note Hatch for your reference.

Click Save and note the provided User Name and Password.

In the Hatch Marketplace, fill out the integration configuration form by entering the User Name and Password provided by ServiceMonster for the API User and click "Finish".

### Frequently Asked Questions

#### How often does the sync with ServiceMonster occur?

<Note>
  Hatch syncs with your CRM every 15 minutes.
</Note>

#### Will Hatch change contact’s statuses in ServiceMonster?

<Note>
  Will Hatch change contact’s statuses in ServiceMonster? Hatch does not update any status in ServiceMonster through the integration. However, if you change the status in ServiceMonster, Hatch will update that contact’s information next time it syncs (every 15 minutes).
</Note>

#### What information is pushed back to ServiceMonster?

What information is pushed back to ServiceMonster? The only thing we push back to ServiceMonster is the communications that occurred in Hatch. This can include texts, emails, or calls. These will populate in ServiceMonster's Account Record in the Activities Section.


# ServiceTitan
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/servicetitan-integration

What Hatch's ServiceTitan integration is, how it works, and where to begin. 

### What does the ServiceTitan integration do?

Hatch offers a native integration with ServiceTitan that you can activate within the App Marketplace (located in your Hatch workspace). This integration syncs contact data from ServiceTitan to Hatch, and can also sync Hatch events to ServiceTitan.

While active, the ServiceTitan integration will sync new and updated ServiceTitan data every 15 minutes. It will also sync Hatch events back to ServiceTitan as soon as they occur (if you have enabled this feature).

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

### How do you set up the integration?

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* ServiceTitan account with admin privileges on your tenant

#### **Setup Steps**

Hatch now has an official ServiceTitan App! All users are required to utilize our official ServiceTitan application over a personal application (as per their API terms of use). The Hatch app automatically provides us with the permissions to read or update data in your ServiceTitan tenant. The scopes requested by our app cover all of the possible use cases in Hatch. For reference, the scopes are listed below in the [FAQ](/integrations/crm-field-management-systems/servicetitan-integration#faq) section.

**The following is the set of steps required to activate the integration:**

<Note>
  Before you begin, consider reviewing ServiceTitan's documentation around [ managing client IDs and secrets](https://developer.servicetitan.io/docs/get-going-manage-client-id-and-secret/). However, all of the necessary information is included in the instructions below.
</Note>

1. This first step is manual and will need to be completed in order to proceed with the rest of the setup steps. In order to make the Hatch app available for activation within your ServiceTitan instance, we will need to add your **ServiceTitan Tenant ID** to *our* ServiceTItan application. Please send your Tenant ID over to your onboarding representative to complete.
   1. \_If you're unsure where to find your Tenant ID, you can find it in ServiceTitan via ***Settings → Integrations → API Application Access***
2. Once the Hatch app has been activated for your tenant, you may proceed with setup. In Hatch, open the **App Marketplace**.
3. Under the **CRMs** filter, click the **Connect** button for ServiceTitan.
4. Proceed through the setup until you reach the connection configuration screen.
5. Open the ServiceTitan instance that you want to connect to your Hatch workspace and navigate to **Settings** → **Integrations** → **API Application Access**.
6. Click the **Connect New App** button, accept the terms and conditions (if prompted), and select **Hatch** from the list of apps.
7. With **Hatch** selected, click **Connect**.
8. Scroll to the bottom of the screen that appears.
9. In the *restriction by booking provider* option, choose **No Restriction**.
   1. This simply allows Hatch to post Bookings in ServiceTitan without restriction to a specific booking provider id.
10. Click **Allow Access**.
11. On the resulting **Application Details** screen, copy/paste the **Tenant ID** and the **Client ID** into the associated fields on the Hatch configuration screen.
12. Click the **Generate** button next to **Client Secret** and then click **Yes, Continue** to generate the secret.
13. Copy/paste the **Client Secret** into the associated field on the Hatch setup screen.
14. You may now close any open ServiceTitan pages. All of the remaining steps are completed in Hatch.
15. If you are an Enteprise Hub customer, enable the Enterprise toggle, and enter the Enterprise Hub URL for this tenant ID
16. Enable the opportunity models you would like to sync with Hatch
    1. *additionally select which related objects to include in the data model*
17. Configure your push communications preferences.
18. Make sure to complete the full setup and click **Finish** in order to officially activate your Hatch integration.
    1. *If successfully activated, the integration will begin syncing your last 90 days of data.*

#### How to upgrade the ServiceTitan app

If an application is configured with incorrect scopes or an upgrade to the scopes is required to access new information, you will need to first edit the application in the ServiceTitan dev portal, and then upgrade the connected app within ServiceTitan.

**Upgrade the connected Hatch app to the new version:**

1. Login to your Service Titan account
2. Manage API Application Access page: `<https://go.servicetitan.com/#/Settings/Api-Apps>`
3. In the Hatch App, you should see a message informing about the scope update.
   ![Untitled (3)](https://www.usehatchapp.com/hs-fs/hubfs/Untitled%20\(3\).png?width=688\&height=157\&name=Untitled%20\(3\).png)
4. Click the "upgrade version" button and confirm.

#### Configuration Options

These options can be set during the integration setup:

**Enterprise Hub Toggle:**

* If you are authenticating via Enterprise Hub, enable the Enterprise Hub toggle
* If enabled, enter the Enterprise Hub URL associated with this tenant

**Choose the ServiceTitan data that syncs to Hatch:**

* Choose which opportunity models the integration should sync from ServiceTitan, and subsequently which data objects to include with the model. We will go into further detail regarding the data objects further down in this article in the section "**What ServiceTitan data is available in Hatch?**"
* Configure a filter for placeholder emails: if your org utilizes placeholder emails within your ServiceTitan, this filter will prevent contacts from merging in Hatch based on the shared information

**Push Events and Communications:**

* **Choose where outgoing campaign messages should sync** — if/where Hatch should create ServiceTitan notes for outgoing campaign message events
* **Sync message content for outgoing campaign messages** — if the message content should be included in notes created for outgoing campaign message events
* **Choose where incoming messages & calls should sync** — if/where Hatch should create ServiceTitan notes for incoming messages & calls
* **Sync message content for incoming messages & calls** — if the message content should be included in notes created for incoming messages & calls
* **Choose where outgoing manual messages & calls should sync** — if/where Hatch should create ServiceTitan notes for outgoing manual messages & calls
* **Sync message content for outgoing manual messages & calls** — if the message content should be included in notes created for outgoing manual messages & calls

#### Configuration Best Practices

* **We recommend utilizing the object selector feature in the data configuration to select only the information necessary for your campaigns**. While the integration can sync a wide range of information that might seem relevant, it can also make it more difficult to pick out the pieces that are truly important and useable with your campaign strategies. Now you can customize what you want to sync. Read more about this feature [here](/integrations/crm-field-management-systems/servicetitan-integration#what-servicetitan-data-is-available-in-hatch).

### When does Hatch sync data to/from ServiceTitan?

#### ServiceTitan → Hatch

ServiceTitan data can be sync’d to Hatch in the following scenarios. These options are configured during the [integration setup](/integrations/crm-field-management-systems/servicetitan-integration#setup-steps).

<Note>
  Keep in mind that syncs occur every 15 minutes for Job and Membership data. Completed calls sync instantly using ServiceTitan webhooks.
</Note>

* When a Job record is created or updated in ServiceTitan, Hatch syncs the Job record along with any associated data (see below for specific fields)
* When a Membership record is created or updated in ServiceTitan, Hatch syncs the Membership record along with any associated data (see below for specific fields)
* When a call is completed, Hatch syncs a record along with any associated data

#### Hatch → ServiceTitan

**Automatically Book Jobs**

Users of Hatch AI can benefit from our calendar integration to automatically book jobs on your schedule. Learn more about how our ServiceTitan scheduler bot in our dedicated [calendar integration](/getting-started/hatch-assistant/hatch-assistant-servicetitan-calendar-integration) article.

**Sync Communications**

Hatch events and/or communications can be sync’d to ServiceTitan in the following scenarios. These options are configured during the integration setup.

<Note>
  Keep in mind that push communications occur instantaneously. There must be a ServiceTitan record in Hatch at the time of the sync in order for it to succeed.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact, Hatch creates a Note for the event on the associated Job, Customer, or Location
* When a contact calls or sends a text/email/voicemail to a Hatch workspace, Hatch creates a Note for the event on the associated Job, Customer, or Location
* When a Hatch user calls or sends a text/email to a contact, Hatch creates a Note for the event on the associated Job, Customer, or Location
* When events occur within a Hatch campaign, Hatch creates a Note for the event on the associated Job, Customer, or Location
  * A contact is launched (added) to a Hatch campaign
  * A contact is sent the first message of a Hatch campaign
  * A contact is removed from a Hatch campaign before it has ended
  * A contact completed a Hatch campaign

Below is an example of push communications and push events sent to ServiceTitan Job Notes:

#### ![image (32)](https://www.usehatchapp.com/hs-fs/hubfs/image%20\(32\).png?width=605\&height=818\&name=image%20\(32\).png)

### How is ServiceTitan data stored in Hatch?

#### Opportunity Models

There are two types of Hatch opportunities that the ServiceTitan integration creates:

* **Job Opportunity** — Created from ServiceTitan Job records, this is the primary opportunity type in our ServiceTitan integration. Additional related data is also included (see below).
* **Membership Opportunity** — These opportunities are created from ServiceTitan Membership records. Additional related data is also included (see below).
* **Inbound Call Opportunity** — These opportunities are created when a inbound call is completed in ServiceTitan.

#### Opportunity Creation & Update

<Note>
  When an **opportunity** is generated that doesn’t match an existing **contact** , a new **contact** will be created. A new **opportunity** will be added to an existing **contact** if a match is found.
</Note>

The integration will replace an existing Hatch opportunity when:

* The sync’d Hatch External ID matches the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

The integration will create an additional (new) Hatch opportunity when:

* The sync’d Hatch External ID does not match the existing opportunity’s Hatch External ID (see below for how the External ID is mapped)

### What ServiceTitan data is available in Hatch?

#### Selecting Object Resources

The latest version of our integration allows you to select the resources that are most relevant to your campaigns, instead of syncing all possible data by default. This customizability allows you (and your integration) to operate more efficiently.

Each opportunity model has a certain set of required objects that are needed in order for some aspect of Hatch to function. The additional resources are optional. We have defaulted the configuration with the most commonly used optional resources, but users can select or deselect as needed.

The resources available with a **Job opportunity** are:

* **Estimates** — Necessary in order to utilize a sales follow-up strategy.

* **Appointments** — Useful for appointment confirmation or canceled-appointment campaigns.

* **Appointment Assignments** — Can only be enabled if Appointments is selected. Useful if you want technician information in your campaigns.

* **Cancel Reasons** — Useful for canceled-appointments campaigns.

* **Tag Types** — Useful for segmenting audiences based on existing ServiceTitan tags.

* **Campaigns** — Useful for segmenting audiences based on existing ServiceTitan campaign attribution.

* **Zones** — Useful for location-based targeting.

* **Employees & Technicians (Sold By)** — Necessary if you need the estimate or membership Sold By information.

* **Invoices** — Necessary for accounts-receivable campaigns or post-completion review/referral targeting.
  The resources available with a **Membership opportunity** are:

* **Recurring Services & Events** — Aggregates the latest, next, and full list of recurring service events plus an unused-services count.

* **Tag Types** — Same as above, applied to the membership's customer.

* **Zones** — Adds zone metadata to the membership's location and recurring location.

* **Employees & Technicians (Sold By)** — Adds the membership's soldBy info.

* **Payment Type** — Adds payment type metadata.

#### Available Resource Fields

The following fields are available in the **Job opportunity** details:

| Resource                      | Field Name                                               | Data Type                               |
| ----------------------------- | -------------------------------------------------------- | --------------------------------------- |
| Job                           | `job:id`                                                 | Number                                  |
| Job                           | `job:jobNumber`                                          | String                                  |
| Job                           | `job:jobStatus`                                          | String                                  |
| Job                           | `job:priority`                                           | String                                  |
| Job                           | `job:noCharge`                                           | Boolean                                 |
| Job                           | `job:notificationsEnabled`                               | Boolean                                 |
| Job                           | `job:createdOn`                                          | Date                                    |
| Job                           | `job:modifiedOn`                                         | Date                                    |
| Job                           | `job:completedOn`                                        | Date                                    |
| Job                           | `job:customFields:{name}`                                | String                                  |
| Customer                      | `customer:id`                                            | Number                                  |
| Customer                      | `customer:name`                                          | String                                  |
| Customer                      | `customer:type`                                          | String                                  |
| Customer                      | `customer:active`                                        | Boolean                                 |
| Customer                      | `customer:doNotService`                                  | Boolean                                 |
| Customer                      | `customer:contacts:#:id`                                 | Number                                  |
| Customer                      | `customer:contacts:#:type`                               | String (Email, Phone, MobilePhone, Fax) |
| Customer                      | `customer:contacts:#:value`                              | String                                  |
| Customer                      | `customer:contacts:#:phoneSettings:doNotText`            | Boolean                                 |
| Customer                      | `customer:tagTypes:#:id`                                 | Number                                  |
| Customer                      | `customer:tagTypes:#:name`                               | String                                  |
| Customer                      | `customer:tagTypes:#:active`                             | Boolean                                 |
| Customer                      | `customer:customFields:{name}`                           | String                                  |
| Business Unit                 | `businessUnit:id`                                        | Number                                  |
| Business Unit                 | `businessUnit:name`                                      | String                                  |
| Business Unit                 | `businessUnit:officialName`                              | String                                  |
| Business Unit                 | `businessUnit:active`                                    | Boolean                                 |
| Job Type                      | `jobType:id`                                             | Number                                  |
| Job Type                      | `jobType:name`                                           | String                                  |
| Campaign                      | `campaign:id`                                            | Number                                  |
| Campaign                      | `campaign:name`                                          | String                                  |
| Campaign                      | `campaign:active`                                        | Boolean                                 |
| Location                      | `location:id`                                            | Number                                  |
| Location                      | `location:name`                                          | String                                  |
| Location                      | `location:active`                                        | Boolean                                 |
| Location                      | `location:address:street`                                | String                                  |
| Location                      | `location:address:unit`                                  | String                                  |
| Location                      | `location:address:city`                                  | String                                  |
| Location                      | `location:address:state`                                 | String                                  |
| Location                      | `location:address:zip`                                   | String                                  |
| Location                      | `location:address:country`                               | String                                  |
| Location                      | `location:address:latitude`                              | Number                                  |
| Location                      | `location:address:longitude`                             | Number                                  |
| Zone                          | `location:zone:id`                                       | Number                                  |
| Zone                          | `location:zone:name`                                     | String                                  |
| Tag Types                     | `tagTypes:#:id`                                          | Number                                  |
| Tag Types                     | `tagTypes:#:name`                                        | String                                  |
| Tag Types                     | `tagTypes:#:active`                                      | Boolean                                 |
| Appointments                  | `appointments:#:id`                                      | Number                                  |
| Appointments                  | `appointments:#:appointmentNumber`                       | String                                  |
| Appointments                  | `appointments:#:status`                                  | String                                  |
| Appointments                  | `appointments:#:start`                                   | Date                                    |
| Appointments                  | `appointments:#:end`                                     | Date                                    |
| Appointments                  | `appointments:#:arrivalWindowStart`                      | Date                                    |
| Appointments                  | `appointments:#:arrivalWindowEnd`                        | Date                                    |
| Appointments                  | `appointments:#:specialInstructions`                     | String                                  |
| Appointments                  | `appointments:#:createdOn`                               | Date                                    |
| Appointments                  | `appointments:#:modifiedOn`                              | Date                                    |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:id`             | Number                                  |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:technicianId`   | Number                                  |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:technicianName` | String                                  |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:assignedById`   | Number                                  |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:assignedOn`     | Date                                    |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:status`         | String                                  |
| Appointment Assignments       | `appointments:#:appointmentAssignments:#:isPaused`       | Boolean                                 |
| Cancel Reasons                | `cancelReasons:#:reasonId`                               | Number                                  |
| Estimates                     | `estimates:#:id`                                         | Number                                  |
| Estimates                     | `estimates:#:name`                                       | String                                  |
| Estimates                     | `estimates:#:summary`                                    | String                                  |
| Estimates                     | `estimates:#:active`                                     | Boolean                                 |
| Estimates                     | `estimates:#:subtotal`                                   | Number                                  |
| Estimates                     | `estimates:#:status:value`                               | Number                                  |
| Estimates                     | `estimates:#:status:name`                                | String (Open, Sold, etc.)               |
| Estimates                     | `estimates:#:soldOn`                                     | Date                                    |
| Estimates                     | `estimates:#:createdOn`                                  | Date                                    |
| Estimates                     | `estimates:#:modifiedOn`                                 | Date                                    |
| Estimates                     | `openEstimates`                                          | Number (count)                          |
| Estimates                     | `openEstimatesSubtotal`                                  | String (decimal)                        |
| Estimates                     | `soldEstimates`                                          | Number (count)                          |
| Estimates                     | `soldEstimatesSubtotal`                                  | String (decimal)                        |
| Sold By (Employee/Technician) | `estimates:#:soldBy:id`                                  | Number                                  |
| Sold By (Employee/Technician) | `estimates:#:soldBy:name`                                | String                                  |
| Sold By (Employee/Technician) | `estimates:#:soldBy:email`                               | String                                  |
| Sold By (Employee/Technician) | `estimates:#:soldBy:active`                              | Boolean                                 |
| Invoices                      | `invoices:#:id`                                          | Number                                  |
| Invoices                      | `invoices:#:summary`                                     | String                                  |
| Invoices                      | `invoices:#:referenceNumber`                             | String                                  |
| Invoices                      | `invoices:#:invoiceDate`                                 | Date                                    |
| Invoices                      | `invoices:#:dueDate`                                     | Date                                    |
| Invoices                      | `invoices:#:subTotal`                                    | Number                                  |
| Invoices                      | `invoices:#:total`                                       | Number                                  |
| Invoices                      | `invoices:#:balance`                                     | Number                                  |
| Invoices                      | `invoices:#:invoiceType:id`                              | Number                                  |
| Invoices                      | `invoices:#:invoiceType:name`                            | String                                  |
| Invoices                      | `invoices:#:customer:id`                                 | Number                                  |
| Invoices                      | `invoices:#:customer:name`                               | String                                  |
| Invoices                      | `invoices:#:termName`                                    | String                                  |
| Invoices                      | `invoices:#:depositedOn`                                 | Date                                    |
| Invoices                      | `invoices:#:createdOn`                                   | Date                                    |
| Invoices                      | `invoices:#:modifiedOn`                                  | Date                                    |
| Invoices                      | `invoices:#:adjustmentToId`                              | Number                                  |
| Invoices                      | `invoices:#:projectId`                                   | Number                                  |
| Invoices                      | `invoices:#:employeeInfo:id`                             | Number                                  |
| Invoices                      | `invoices:#:employeeInfo:name`                           | String                                  |
| Invoices                      | `invoices:#:employeeInfo:modifiedOn`                     | Date                                    |
| Invoices                      | `invoices:#:assignedTo:id`                               | Number                                  |
| Invoices                      | `invoices:#:assignedTo:name`                             | String                                  |
| Invoices                      | `invoices:#:sentStatus`                                  | String                                  |
| Invoices                      | `invoices:#:reviewStatus`                                | String                                  |
| Invoices                      | `invoices:#:syncStatus`                                  | String                                  |
| Invoices                      | `invoices:#:items:#:id`                                  | Number                                  |
| Invoices                      | `invoices:#:items:#:displayName`                         | String                                  |
| Invoices                      | `invoices:#:items:#:membershipTypeId`                    | Number                                  |
| Invoices                      | `invoices:#:items:#:serviceDate`                         | Date                                    |
| Invoices                      | `invoices:#:items:#:modifiedOn`                          | Date                                    |
| Invoices                      | `invoices:#:customFields:#:name`                         | String                                  |
| Invoices                      | `invoices:#:customFields:#:value`                        | String                                  |

The following fields are available in the **Membership opportunity** details:

| Resource                      | Field Name                                                                           | Data Type |
| ----------------------------- | ------------------------------------------------------------------------------------ | --------- |
| Membership                    | `membership:id`                                                                      | Number    |
| Membership                    | `membership:status`                                                                  | String    |
| Membership                    | `membership:followUpStatus`                                                          | String    |
| Membership                    | `membership:active`                                                                  | Boolean   |
| Membership                    | `membership:from`                                                                    | Date      |
| Membership                    | `membership:to`                                                                      | Date      |
| Membership                    | `membership:followUpOn`                                                              | Date      |
| Membership                    | `membership:cancellationDate`                                                        | Date      |
| Membership                    | `membership:nextScheduledBillDate`                                                   | Date      |
| Membership                    | `membership:billingFrequency`                                                        | String    |
| Membership                    | `membership:renewalBillingFrequency`                                                 | String    |
| Membership                    | `membership:duration`                                                                | Number    |
| Membership                    | `membership:renewalDuration`                                                         | Number    |
| Membership                    | `membership:initialDeferredRevenue`                                                  | Number    |
| Membership                    | `membership:memo`                                                                    | String    |
| Membership                    | `membership:createdOn`                                                               | Date      |
| Membership                    | `membership:modifiedOn`                                                              | Date      |
| Customer                      | `customer:id`                                                                        | Number    |
| Customer                      | `customer:name`                                                                      | String    |
| Customer                      | `customer:type`                                                                      | String    |
| Customer                      | `customer:active`                                                                    | Boolean   |
| Customer                      | `customer:doNotService`                                                              | Boolean   |
| Customer                      | `customer:contacts:#:id`                                                             | Number    |
| Customer                      | `customer:contacts:#:type`                                                           | String    |
| Customer                      | `customer:contacts:#:value`                                                          | String    |
| Customer                      | `customer:contacts:#:phoneSettings:doNotText`                                        | Boolean   |
| Customer                      | `customer:tagTypes:#:id`                                                             | Number    |
| Customer                      | `customer:tagTypes:#:name`                                                           | String    |
| Customer                      | `customer:tagTypes:#:active`                                                         | Boolean   |
| Customer                      | `customer:customFields:{name}`                                                       | String    |
| Business Unit                 | `businessUnit:id`                                                                    | Number    |
| Business Unit                 | `businessUnit:name`                                                                  | String    |
| Business Unit                 | `businessUnit:officialName`                                                          | String    |
| Business Unit                 | `businessUnit:active`                                                                | Boolean   |
| Membership Type               | `membershipType:id`                                                                  | Number    |
| Membership Type               | `membershipType:name`                                                                | String    |
| Membership Type               | `membershipType:active`                                                              | Boolean   |
| Membership Type               | `membershipType:discountMode`                                                        | String    |
| Membership Type               | `membershipType:locationTarget`                                                      | String    |
| Membership Type               | `membershipType:revenueRecognitionMode`                                              | String    |
| Membership Type               | `membershipType:createdOn`                                                           | Date      |
| Membership Type               | `membershipType:modifiedOn`                                                          | Date      |
| Location                      | `location:id`                                                                        | Number    |
| Location                      | `location:name`                                                                      | String    |
| Location                      | `location:active`                                                                    | Boolean   |
| Location                      | `location:address:street`                                                            | String    |
| Location                      | `location:address:unit`                                                              | String    |
| Location                      | `location:address:city`                                                              | String    |
| Location                      | `location:address:state`                                                             | String    |
| Location                      | `location:address:zip`                                                               | String    |
| Location                      | `location:address:country`                                                           | String    |
| Location                      | `location:address:latitude`                                                          | Number    |
| Location                      | `location:address:longitude`                                                         | Number    |
| Zone                          | `location:zone:id`                                                                   | Number    |
| Zone                          | `location:zone:name`                                                                 | String    |
| Recurring Location            | `recurringLocation:id`                                                               | Number    |
| Recurring Location            | `recurringLocation:name`                                                             | String    |
| Recurring Location            | `recurringLocation:active`                                                           | Boolean   |
| Recurring Location            | `recurringLocation:address:street`                                                   | String    |
| Recurring Location            | `recurringLocation:address:unit`                                                     | String    |
| Recurring Location            | `recurringLocation:address:city`                                                     | String    |
| Recurring Location            | `recurringLocation:address:state`                                                    | String    |
| Recurring Location            | `recurringLocation:address:zip`                                                      | String    |
| Recurring Location            | `recurringLocation:address:country`                                                  | String    |
| Recurring Location            | `recurringLocation:address:latitude`                                                 | Number    |
| Recurring Location            | `recurringLocation:address:longitude`                                                | Number    |
| Recurring Location            | `recurringLocation:zone:id`                                                          | Number    |
| Recurring Location            | `recurringLocation:zone:name`                                                        | String    |
| Sold By (Employee/Technician) | `soldBy:id`                                                                          | Number    |
| Sold By (Employee/Technician) | `soldBy:name`                                                                        | String    |
| Sold By (Employee/Technician) | `soldBy:email`                                                                       | String    |
| Sold By (Employee/Technician) | `soldBy:active`                                                                      | Boolean   |
| Payment Type                  | `paymentType:id`                                                                     | Number    |
| Payment Type                  | `paymentType:name`                                                                   | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:unusedServicesCount`                                    | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:date`                       | Date      |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:status`                     | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:membershipId`               | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:locationRecurringServiceId` | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:jobType:id`                 | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:latestRecurringServiceEvent:jobType:name`               | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:date`                         | Date      |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:status`                       | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:membershipId`                 | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:locationRecurringServiceId`   | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:jobType:id`                   | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:nextRecurringServiceEvent:jobType:name`                 | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:date`                          | Date      |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:status`                        | String    |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:membershipId`                  | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:locationRecurringServiceId`    | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:jobType:id`                    | Number    |
| Recurring Service Aggregation | `recurringServiceAggregation:recurringServiceEvents:#:jobType:name`                  | String    |

The following fields are available in the **Inbound Call opportunity** details:

| Resource | Field Name                                  | Data Type         |
| -------- | ------------------------------------------- | ----------------- |
| Call     | `call:id`                                   | Number            |
| Call     | `call:eventId`                              | String            |
| Call     | `call:webhookId`                            | String            |
| Call     | `call:direction`                            | String (Inbound)  |
| Call     | `call:callType`                             | String            |
| Call     | `call:from`                                 | String (phone)    |
| Call     | `call:to`                                   | String (phone)    |
| Call     | `call:duration`                             | String (HH:MM:SS) |
| Call     | `call:durationInSeconds`                    | Number            |
| Call     | `call:receivedOn`                           | Date              |
| Call     | `call:modifiedOn`                           | Date              |
| Call     | `call:recordingUrl`                         | String            |
| Call     | `call:voiceMailUrl`                         | String            |
| Call     | `call:reason:id`                            | Number            |
| Call     | `call:reason:name`                          | String            |
| Call     | `call:reason:lead`                          | Boolean           |
| Call     | `call:reason:active`                        | Boolean           |
| Call     | `call:agent:id`                             | Number            |
| Call     | `call:agent:externalId`                     | String            |
| Call     | `call:agent:name`                           | String            |
| Call     | `call:createdBy:id`                         | Number            |
| Call     | `call:createdBy:name`                       | String            |
| Call     | `call:campaign:id`                          | Number            |
| Call     | `call:campaign:name`                        | String            |
| Call     | `call:campaign:active`                      | Boolean           |
| Call     | `call:campaign:source`                      | String            |
| Call     | `call:campaign:otherSource`                 | String            |
| Call     | `call:campaign:medium`                      | String            |
| Call     | `call:campaign:otherMedium`                 | String            |
| Call     | `call:campaign:businessUnit`                | String            |
| Call     | `call:campaign:dnis`                        | String            |
| Call     | `call:campaign:createdOn`                   | Date              |
| Call     | `call:campaign:modifiedOn`                  | Date              |
| Call     | `call:campaign:category:id`                 | Number            |
| Call     | `call:campaign:category:name`               | String            |
| Call     | `call:campaign:category:active`             | Boolean           |
| Customer | `call:customer:id`                          | Number            |
| Customer | `call:customer:name`                        | String            |
| Customer | `call:customer:email`                       | String            |
| Customer | `call:customer:type`                        | String            |
| Customer | `call:customer:active`                      | Boolean           |
| Customer | `call:customer:balance`                     | Number            |
| Customer | `call:customer:doNotMail`                   | Boolean           |
| Customer | `call:customer:doNotService`                | Boolean           |
| Customer | `call:customer:hasActiveMembership`         | Boolean           |
| Customer | `call:customer:importId`                    | Number            |
| Customer | `call:customer:mergedToId`                  | Number            |
| Customer | `call:customer:createdBy`                   | Number            |
| Customer | `call:customer:createdOn`                   | Date              |
| Customer | `call:customer:modifiedOn`                  | Date              |
| Customer | `call:customer:address:street`              | String            |
| Customer | `call:customer:address:streetAddress`       | String            |
| Customer | `call:customer:address:unit`                | String            |
| Customer | `call:customer:address:city`                | String            |
| Customer | `call:customer:address:state`               | String            |
| Customer | `call:customer:address:zip`                 | String            |
| Customer | `call:customer:address:country`             | String            |
| Customer | `call:customer:address:latitude`            | Number            |
| Customer | `call:customer:address:longitude`           | Number            |
| Customer | `call:customer:contacts:#:id`               | Number            |
| Customer | `call:customer:contacts:#:type`             | String            |
| Customer | `call:customer:contacts:#:value`            | String            |
| Customer | `call:customer:contacts:#:memo`             | String            |
| Customer | `call:customer:contacts:#:active`           | Boolean           |
| Customer | `call:customer:contacts:#:modifiedOn`       | Date              |
| Customer | `call:customer:phoneSettings:#:phoneNumber` | String            |
| Customer | `call:customer:phoneSettings:#:doNotText`   | Boolean           |
| Customer | `call:customer:memberships:#:id`            | Number            |
| Customer | `call:customer:memberships:#:active`        | Boolean           |
| Customer | `call:customer:memberships:#:status`        | String            |
| Customer | `call:customer:memberships:#:from`          | Date              |
| Customer | `call:customer:memberships:#:to`            | Date              |
| Customer | `call:customer:memberships:#:locationId`    | Number            |
| Customer | `call:customer:memberships:#:type:id`       | Number            |
| Customer | `call:customer:memberships:#:type:name`     | String            |
| Customer | `call:customer:memberships:#:type:active`   | Boolean           |
| Customer | `call:customer:customFields:#:typeId`       | Number            |
| Customer | `call:customer:customFields:#:name`         | String            |
| Customer | `call:customer:customFields:#:value`        | String            |
| Tenant   | `call:__tenantInfo:id`                      | Number            |
| Tenant   | `call:__tenantInfo:name`                    | String            |

#### Standard Field Mapping

Hatch standard fields are mapped from ServiceTitan detail fields as detailed below.

**Job Opportunity**

<Note>
  The base object of this opportunity model is the ServiceTitan **Job**. Therefore, (as an example) the **id** field would indicate the ID of the ServiceTitan **Job** record.
</Note>

In Job opportunities, the following Hatch standard fields are mapped from ServiceTitan detail fields:

| Hatch Standard Field                                                                                                          | ServiceTitan Detail Field                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Email**                                                                                                                     | The value of the first item in the **customer:contacts** list that has **type** equal to **email**           |
| **External ID**                                                                                                               | **id**                                                                                                       |
| **External Contact ID**                                                                                                       | **customer:id**                                                                                              |
| **External Created At**                                                                                                       | **createdOn**                                                                                                |
| **External Updated At**                                                                                                       |                                                                                                              |
| *(used for Hatch opportunity sorting)*                                                                                        | *The most recent date within these fields:*                                                                  |
| **modifiedOnappointments:1:modifiedOn**                                                                                       |                                                                                                              |
| **estimates:1:modifiedOn**                                                                                                    |                                                                                                              |
| **First Name**                                                                                                                | *If there is no comma in**customer:name** :*                                                                 |
| The first word in the **customer:name** value                                                                                 |                                                                                                              |
| *If there is a comma in**customer:name** :*                                                                                   |                                                                                                              |
| All text after the first comma in the **customer:name** value                                                                 |                                                                                                              |
| **Last Name**                                                                                                                 | *If there is no comma in the **customer:name** value:*                                                       |
| Everything after the first word in the **customer:name** value                                                                |                                                                                                              |
| *If there is a comma in the **customer:name** value:*                                                                         |                                                                                                              |
| All text before the first comma in the **customer:name** value                                                                |                                                                                                              |
| **Phone**                                                                                                                     | The **value** of the first item in the **customer:contacts** list that has **type** equal to **mobilePhone** |
| *IF ABOVE IS MISSING:* The **value** of the first item in the **customer:contacts** list that has **type** equal to **phone** |                                                                                                              |

**Membership Opportunity**

<Note>
  The base object of this opportunity model is the ServiceTitan **Membership**. Therefore, (as an example) the **id** field would indicate the ID of the ServiceTitan **Membership** record.
</Note>

In Membership opportunities, the following Hatch standard fields are mapped from ServiceTitan detail fields:

| Hatch Standard Field                                                                                                      | ServiceTitan Detail Field                                                                                |
| ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Email**                                                                                                                 | The value of the first item in the **customer:contacts** list that has **type** equal to **email**       |
| **External ID**                                                                                                           | **id**                                                                                                   |
| **External Contact ID**                                                                                                   | **customer:id**                                                                                          |
| **External Created At**                                                                                                   | **createdOn**                                                                                            |
| **External Updated At**                                                                                                   |                                                                                                          |
| *(used for Hatch opportunity sorting)*                                                                                    | **modifiedOn**                                                                                           |
| **First Name**                                                                                                            | *If there is no comma in**customer:name** :*                                                             |
| The first word in the **customer:name** value                                                                             |                                                                                                          |
| *If there is a comma in**customer:name** :*                                                                               |                                                                                                          |
| All text after the first comma in the **customer:name** value                                                             |                                                                                                          |
| **Last Name**                                                                                                             | *If there is no comma in the **customer:name** value:*                                                   |
| Everything after the first word in the **customer:name** value                                                            |                                                                                                          |
| *If there is a comma in the **customer:name** value:*                                                                     |                                                                                                          |
| All text before the first comma in the **customer:name** value                                                            |                                                                                                          |
| **Phone**                                                                                                                 | The value of the first item in the **customer:contacts** list that has **type** equal to **mobilePhone** |
| *IF ABOVE IS MISSING:* The value of the first item in the **customer:contacts** list that has **type** equal to **phone** |                                                                                                          |

**Inbound Call Opportunity**

| Hatch Standard Field | ServiceTitan Detail Field                                                       |
| -------------------- | ------------------------------------------------------------------------------- |
| Email                | `call:customer:email`                                                           |
| External ID          | `call:webhookId`                                                                |
| External Contact ID  | `call:customer:id`                                                              |
| External Created At  | `call:receivedOn`                                                               |
| External Updated At  | `call:modifiedOn`                                                               |
| First Name           | Same comma/space split rule as Job & Membership applied to `call:customer:name` |
| Last Name            | Same comma/space split rule as Job & Membership applied to `call:customer:name` |
| Phone                | `call:from`                                                                     |
| Status               | `call:callType`                                                                 |

#### Creating a Job

You can create ServiceTitan jobs directly in Hatch, eliminating tab-switching, manual re-entry, and lost context. If the ServiceTitan integration is enabled,
the "Create a Job" button will appear on the right when selecting a contact, within the "Quick Actions" section. When creating a job,
you will need to select a customer and location, and provide the required information.

<img alt="" />

### What are the limitations of the integration?

* The ServiceTitan API does not provide information related to the Job's "Opportunity", so Hatch is unable to target audiences based on the follow-up date or status.

### Recommended targeting for audiences

We have a [template library](/getting-started/audience-builder/audience-templates) to help get you started on building audiences. These are what we've found works best to accomplish common use cases. Feel free to use these as a starting point for your own campaigns, but it's always wise to evaluate what targeting strategy works best with your internal processes.

#### Speed to Lead (Removal Rules)

The goal in mind here is to remove contacts from the STL campaign when a job (appointment) has been scheduled in ServiceTitan. There are a couple ways to achieve this:

<img alt="ST appt removal rules" />

### FAQ

<AccordionGroup>
  <Accordion title="Where can I find additional resources to assist with building ServiceTitan campaigns?">
    Check out our blog posts! Here are some examples:

    <ul>
      <li><a href="https://www.usehatchapp.com/blog/recurring-services-integration">Improve retention with recurring services integration</a></li>
      <li><a href="https://www.usehatchapp.com/blog/servicetitan-call-status">Create an abandoned call campaign to re-engage callers</a></li>
    </ul>
  </Accordion>

  <Accordion title="What API scopes are required by the integration, and are we able to customize them?">
    The scopes are standardized via our official ServiceTitan application so they are not able to be customized. If there are any scopes your organization does not wish Hatch to have access to, many of the features are optional and can be turned off. In that case, the integration would not access the related scopes.<br /><br />

    <b>The following <u>Read</u> scopes are required:</b>

    <ul>
      <li>Accounting: <b>Invoices, Invoice Items, Payment Types</b>, <b>Tax Zones</b></li>
      <li>CRM: <b>Booking Provider Tags</b>, <b>Bookings</b>, <b>Customers</b>, <b>Leads</b>, <b>Locations</b>, <b>Tags</b></li>
      <li>Dispatch: <b>Appointment Assignments</b>, <b>Capacity</b>, <b>Non-Job Appointments</b>, <b>Zones</b></li>
      <li>Job Planning and Management: <b>Appointments</b>, <b>Job Cancel Reasons</b>, <b>Job Hold Reasons</b>, <b>Jobs</b>, <b>Job Types</b></li>
      <li>Memberships: <b>Customer Memberships</b>, <b>Membership Types</b>, <b>Recurring Service Events</b>, <b>Recurring Services</b>, <b>Recurring Service Types</b></li>
      <li>Marketing: <b>Campaigns</b>, <b>Campaign Categories</b></li>
      <li>Sales & Estimates: <b>Estimates</b></li>
      <li>Settings: <b>Business Units</b>, <b>Employees</b>, <b>Tag Types</b>, <b>Technicians</b>, <b>User Roles</b></li>
    </ul>

    <b>The following <u>Write</u> scopes are required:</b>

    <ul>
      <li>CRM: <b>Customers</b>, <b>Leads</b>, <b>Locations</b></li>
      <li>Dispatch: <b>Capacity</b></li>
      <li>Marketing: <b>Campaigns</b></li>
      <li>Job Planning and Management: <b>Jobs, Appointments</b></li>
    </ul>
  </Accordion>
</AccordionGroup>


# Siro
Source: https://docs.usehatchapp.com/integrations/crm-field-management-systems/siro-integration

What Hatch's Siro integration is, how it works, and where to begin.

## What does the Siro integration do?

Hatch offers a native integration with Siro that you can activate within the App Marketplace (located in your Hatch workspace). This integration syncs Follow-up data from Siro to Hatch, and can also sync Hatch communications back to Siro.

While active, the Siro integration will sync new and updated Siro Follow-up data every 15 minutes. It can also update Follow-up status in Siro when communications are sent from Hatch campaigns.

To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

## How do you set up the integration?

### Requirements

You will need the following to set up the integration:

* Hatch account with manager privileges
* Siro account with admin access (the integration requires an admin user to create OAuth credentials)

### Setup Steps

<Steps>
  <Step title="Open App Marketplace">
    In Hatch, open the **App Marketplace**.
  </Step>

  <Step title="Connect Siro">
    Under the **CRMs** tab, click the Siro **Connect** button.
  </Step>

  <Step title="Start Setup">
    In the window that appears, click the **Start Setup** button.
  </Step>

  <Step title="Provide API Token">
    Follow the steps of the setup, clicking the **Next** button after each screen is completed. You will need to provide your Siro API Token during setup.
  </Step>

  <Step title="Finish Setup">
    In the final screen of the setup, click the **Finish** button.
  </Step>
</Steps>

<Note>
  When the integration is first enabled, Hatch will automatically create an OAuth App in your Siro account. This is used to securely authenticate API requests. Hatch will also sync the last 2 months of Follow-up data from Siro.
</Note>

## When does Hatch sync data to/from Siro?

### Siro → Hatch

Siro data can be synced to Hatch in the following scenarios. These options are configured during the integration setup.

<Note>
  Keep in mind that syncs occur every 15 minutes.
</Note>

* If a Follow-up record is created or updated in Siro, Hatch syncs the Follow-up record along with any associated customer data (see below for specific fields)

<Info>
  Only Follow-ups with a score higher than 3 are included by Siro. This means Hatch will only receive high-quality follow-up opportunities that Siro's AI has identified as having strong potential.
</Info>

### Hatch → Siro

Hatch communications can be synced to Siro in the following scenarios. These options are configured during the integration setup. If enabled, Hatch will update the Follow-up status to "COMPLETED" and add the communication details to the Follow-up notes.

<Note>
  Keep in mind that push communications occur instantaneously. There must be a Siro Follow-up record in Hatch at the time of the communication event in order for it to succeed.
</Note>

* When a Hatch campaign sends a text/email/voicemail to a contact
* When a contact calls or sends a text/email/voicemail to a Hatch workspace
* When a Hatch user calls or sends a text/email to a contact

## What Siro data is available in Hatch?

### Detail Field Lists

The following fields are available in the opportunity details:

**Follow-up Opportunity**

| Field                                  | Type   |
| -------------------------------------- | ------ |
| follow\_up                             | Object |
| follow\_up:repName                     | String |
| follow\_up:dateCreated                 | Date   |
| follow\_up:followupId                  | String |
| follow\_up:followupType                | String |
| follow\_up:score                       | Number |
| follow\_up:followupAction              | String |
| follow\_up:updatedAt                   | Date   |
| follow\_up:status                      | String |
| follow\_up:crmCustomer                 | Object |
| follow\_up:crmCustomer:id              | String |
| follow\_up:crmCustomer:name            | String |
| follow\_up:crmCustomer:emailAddress    | String |
| follow\_up:crmCustomer:phoneNumber     | String |
| follow\_up:context                     | Object |
| follow\_up:context:FollowupEmailHeader | String |
| follow\_up:context:FollowupTextHeader  | String |

<Tip>
  **Using Siro's AI-Generated Follow-up Messages**

  The `FollowupEmailHeader` and `FollowupTextHeader` fields contain AI-generated message content that Siro creates based on the sales call analysis. If you want to use Siro's suggested follow-up text in your Hatch campaigns, you can reference these fields using snippets like `[[Opportunity Details follow_up:context:FollowupTextHeader]]`.

  We recommend using `FollowupTextHeader` (the text message version) rather than `FollowupEmailHeader`, as the email version may contain formatting that is not fully supported in Hatch campaigns.
</Tip>

### Standard Field Mapping

Hatch standard fields are mapped from Siro detail fields as detailed below.

**Follow-up Opportunity**

<Note>
  The base object of this opportunity model is the Siro **Follow-up**. Therefore, (as an example) the **followupId** field would indicate the ID of the Siro **Follow-up** record.
</Note>

In Follow-up opportunities, the following Hatch standard fields are mapped from Siro detail fields:

| Hatch Standard Field                                       | Siro Detail Field                      |
| ---------------------------------------------------------- | -------------------------------------- |
| Email                                                      | crmCustomer:emailAddress               |
| External ID                                                | followupId                             |
| External Contact ID                                        | crmCustomer:id                         |
| External Created At                                        | dateCreated                            |
| External Updated At *(used for Hatch opportunity sorting)* | updatedAt                              |
| First Name                                                 | crmCustomer:name (first part of name)  |
| Last Name                                                  | crmCustomer:name (second part of name) |
| Phone Number                                               | crmCustomer:phoneNumber                |
| Status                                                     | status                                 |

## Configuration Options

The following options can be configured during integration setup:

* **Enabled Resources** — Choose which Siro data types to sync (Follow-ups)
* **Sync user communications with Siro Follow Up Notes** — Enable/disable pushing Hatch communications back to Siro

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Will Hatch change Follow-up statuses in Siro?">
    Yes, if you have enabled the "Sync user communications with Siro Follow Up Notes" option. When the first campaign message is sent to a contact, Hatch will update the corresponding Follow-up status to "COMPLETED" and add the message content to the Follow-up notes.
  </Accordion>

  <Accordion title="How often does the integration sync?">
    Our integration syncs every 15 minutes.
  </Accordion>

  <Accordion title="What information is pushed back to Siro?">
    When communications are sent from Hatch campaigns, the integration can update the Follow-up status to "COMPLETED" and add the message content to the Follow-up notes field in Siro. This helps sales reps track that outreach has been completed.
  </Accordion>

  <Accordion title="What happens when the integration is disconnected?">
    When the integration is disabled, Hatch will stop syncing data to and from Siro.
  </Accordion>

  <Accordion title="What Siro user permissions are required?">
    The integration requires admin access to your Siro organization. During setup, the first admin user of your organization will be used to create the OAuth credentials needed for API access.
  </Accordion>

  <Accordion title="Which Follow-ups does Hatch receive from Siro?">
    Hatch receives Follow-ups that have a score higher than 3. Siro filters these on their end, so only high-quality follow-up opportunities are sent to Hatch. The score (ranging from 1-5) indicates how promising Siro's AI considers the follow-up opportunity to be.
  </Accordion>
</AccordionGroup>


# Integrations Overview
Source: https://docs.usehatchapp.com/integrations/general/integration-overview

This article covers the different integration methods that Hatch offers.

### User Permissions

Hatch Manager permissions are required in order to access integrations.

### The Hatch App Marketplace

The Hatch App Marketplace is where you browse, install, and configure integrations — all from inside Hatch.

To access it, click **Integrations** in your workspace sidebar. From there you can:

* **Search** for integrations by name
* **Filter** by category: CRM, Leads, Other Tools, or Installed
* **Connect** a new integration by clicking its card and following the setup steps
* **View** the status of integrations you've already installed (Active, Paused, Setup Incomplete, etc.)

Once you click an integration card, you'll see what data it shares with Hatch and a link to detailed documentation. Click **Start Setup** to walk through the configuration steps specific to that integration.

<img alt="" />

### Getting Data Into Hatch

#### Native Integrations

The Hatch App Marketplace contains a number of prebuilt integrations for you to use. If you are a Hatch Manager, you can explore the apps that are popular amongst our users including CRMs, lead sources, and more.

#### Contacts API

The Contacts API can be used to push data that will create new contacts/opportunities in Hatch. Many of our lead partners utilize this API when feeding lead information to Hatch. This can also be useful if you have a data source that Hatch does not offer a native integration for. Learn more about how to use this API [here](/integrations/hatch-api).

#### Zapier

Hatch's public Zapier app can be used to create new contacts/opportunities within Hatch from many of Zapier 5000+ apps. Learn more about how to use the Contact Created trigger [here](/integrations/general/zapier-hatch-part-1-basics).

#### CSV Import

This is a useful tool for one-time imports of data such as a pre-built contact list for a specific campaign. Check out tips and tricks for using the csv importer [here](/how-to-use-hatch/contacts/importing-contacts-with-a-csv).

### Getting Data Out of Hatch

#### Webhooks

Webhooks are a common integration pattern that allow for consumption of real-time Hatch events. Learn more about the different webhook triggers that Hatch offers [here](/integrations/hatch-webhooks/webhooks-basics).

#### Zapier

Hatch's public Zapier app can be used to trigger actions when a Hatch contact is created or a Hatch contact sends or receives a communication. Learn more about how to use these triggers [here](/integrations/general/zapier-hatch-part-1-basics).

#### Bulk Export API

The Bulk Export API allows Enterprise tier customers to export BI-ready datasets for analytics and data warehouses. Learn more about the [Bulk Export API](/integrations/hatch-api/bulk-export/overview).


# Understanding your Integration
Source: https://docs.usehatchapp.com/integrations/general/understanding-your-integration

This article will help you understand the status of your integration and how to resolve any errors preventing it from syncing successfully. 

### Lead Integration Status

#### Setup Incomplete

This one pretty much speaks for itself! Further detail on this state can be viewed within the lead source setup tracker. If your integration has not moved to the Active state even after you received an expected test lead, check these steps:

* You may need to hit the "complete setup" button in the integration. At this time, the setup does not complete automatically when leads are received
* If you are unable to "complete setup", the test lead may not have the exact expected source value--in which case a revision should be requested by the lead partner.

#### Active

Your integration will appear as Active once a lead has been received with the expected source value and a user has completed the setup flow.

One distinction that needs to be made is that this status is not dynamic: it only reflects that the lead integration was at one point successfully activated, and does not reflect any subsequent errors or changes that may occur on the lead partner's side.

### CRM Integration Status

#### Setup Incomplete

This one pretty much speaks for itself! We see this on occasion if:

* Your org's Manager needed some more information to complete setup at a later time
* Your org's Manager never hit the "Finish" button after authorizing
* Someone clicked an integration setup by mistake or out of curiosity, and never deleted it

#### Active

If your Integration is in the Active state, you should have nothing to worry about! This is the expected status indicating your integration is in a healthy state.

<Note>
  An Active state does not necessarily mean the integration will never have an error or failed sync (these are naturally expected when working with APIs!), but they should be infrequent and may even resolve themselves due to our automated failure retry system.
</Note>

#### Failed Sync

A failed sync may be nothing to worry about--these things happen sometimes! It just means the last attempted sync had some error or failure, and our retry system will keep attempting until it succeeds. The integration is still actively attempting to sync information, whether or not it is successful.

<Note>
  However, if your integration is experiencing a regular state of failure or you notice information is missing, you may want to check with our Support Team to take a closer look.
</Note>

#### Paused

Your integration may become paused in two ways: manually (by user action) or automatically (by our validation process).

Our validation process evaluates if the integration meets certain requirements in regards to the authorization provided and/or necessary permissions to use the source API. These differ for each integration (we will go into more detail in the next section).

If your integration has failed the validation checks, it may result in one of these sub-statuses of Paused:

* **Invalid Credentials** - This state indicates that your integration has been paused as a result of invalid credentials. You may also have received an email and/or an in-app notification alerting you to this status. Invalid Credentials means that whatever authorization method has been provided to the integration is not valid for one reason or another. Examples of this error can include:
  * Generally incorrect or incomplete information provided (think typos or copy/paste errors)
  * Configuration error within the integration
  * A previously valid API key has been deleted or expired
  * A previously valid user has been removed from the account
* **Missing Permissions** - This state indicates that your integration has been paused as a result of missing permissions. You may also have received an email and/or an in-app notification alerting you to this status. Missing Permissions means that while the credentials used to authorize the integration are technically valid, they may not have permission to access some of the objects or APIs that the integration needs.

### How to Resolve CRM Validation Errors

These errors vary somewhat from CRM to CRM. We will review them individually here.

<Note>
  As always, feel free to reach out to our Support Team for assistance resolving these errors!
</Note>


# Zapier + Hatch Part 1: Basics
Source: https://docs.usehatchapp.com/integrations/general/zapier-hatch-part-1-basics

This is Part One of a three part series on Zapier. In this article, we’ll cover what Zapier is and a high-level overview of how it can be used in combination with Hatch. Next up: We'll cover the use cases our Zapier app enables in Part Two.

### Overview

Zapier is a popular **low-code** automation tool frequently used by individuals in the marketing industry.

While Hatch offers many native integrations and options to directly connect with many external systems, Zapier may be the easiest (or only) connection offered for some systems or lead sources.

<Note>
  **Note** : Before moving forward with a custom Zapier integration, confirm that we don’t offer a direct integration with your lead source! See the full list of our partnerships [here](https://www.usehatchapp.com/partners).
</Note>

#### Zapier Basics

A "zap" is essentially an automated workflow. A zap consists of at least two parts:

* **Triggers** - an event that initiates the zap
* **Actions** - an event that is performed by the zap

There can be steps in-between as well to create a multi-step zap: popular steps might include the Zapier formatter (to re-format inputs or outputs) or the Zapier filter (to control if a zap proceeds or what actions to take based on some input).

#### Popular Zapier Connections with Hatch

There are 1000+ Apps that you can connect to in the [Zapier Marketplace](https://zapier.com/apps). We’ve listed out a few that are most popular amongst our users here at Hatch.

If you want to try something different, just search on Zapier and see if they have an App available.

* Facebook Leads
* Nextdoor
* NinjaForms
* Hubspot Forms

### **Setup**

#### Creating a Zapier Account

In order to set up this integration, make sure you have created a Zapier Account. Create your Zapier account by [clicking here](https://zapier.com/sign-up/).

<Note>
  **Note:** Your expected volume of zap runs will determine if a free account may be sufficient for your needs or if you will need a paid subscription. Certain features may always require a paid subscription.
</Note>

#### Gain Access to Our Zapier App

Our Zapier App is now public so an invite link is not required to add a Hatch action or trigger to your zap! You can find it by simply searching "Hatch" in Zapier's app marketplace or [following this link ](https://zapier.com/apps/hatch/integrations)to our Zapier home page.

<Note>
  **Note:** The public version of the Hatch app is our most up to date version. Older, private versions may still function but are not recommended for new zaps.
</Note>

#### Authentication

In order to use Zapier with Hatch, you will need to obtain an API key from your Hatch representative or our support team (We recommend using our in-app support chat for quickest response). The API key will authorize access for a specified Hatch Organization.

### Creating a Zap

1. From the [Zapier Dashboard](https://zapier.com/app/dashboard), click **Create + Zap**.

   <img alt="" />

2. This will open the zap editor where you can create a series of steps from different triggers and actions.

   <img alt="" />

3. **Once a Hatch trigger or action has been selected, you will be prompted to authorize access to Hatch.** If you have already authorized access to your Hatch org, you can select it from a drop-down. Otherwise, connect a new account. You may authorize connections to more than one Hatch org.

   <img alt="" />

4. After clicking *Connect* , you will receive a pop-up prompting you to enter the API key obtained from Hatch support.

   <img alt="" />

5. Now you're free and clear to proceed with configuring your Zap.

6. Once your Zap has been tested successfully, it is ready to be **published** to push it live.

7. If you run into any issues during testing or after publishing, check out Zapier's articles on **[troubleshooting your zap](https://help.zapier.com/hc/en-us/articles/8496037690637-How-to-troubleshoot-errors-in-Zaps#h_01HY0J8E4VVA8708VQV6BDPJ39)**. Our support team is also here to help!

### Now that we've covered the basics, we will dive deeper into the use cases in the following articles!

**To view Part Two: Triggers and Actions, please [click here](/integrations/general/zapier-hatch-part-two-trigger-and-actions).**

**To view Part Three: Integrate your Leads, please [click here](/integrations/lead-sources/zapier-hatch-integrate-with-lead-sources).**

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Does Zapier cost money?">
    You can create 5 separate “Zaps” and run 100 “Tasks” per month for free. Essentially, you can pull 100 leads into Hatch per month before having to upgrade. See their <a href="https://zapier.com/app/billing/plans">full pricing here</a>.
  </Accordion>

  <Accordion title="How do I set up a speed to lead campaign?">
    Once a lead is sent to Hatch, that lead can be launched automatically into a campaign. Check out part 3 of our help article for more specifics.
  </Accordion>

  <Accordion title="Do you offer any direct integrations?">
    Currently, we can directly connect with <a href="/integrations/lead-sources/angi-leads-integration">Angi Leads</a>, <a href="/integrations/lead-sources/modernize-integration">Modernize</a>, and more. Check out our <a href="https://www.usehatchapp.com/partners">full list of Partnerships</a> on our website.<br /><br />
    We can also connect with <b>web forms</b> on your website.
  </Accordion>
</AccordionGroup>


# Zapier + Hatch Part Two: Triggers and Actions
Source: https://docs.usehatchapp.com/integrations/general/zapier-hatch-part-two-trigger-and-actions

In this article, we’ll go more in depth about the uses for Hatch's Zapier app

### **Triggers**

#### **New Contact**

**Description**

This trigger will listen for newly created contacts in the board of your choosing. A good use-case is if you want to also push ingested new contacts from Hatch into your own CRM.

**Use Case**

This allows Hatch to be used as an aggregation point. Instead of setting up multiple integrations with many individual lead sources to go to both Hatch, your CRM, and anywhere else you might need...you could integrate the leads sources with Hatch then used the New Contact trigger to flow those leads into your CRM.

#### **New Communication Outbound**

**Description**

This trigger will listen for  *outbound communication sent* within the board of your choosing. A good use-case for this is if you combine this with the New Communication Inbound trigger to listen for communication occurring inside your boards.

**Use Case**

This can be used to create a custom integration with your CRM to record communications in your source of truth.

#### **New Communication Inbound**

**Description**

This trigger will listen for  *inbound communication* occurring inside the board of your choosing. A good use-case for this is if you combine this with the New Communication Outbound trigger to listen for communication occurring inside your boards.

**Use Case**

This can be used to create a custom integration with your CRM to record communications in your source of truth. Another potential use case would be a custom notifications system--for example, you could send a notification in Slack.

### Actions

#### **Create Contact**

**Description**

This action will push contacts into your Hatch account.

**Use Case**

This action can be used to create a custom integration with a lead source or CRM. Check out a detailed example in [part 3](/integrations/lead-sources/zapier-hatch-integrate-with-lead-sources) of this article!

To view the first section of this article (covering Zapier basics), please click [here](/integrations/general/zapier-hatch-part-1-basics).


# Bulk Export Schema Overview
Source: https://docs.usehatchapp.com/integrations/hatch-api/bulk-export/bulk-export-schema-overview

Column-level definitions for the contact_history and conversation_items datasets.

## contact\_history fields

| Field                 | Description                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------- |
| `organization_id`     | Organization ID tied to the record.                                                                     |
| `organization_name`   | Friendly organization name.                                                                             |
| `workspace_id`        | Unique workspace identifier.                                                                            |
| `workspace_name`      | Workspace name.                                                                                         |
| `contact_history_id`  | Unique Identifier.                                                                                      |
| `campaign_id`         | Campaign identifier in Hatch.                                                                           |
| `campaign_name`       | Campaign name.                                                                                          |
| `current_lead_source` | Source assigned to the contact (e.g., `integration:salesforce`).                                        |
| `hatch_contact_id`    | Unique contact ID from Hatch.                                                                           |
| `contact_status`      | Field definitions below. Campaign engagement status (`In Progress`, `No Reply`, `Replied`, `Canceled`). |
| `campaign_stage`      | Current stage of the campaign workflow.                                                                 |
| `sales_value`         | Sales amount associated with the contact (if provided).                                                 |
| `opted_out`           | Boolean flag showing whether the contact opted out.                                                     |
| `email`               | Contact email.                                                                                          |
| `phone`               | Contact phone number.                                                                                   |
| `updated_at`          | Timestamp when the record was last updated.                                                             |
| `external_contact_id` | CRM-based customer or contact id from integrated CRM/lead source. (See Below)                           |
| `appointment_id`      | CRM-based appointment ID from integrated sources. (See Below)                                           |
| `invoice_id`          | CRM-based invoice/estimate/sale ID from integrated sources. (See Below)                                 |

<AccordionGroup>
  <Accordion title="Configuration for integrated CRM IDs">
    <p> **We are rolling these out integration by integration, so they may be null for now.** The API passess through <code>appointment\_id</code>, <code>invoice\_id</code>, and <code>external\_contact\_id</code> values directly from CRMs & lead sources integrated with Hatch. </p>

    <ul>
      <li><b>Appointment ID</b>: The field that gets passed through, will be configured through the [Reporting Settings](https://docs.usehatchapp.com/getting-started/reporting/legacy-reporting), under Appointments.</li>
      <li><b>Invoice ID</b>: The field that gets passed through, will be configured through the [Reporting Settings](https://docs.usehatchapp.com/getting-started/reporting/legacy-reporting), under Sales.</li>
      <li><b>External Contact ID</b>: This field is not configurable, and based on Hatch's own internal CRM mapping.</li>
    </ul>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="Contact status definitions">
    <p>Hatch calculates <code>contact\_status</code> values as campaigns progress. Use these labels to group performance inside your BI tools:</p>

    <ul>
      <li><b>In Progress</b>: The contact is actively moving through automated steps and can still receive follow-ups.</li>
      <li><b>No Reply</b>: Automation completed without a response from the contact.</li>
      <li><b>Replied</b>: The contact responded, so the automation ended and the conversation moved to your team.</li>
      <li><b>Canceled</b>: The contact was removed manually or due to rules (invalid info, opt-out, competing campaign, etc.).</li>
    </ul>
  </Accordion>
</AccordionGroup>

## conversation\_items fields

| Field                 | Description                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------- |
| `organization_id`     | Organization ID tied to the conversation.                                                       |
| `organization_name`   | Organization name.                                                                              |
| `workspace_id`        | Workspace ID.                                                                                   |
| `workspace_name`      | Workspace name.                                                                                 |
| `id`                  | Unique identifier for the message.                                                              |
| `conversation_id`     | Conversation identifier.                                                                        |
| `contact_id`          | Contact identifier for the participant.                                                         |
| `actor_type`          | Who sent the message (`contact`, `hatch_user`, automated agent, etc.).                          |
| `actor_id`            | Unique ID for the actor (user/contact/bot).                                                     |
| `category`            | Message category (e.g., `sms`, `email`, `call`).                                                |
| `type`                | Message payload type (text, voicemail drop, etc.).                                              |
| `direction`           | Inbound vs. outbound.                                                                           |
| `body`                | Message body text (if applicable).                                                              |
| `delivery_status`     | Latest delivery status from the provider.                                                       |
| `status_history`      | Serialized status change history for troubleshooting delivery failures.                         |
| `chatbot_disposition` | The disposition a chatbot applied to the overall conversation (same for each conversation item) |
| `send_at`             | Scheduled send time for delayed/scheduled messages.                                             |
| `is_scheduled`        | Indicates whether the item was scheduled.                                                       |
| `provider_name`       | External provider handling delivery (e.g., Twilio).                                             |
| `provider_message_id` | Provider-specific identifier for the message.                                                   |
| `mongo_id`            | Unique database source identifier.                                                              |
| `updated_at`          | Timestamp when the message item was last updated.                                               |

<CardGroup>
  <Card title="Bulk Export API Overview" href="/integrations/hatch-api/bulk-export/overview" />
</CardGroup>


# Bulk Export API
Source: https://docs.usehatchapp.com/integrations/hatch-api/bulk-export/overview

Export BI-ready Hatch datasets for analytics and data warehouses.

<CardGroup>
  <Card title="Bulk Export Schema Overview" href="/integrations/hatch-api/bulk-export/bulk-export-schema-overview" />
</CardGroup>

## Authentication & onboarding

* Access is limited to **Enterprise** tier customers—ask your Hatch Account Manager to enable the Bulk Export API for your organization.
* A **Manager** must create a reporting API key in **Settings → API Keys**.
* Send the key in an `Authorization: Bearer <api-key>` header on every request.

## Rate limits & constraints

* Data is updated nightly and will only contain the previous day's data
* Up to **1 export every 5 minutes** per organization.
* Maximum **100 exports per organization per day**.
* Date ranges may not exceed **180 days** into the past.
* Maximum payload size: **100 MB** uncompressed. Larger requests return `413 Payload Too Large`.

## GET `/export-data`

**Method & Path:** `GET https://bulk-export-api.usehatchapp.com/api/v1/export-data`

Request a downloadable ZIP archive containing newline-delimited JSON for either the `contact_history` or `conversation_items` dataset.

Exports default to newline-delimited JSON, but you can also request a CSV version by adding `&output_format=csv` to the end of the query url.

<Tip>
  Prefer to explore interactively? Use the Swagger UI linked above to send test requests, toggle the output format, and view sample payloads.
</Tip>

### Query parameters

| Name            | Required | Description                                                                                                     |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `data_source`   | Yes      | Dataset to export. Allowed values: `contact_history`, `conversation_items`.                                     |
| `start_date`    | Yes      | Inclusive start date in `YYYY-MM-DD`. Earliest supported date depends on your contracted data retention window. |
| `end_date`      | Yes      | Inclusive end date in `YYYY-MM-DD`. Must be on/after `start_date` and within 180 days of it.                    |
| `output_format` | No       | Defaults to `json`. Set to `csv` to receive a CSV file (still packaged inside the ZIP).                         |

### Example request

```bash theme={null}
curl -L "https://bulk-export-api.usehatchapp.com/api/v1/export-data?data_source=contact_history&start_date=2025-10-30&end_date=2025-11-04&output_format=csv" \
  -H "Authorization: Bearer <api-key>" \
  -o contact_history_2025-10-30_2025-11-04.zip
```

### Response

* **Status:** `200 OK`
* **Headers:** `Content-Type: application/zip`
* **Body:** Binary ZIP archive containing one data file—`.json` for the default JSONL export or `.csv` when `output_format=csv`.
* **File names:** `{data_source}_{start_date}_{end_date}.zip` → `{data_source}_{start_date}_{end_date}.json` (or `.csv`).

```text theme={null}
conversation_items_2024-02-01_2024-02-07.zip
└── conversation_items_2024-02-01_2024-02-07.json
    {"conversation_id": "c_123", "actor_type": "contact", "direction": "inbound", "..."}
    {"conversation_id": "c_124", "actor_type": "hatch", "direction": "outbound", "..."}
```

| Status | Meaning                                                                |
| ------ | ---------------------------------------------------------------------- |
| `200`  | Export succeeded and returned records.                                 |
| `204`  | Request succeeded but the specified range did not contain any rows.    |
| `400`  | Invalid query parameters (e.g., bad date format, unsupported dataset). |
| `401`  | Missing or invalid API key.                                            |
| `413`  | Result exceeded the 100 MB size limit. Narrow the date range.          |
| `429`  | Rate limit exceeded (1 export every 5 minutes / 100 exports per day).  |
| `500`  | Unexpected server error. Retry with backoff.                           |

### Operational guidance

* Use the schema overview to inspect columns before mapping the export into your warehouse.
* Poll `GET /export-data` on a schedule that respects both the **5-minute spacing** rule and **daily cap**.
* Monitor `413` responses—if they occur frequently, reduce the date window (for example, export weekly instead of monthly).
* Store exported ZIP archives in an object store (S3, GCS, Azure Blob) before processing so you can re-run failed ETL jobs without hitting rate limits.

### Next steps

1. Review the [Bulk Export API integration guide](/integrations/hatch-api/bulk-export/bulk-export-schema-overview) for more information on the available export data.
2. Request the Bulk Export API to be enabled for your organization through your Hatch Account Team.
3. Check for API Keys under **Integrations → API Keys**
4. Schedule exports at a cadence that aligns with the published limits (one every 5 minutes, 100 per day).


# Custom Integration Example: Talkdesk
Source: https://docs.usehatchapp.com/integrations/hatch-api/custom-integration-example-talkdesk

Learn how to create a Hatch contact from your Talkdesk interactions

### Use Case

Integrating your Hatch account with Talkdesk opens up a variety of possibilities. For instance, you may want to follow up on specific phone interactions with a text message.

One effective use case is implementing an abandoned call campaign. When your team misses a call, you can configure Talkdesk to automatically send that information over to Hatch as a new opportunity. This allows you to promptly engage with the customer via an instant launch campaign, demonstrating your commitment to their needs and ensuring they feel valued.

### Setup

There are three main steps to setting up a custom Hatch integration from your Talkdesk account. On the Hatch side, there is a small bit of configuration required (the same key steps you would take for any [custom API setup](/integrations/hatch-api)).

#### Hatch Setup

1. Navigate to the Integrations marketplace.

2. Generate a custom source value. The source value should meaningfully identify where the data has originated from. In this case, we will recommend the source "custom:talkdesk"

<img alt="" />

3. Generate an API Key to be used by the new Talkdesk source.

4. You will need these values later when configuring the connection in Talkdesk.

#### Create a Custom Connection in Talkdesk

In this step you will configure the Hatch url where Talkdesk will send data to. Talkdesk has a detailed explanation on this [here](https://docs.talkdesk.com/docs/configuring-a-custom-connection).

Head to your Talkdesk account, and add a custom integration.

<img alt="" />

This will bring you to the configuration screen.

<img alt="" />

The key pieces you will need from Hatch are the same steps you will take with any custom integration to the Hatch Contacts API:

1. Name the connection (recommended: Hatch)
2. Describe the purpose of the connection
3. Input the Hatch API url to base path: **[https://api.usehatchapp.com/v1/contacts](https://api.usehatchapp.com/v1/contacts)**
4. Select No Authentication as the authentication type (we will authenticate via the headers)
5. Under Other Settings, add a header. This header will provide the API key for the Hatch API.
   1. The field should be and the value "Bearer (API KEY)" where you should replace (API KEY) with the key generated in your Hatch account.

#### Create a Custom Action in Talkdesk

Now that we have a connection, we can configure custom actions that utilize that connection. Talkdesk has a detailed article [here](https://docs.talkdesk.com/docs/configuring-a-custom-action), but we will cover the Hatch specific configurations.

Click Action and then Add Action

<img alt="" />

This will take you to the action configuration screen.

<img alt="" />

1. Name your Action (recommended Create Hatch Contact)
2. Describe your Action (what is the goal or the end result?)
3. Configure the relative path:
   1. change the method from **GET** to **POST** because we are sending data out from Talkdesk and posting it into Hatch.
   2. the path field should remain blank-- there is no relative path needed on top of the base url that was already configured in the connection
4. The path preview should still look like **[https://api.usehatchapp.com/v1/contacts](https://api.usehatchapp.com/v1/contacts)**
5. Path parameters: none required
6. Path parameters: none required
7. Path parameters: none required
8. Path parameters: none required
9. Configure Output-- here is where we define the data that will be sent in or out of Talkdesk
10. Input is not applicable in this scenario, so leave this blank
11. Output is the data that needs to be sent to the Hatch API. Below are two example data schemas that you can copy and paste into the Output schema with minimal adjustment.

**Basic Data Schema**
Use this schema if you only care about sending the bare minimum data needed to create a Hatch contact.

```
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Output",
  "required": [
    "externalId", "phoneNumber", "source"
  ],
  "properties": {
    "externalId": {
      "type": "string",
      "title": "Contact Id"
    },
    "status": {
      "type": "string",
      "title": "Call Status"
    },
   "email": {
      "type": "string",
      "title": "Contact Email"
    },
    "phoneNumber": {
      "type": "string",
      "title": "Contact Phone"
    },
    "firstName": {
      "type": "string",
      "title": "Contact First Name"
    },
    "lastName": {
      "type": "string",
      "title": "Contact Last Name"
    },
    "source": {
      "type": "string",
      "title": "Source for Hatch"
    }
  }
}
```

**Advanced Data Schema**

Use this schema if you care about including some additional details from the Talkdesk record. Details might include useful context that will inform the Hatch user (or bot) or can be used as a snippet in the messaging.

<Note>
  ***Note*** : You will need to make some adjustments to this schema to reflect the custom details you require. Replace the bolded \*\**example* \*\*fields and values with your custom fields and values. You can append additional details properties following the same pattern.
</Note>

```
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Output",
  "required": [
    "externalId", "phoneNumber", "source"
  ],
  "properties": {
    "externalId": {
      "type": "string",
      "title": "Contact Id"
    },
    "status": {
      "type": "string",
      "title": "Call Status"
    },
   "email": {
      "type": "string",
      "title": "Contact Email"
    },
    "phoneNumber": {
      "type": "string",
      "title": "Contact Phone"
    },
    "firstName": {
      "type": "string",
      "title": "Contact First Name"
    },
    "lastName": {
      "type": "string",
      "title": "Contact Last Name"
    },
    "source": {
      "type": "string",
      "title": "Source for Hatch"
    },
    "details": {
      "type": "object",
      "title": "Custom Details",
      "properties": {
        "**example 1** ": {
          "type": "string",
          "title": "**Example 1 Name** "
        },
        "**example 2** ": {
          "type": "string",
          "title": "**Example 2 Name** "
**}** ,
        "additionalProperties": false
            }
    }
  }
}
```

#### Configure Automation in Talkdesk

In this step you will tie together all these pieces and choose a trigger(s) that will automatically initiate your custom action and send the data to the Hatch connection.

In the Hatch connection, add an Automation.

<img alt="" />

This will take you to the Automation configuration

<img alt="" />

1. Give the Automation a name.
2. Choose a trigger event.
   1. Example: Trigger when a Talkdesk call is dispositioned
3. Choose an action that should be completed after the trigger. The action in this case will be the custom action to send data to Hatch.
4. Apply **[filters](https://docs.talkdesk.com/docs/automations-filters)** as necessary. The filters will determine if there are certain additional criteria to determine if the trigger event should proceed.
   1. Example: It may not be productive to send data to Hatch when every call is dispositioned. Maybe only some dispositions are relevant.
5. Map the related data from the event trigger into the data output schema we created earlier. The fields that will be sent to Hatch are on the right side and are the result of that schema.

   1. The mapped event variables can be dragged from the left side of the screen into the Hatch fields.
   2. In the "source" field, hand-write the custom source that you setup in Hatch earlier. From our example, this was "custom:talkdesk" so we will plug that value in.

<img alt="" />

#### You're Done!

In order to go live, you will need to enable the Automation on the main page.


# Custom Sources
Source: https://docs.usehatchapp.com/integrations/hatch-api/custom-sources

An explanation of custom sources that can be used with Hatch's public API

### Contact source basics

Every contact in Hatch comes from somewhere. To keep track of where your data originated, Hatch stores a **source** value on every contact in your workspace.

<img alt="" />

Hatch automatically adds the source value to contacts that are created through an integration or directly in the app. You will see a unique value for every source.

For example: contacts created through our Salesforce integration always have a source value of **integration:salesforce**. Similarly, contacts created through a CSV import always have a source value of **imported** (like you see in the screenshot above).

### Custom sources

When contacts are sent through Hatch's public API, Hatch has no way to automatically determine the source of the contact. Instead, a **custom source** is necessary for Hatch to create the contact.

Custom sources are sources that you define. They appear in your contact data just like any other source in Hatch.

<img alt="" />

Each custom source has a unique **API Source Name**.

<img alt="" />

When sending contacts through the public API, you will need to provide the API source name in your request.

[Click here to learn more about using the Hatch API.](/integrations/hatch-api)

### Creating and managing custom sources

You can create and manage your custom sources in the **Custom Sources** tab of the App Marketplace.

<img alt="" />

#### How to create a new custom source

Follow these steps to create a new custom source:

1. Click the **Create Custom Source** button
2. Enter a label for your custom source
3. Hatch will automatically generate the **API Source Name**
4. Click the **Create Custom Source** button

<Tip>
  The generated **API Source Name** must be unique for your existing custom sources
</Tip>

#### How to delete an existing custom source

Follow these steps to delete an existing custom source:

<Warning>
  Once a custom source is deleted, you will no longer be able to use its **API Source Name** when sending data through the API
</Warning>

1. Locate the custom source in the list
2. Click the custom source's delete button
3. When the confirmation appears, click **Yes, delete**


# Hatch API Reference
Source: https://docs.usehatchapp.com/integrations/hatch-api/hatch-api-reference

Complete reference documentation for the Hatch API including authentication details and the list of available endpoints

<Tip>
  If you are just looking for an API endpoint reference, [check out our Swagger documentation](https://api.usehatchapp.com/v1/docs#/).
</Tip>

### API basics

Hatch's public API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API has predictable resource-oriented URLs, accepts [JSON-encoded](http://www.json.org/) request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Our API uses [API keys](https://en.wikipedia.org/wiki/API_key) to authenticate requests. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

### Creating and managing API keys

Before using the API, you will need to create an API key. You can create and manage your API keys in the **API Keys** tab of the App Marketplace.

<img alt="" />

The key itself is hidden by default. To view a previously-created API key, click the **Show** button. You can also click the **Copy** button to copy the API key to your clipboard.

#### How to create a new API key

Follow these steps to create a new API key:

1. Click the **Create API Key** button
2. Enter a label for your **API key**
3. Click the **Create API Key** button

#### How to delete an existing API key

Follow these steps to delete an existing API key:

<Warning>
  You will no longer be able to send API requests with an API key once it is deleted
</Warning>

1. Locate the API key in the list
2. Click the API key's delete button
3. When the confirmation appears, click **Yes, delete**

### Authenticating requests

Authentication to the API is performed via [Bearer Authentication](https://swagger.io/docs/specification/authentication/bearer-authentication/). You must send an API token in the **Authorization** header when making requests:

```
    Authorization: Bearer `<token>`
```

So, as an example:

```
    Authorization: Bearer af13791e-1fa9-3bae-c42f-c3e123ae7a22
```

### Sending contact data

When you send contact data into Hatch, you are required to provide a valid source\*\*\*\* value in the body of the request. You can view and manage your custom sources in the App Marketplace custom sources tab.

<img alt="" />

Once you have created a custom source, you can use its **API Source Name** as the **source** value in your request.

<Warning>
  Once a custom source is deleted, you will no longer be able to use its **API Source Name** when sending data through the API
</Warning>

[Click here to learn more about custom sources.](/integrations/hatch-api/custom-sources)

### Errors

Hatch uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the **2xx** range indicate success. Codes in the **4xx** range indicate an error that failed given the information provided (e.g., a record was not found, a required parameter was omitted, etc.). Codes in the **5xx** range indicate an error with Hatch's servers (these are rare).

### Endpoints

This is an embedded version of our [Swagger endpoint documentation](https://api.usehatchapp.com/v1/docs#/) which contains an example of the expected data schema.

<Tip>
  Tip: The fields provided in the "details" object are simply examples of fields you can send. The details fields are fully customizable so you may omit or send fields at your discretion.
</Tip>

### FAQ

<AccordionGroup>
  <Accordion title="Does the API have a rate limit?">
    Yes-- the rate limit is 100 requests per 10 seconds.
  </Accordion>
</AccordionGroup>


# New Lead API (legacy)
Source: https://docs.usehatchapp.com/integrations/hatch-api/new-lead-api-legacy

This article covers the basics of our Standard API including a general overview, the setup steps, and some frequently asked questions.

<Tip>
  This is our legacy public API. To read about our newer public API, [click here](/integrations/hatch-api).
</Tip>

### Overview

Hatch’s standard API allows your business to send lead information into Hatch from any source that can support a POST API endpoint.

Through our integration, leads sent to the API endpoint are instantly pulled into Hatch and placed into your Hatch campaign (if applicable) using text, email, and voicemail communication.

#### Here's an example of how it could be used

In this example, the Standard API is being used to receive leads from a "contact us" form on a company's website.

1. First, a potential customer fills out the "contact us" form, providing their name, phone number, and email.
2. When the form is submitted on the company website, the website sends a POST request to the Hatch Standard API (this API request is detailed below).
   1. This API request contains all of the customer's contact information that was submitted through the website form.
3. Hatch receives the customer's contact information and creates a new contact in the Hatch workspace.
4. The contact is instantly added to a matching Hatch campaign and the first message is sent immediately to the customer.
5. Once the customer replies to the automated message, the contact is moved to the Hatch board and the conversation can continue with a real person from the company.

### **How To Set Up**

<Warning>
  This setup requires that you have experience with web APIs and sending API requests. **You may need assistance from your development team.**
</Warning>

1. Confirm with your development team that your software or website can support the specifications listed below.
2. Speak with your Hatch Customer Success Manager or [contact support](mailto:support@usehatchapp.com) to collect the following pieces of information that are required to send API requests:

   1. Your **Department ID**
   2. Your **Hatch API Key**
3. Use the specifications below to send a POST request to the Hatch Standard API endpoint URL. Make sure to replace the placeholders for **Department ID** and **Hatch API Key** with the values you retrieved in step 2.
4. Once configured, speak with your Hatch Customer Success Manager or [contact support](mailto:support@usehatchapp.com) to configure a Hatch campaign to launch your incoming contacts.

#### Endpoint URL

Send a **POST** request to this endpoint:

```
    https://app.usehatchapp.com/api/webhooks/{Department ID}/newlead
```

#### Request Headers

<Warning>
  Keep your Hatch API Key secret. **Do not place these request headers in your website HTML or anywhere public.**
</Warning>

```
    X-API-KEY: **`{Hatch API Key}`**
     Content-Type: application/json
```

#### Request Body Properties

The following properties are **required** for every request:

| **Property Name** | **Property Type** | **Description**                                                                                             |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------------------------------- |
| phoneNumber       | String            | The contact's phone number.<br />*Only required when "email" is not included.*                              |
| email             | String            | The contact's email.<br />*Only required when "phoneNumber" is not included.*                               |
| source            | String            | The external source assigned to the Hatch contact.<br />*This should be the same for all of your requests.* |

The following properties are **optional** for every request:

| **Property Name** | **Property Type**            | **Description**                                                                      |
| ----------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
| firstName         | String                       | The contact's first name                                                             |
| lastName          | String                       | The contact's last name                                                              |
| id                | String                       | The ID from your system                                                              |
| contactID         | String                       | The contact's ID from your system                                                    |
| status            | String                       | The contact's status from your system (can be whatever is helpful for your workflow) |
| createdAt         | Timestamp String (see below) | The contact's creation timestamp from your system                                    |
| updatedAt         | Timestamp String (see below) | The contact's updated timestamp from your system                                     |

<Note>
  You may also add **any additional custom properties** to the request body that you want included on your Hatch contact.

  Your custom properties may send any valid JSON value. Multidimensional values will be flattened upon consumption.

  **All additional custom properties will have their values imported as strings.** If you need these imported as another data type, speak with your Hatch Customer Success Manager or [contact support](mailto:support@usehatchapp.com).
</Note>

Here is an example request body:

```
    {
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "8048675309",
      "email": "testjohndoe@test.com",
      "source": "my_company_name",
      "status": "my_lead_status",
      "contactID": "1001123123900",
      "createdAt": "2020-01-02T15:04:05-0700",
      "myCustomNestedObject": {
        "color": "red",
        "model": "toyota",
      },
    }
```

#### Timestamp Strings

When you send a **createdAt** or **updatedAt** value in your request, the value must use one of the following formats:

```
    2006-01-02T15:04:05-0700
```

```
    2006-01-02T15:04:05-07:00
```

### How To Verify

Once you have set up the connection, requests sent to the Standard API will automatically create contacts in Hatch. You can test this easily by performing the following steps:

1. Send a request to the Standard API with some test data.
   1. For example, if you connected your webform to the Standard API, simply submit some test data using your webform.
2. Open the contacts page in your Hatch workspace.
3. Verify that one of the contacts in the list contains the test data that you submitted.
4. If you have a configured campaign, verify that the contact was launched into the campaign.
   1. If you are unsure about this step, speak with your Hatch Customer Success Manager or [contact support](mailto:support@usehatchapp.com).

### **Frequently Asked Questions**

<AccordionGroup>
  <Accordion title="Why is instant lead engagement important?">
    Instant lead engagement (also known as "Speed to Lead") is extremely important when it comes to your new leads. The first company to get to a new lead wins!
  </Accordion>

  <Accordion title="Who can use the Standard API?">
    The Standard API is available to all Hatch users. There is no additional fee to use the endpoint. Our team just needs to work with you to provide the necessary information to get started.
  </Accordion>

  <Accordion title="How long does it take to get set up?">
    Once your team has configured your software or website to send to the Standard API, you're ready to go! Just make sure that you talk to your Customer Success Manager about what campaign you want to put those incoming leads into.
  </Accordion>

  <Accordion title="What other lead source or Speed to Lead integrations do you offer?">
    We offer lead engagement integrations with many other lead sources. Check out the app marketplace in your Hatch workspace or visit [our website](https://www.usehatchapp.com/partners) to see the full list.
  </Accordion>
</AccordionGroup>


# Creating & Managing Webhooks
Source: https://docs.usehatchapp.com/integrations/hatch-webhooks/creating-managing-webhooks

Learn how to configure a webhook in Hatch to directly hit a downstream system or use Zapier as a 'no code' option.

You can use webhooks to send information to systems such as your CRM or dialer. You can use webhooks to send information to almost any external system. For example, you might want to update your CRM to reflect that a contact has opted out of text messages in Hatch.

If you want to learn more about what webhooks are and how you can use them in Hatch, check out [Webhook Basics](/integrations/hatch-webhooks/webhooks-basics) before proceeding.

<img alt="Screenshot 2024-08-07 at 2.49.03 PM" />

### Configure your webhook

1. Navigate to the App Marketplace within Hatch, then click on the Webhooks tab
2. Create a new webhook by clicking Add Webhook
3. A Webhook Name, Event Trigger, and Endpoint URL are required to save your webhook
   1. You may attach multiple event triggers to a single webhook
   2. You may optionally configure headers if required by your endpoint
      1. **Note**\*\* the content-type of the Hatch payload will always be **application/json** and the related header will be automatically added to the request.
   3. As you select Event Triggers, you will see a preview of the payload that will be sent for that event
4. Upon saving, your webhook will be active and ready to start sending new events to your specified URL

<Note>
  Note: You can return to this page at any point to deactivate, edit, or delete your newly created webhook.
</Note>

<img alt="Screenshot 2024-08-07 at 2.21.47 PM" />

### Send event via Zapier

If you do not have a developer team to set up a webhook in your downstream system, sending events via Zapier is a good, "no code" option.

1. Configure your webhook as described above through step 3
2. Open Zapier and create a New Zap
3. In the App Event, select Webhooks by Zapier
4. In the Event dropdown, select Catch Raw Hook
5. Copy the Webhook URL Zapier provides and set that as your Endpoint URL in Hatch
6. Finish configuring your webhook, save, and make sure it is set to active
7. Trigger a test of your webhook by completing the appropriate action in Hatch depending on your event triggers (e.g., if you are testing an opt-out webhook, find a test Contact and opt them out of communications)
8. Return to Zapier and click Test Trigger to see the request details
9. The rest of the Zapier setup depends on where you want to send this event data so you should select the appropriate Action based on your destination system

### Optional: webhook verification

Hatch uses public key encryption as an extra security measure: Hatch uses a private key to sign the webhooks and a public key has been provided so that you may verify the authenticity of the requests at your endpoint, if you so choose. A single public key is valid for all webhooks within your Hatch Org.

Hatch will send the key `hatch-webhook-verification` in the header.

<Note>
  Below is an example (in elixir) of how to decode the key:

  decoded\_signature = Base.decode64!(header\_value) :crypto.verify(:eddsa, :none, request\_body, decoded\_signature, \[public\_key, :ed25519])
</Note>

### Managing webhooks

In an ideal world, webhooks would be set-it-and-forget-it...but unfortunately, that may not be the case 100% of the time. Here's some tips and resources to assist with testing and managing webhooks in Hatch.

#### Implementing Multiple Hatch Departments

Most Hatch data, as it relates to contacts, is contained in Hatch within a department (which has 1 or many workspaces attached to it). If your Hatch organization has been separated into more than one department, each with its own set of data, it is important to note that each department also has its own set of integrations-- this includes webhooks.

#### Deactivate/Reactivate

If you're experiencing some configuration or system issues, it may be useful to temporarily pause your webhook while troubleshooting or making adjustments. Then, you can reactivate it when ready.

#### Execution History

Hatch will retain execution logs for up to 30 days. These logs are a good place to start if you are noticing any issues, such as missing data. The logs are filterable by date, status, and event type.

In the event that an execution is in a `failed` status you can view more detail about the attempted request by clicking the arrow on the right.

* If Hatch was unable to complete the execution, an Error message will show
* If Hatch was able to complete the execution but unable to successfully deliver the request at the webhook endpoint, the Status Code (400, 401, etc) may clue you into the reason delivery failed

<img alt="Screenshot 2024-08-08 132348" />

#### Retries

Hatch will attempt to send the request to the specified endpoint 10 times. After 10 failed attempts, the execution status will be considered officially failed.


# Webhooks Basics
Source: https://docs.usehatchapp.com/integrations/hatch-webhooks/webhooks-basics

This article will review the basic concepts of webhooks and how to use them to get data our of Hatch.

<Tip>
  This reference article covers the basics of webhooks to give you the building blocks you need to create your own. Looking for steps on how to create a webhook in Hatch? Refer to [Creating a webhook](/integrations/hatch-webhooks/creating-managing-webhooks).
</Tip>

### What are Webhooks?

Webhooks are a way for one application to send real-time information to another whenever a certain event happens. Imagine it as a phone call: when something specific occurs, like a new message on a chat app, the app can "call" another app to let it know about the new message. This happens instantly and without you having to check manually.

Webhooks are powerful tools that enable real-time communication between applications, enhancing automation and reducing manual effort. By understanding how they work and their benefits, businesses and developers can leverage webhooks to create more integrated and responsive systems.

### How do Webhooks Work?

* **Event Triggering** : A webhook starts with an event in an application, like a new order placed in an online store or a new comment on a blog.

* **HTTP Request** : Once the event occurs, the application makes a special kind of request (HTTP POST request) to a unique URL provided by another application or service.

* **Receiving and Processing** : The receiving application gets this request and processes the data sent with it. For example, if it's a new order, the receiving application might update inventory or send a confirmation email.

### Key Concepts to Understand

* **URL Endpoint** : This is like a specific phone number that the sending app knows to call when an event happens. It's where the data will be sent.

* **Payload** : This is the data that gets sent with the request. It could be information about the event itself, like details of a new order or the content of a new comment.

* **HTTP Request Methods** : Webhooks typically use HTTP POST requests to send data. This means they send data securely and efficiently over the internet.

### Why Use Webhooks?

* **Real-Time Updates** : Instead of checking for updates manually, webhooks allow applications to receive updates instantly as they happen.

* **Automation** : They automate processes between different applications, reducing manual work and improving efficiency.

* **Integration** : Webhooks help different applications work together seamlessly, like notifying a messaging app of new data in a project management tool.

### Use Cases in Hatch

* **Opt-Out:** Triggered when a contact opts out of texts by replying STOP or END, or
  when a Hatch user manually opts the contact out of communications in the UI
* **Opt-In:** Triggered when a contact opts back into texts by replying START
* **Contact Created:** Triggered when a new contact is created in Hatch
* **Contact Edited:** Triggered when contact information is edited in Hatch
* **Contact in Campaign:** Triggered when a contact receives the first message in a messaging campaign
* **Assistant Conversation Completed:** Triggered when a Hatch AI assistant bails out, discards, or completes a successful conversation. Can also share answers to interactions for any of those outcomes.
* **Assistant Appointment Scheduled:** Triggered when a Hatch AI assistant successfully schedules an appointment during a conversation.
* **Contact (Email or Phone) Expired:** Triggered when the email or phone of a [contact with temporary information](/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch) expires
* **Contact Call Dispositioned:** Triggered when a call with a contact is dispositioned.
* **Campaign Third Party Launched:** Triggered when a contact is successfully launched into a third-party campaign.
* **Campaign Third Party Failed:** Triggered when a contact fails to launch into a third-party campaign.


# ActiveProspect
Source: https://docs.usehatchapp.com/integrations/lead-sources/activeprospect-integration

ActiveProspect is a lead aggregator and lead optimization platform that delivers qualified leads to home services businesses. Below is a description of the process on how to properly get them connected.

#### How it Works

ActiveProspect delivers leads into Hatch via webhook. Once setup is complete, ActiveProspect sends new leads to Hatch, and Hatch
creates a Contact and Opportunity record, which can be launched into a Speed to Lead campaign. Leads flow one-way (ActiveProspect → Hatch).

At minimum, the lead's full name is captured (required). Email address is captured when present.

#### **Setup Instructions**

When you connect ActiveProspect from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates
the third-party coordination for you. Clicking *Connect* on the ActiveProspect card will configure your workspace and contact
ActiveProspect on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the ActiveProspect lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to ActiveProspect's implementation team
   asking them to begin delivering your leads. You
   can review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When ActiveProspect opens the setup request email, the read receipt is recorded (a tooltip notes that read status may
     be inaccurate if ActiveProspect blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:active-prospect`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your ActiveProspect leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email ActiveProspect myself?">
    No. The Setup Tracker sends the request email to ActiveProspect's implementation team automatically when you start the
    connection. You'll be able to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="ActiveProspect hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether ActiveProspect has opened our setup email. If 24 hours have passed and leads
    still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from ActiveProspect?">
    Hatch captures the lead's full name (required) and email address (when provided) from each ActiveProspect lead. If you
    need additional fields parsed or mapped, reach out to our support team and we can review what's possible.
  </Accordion>

  <Accordion title="Can Hatch send a reply or status update back to ActiveProspect?">
    No. The integration is one-way (ActiveProspect → Hatch). All outreach to the lead happens through your Speed to Lead campaign in Hatch.
  </Accordion>
</AccordionGroup>


# Angi Ads
Source: https://docs.usehatchapp.com/integrations/lead-sources/angi-ads-integration



In this article, we’ll cover the basics of how to integrate with Angi Ads including what it does, how to set it up, and frequently asked questions.

### **Integration Overview**

Hatch's integration with Angi Ads (fka Angie's List) allows your business to win the game of "speed to lead".

Through our integration, leads from Angi Ads are instantly pulled into Hatch and put into a Hatch campaign using text, email and voice communication.

#### **Here’s how it works:**

First, a contact fills out a lead form on Angie's List.

<img alt="" />

> *Here is an example of a form being filled out on Angie's List.*

Once the form is submitted, Hatch receives that lead information and you can find those leads on your Contacts page. You can see all of the Lead details inside of the contact card.

<img alt="" />

> *This is a test contact. You can see the "Source" comes over as "Angie's List Quote Request" for Angie's List leads. All fields collected on your lead form will be shown in Hatch.*

For speed-to-lead, we recommend adding contacts instantly into a campaign within Hatch. The contact receives a message that looks like this:

<img alt="" />

> *Here you can see the message Mary was sent after she filled out the lead form on Angie's List.*

When the contact responds to the message, your Hatch user will be able to respond from their Board.

<img alt="" />

> *Here you can see the message Mary sent popped up on the Hatch Board.*

### Setup Instructions

1. Contact the Hatch support team to get started. We'll need the following information:
   * **Which Hatch board(s)** you would like leads to come to
2. A Hatch team member will use this information to provide you with the Hatch **url endpoint** and the **API** key for the integration (this key is not currently publicly accessible).
3. Navigate to the Angi Business Center: this is where you will add the webhook integration: [https://office.angieslist.com/app/webhooks/](https://office.angieslist.com/app/webhooks/) (replace `*ANGI ID*` with your actual Angi ID in the URL path)
4. Evaluate your needs in terms of the Angi Ads integration: Do you only need leads to flow into Hatch or do you also need leads to flow to other integrations?

   1. ***If you only need to send leads to Hatch,*** add a simple webhook in your Angi Ads account using the **url** and the **API key** Hatch support has provided to you. Angi has provided detailed instructions on how to achieve this [**here**](https://intercom.help/angi/en/articles/7116174-setting-up-api-integration-with-angi-ads), the gist of it is below:
      1. the Hatch url is this, replace `{DEPARTMENT-ID}` with your ID: `https://app.usehatchapp.com/api/webhooks/{DEPARTMENT-ID}/angieslist?`
      2. data type: JSON
      3. Authentication type: send API key in header
      4. add an email address to receive notifications
   2. **If you need to send leads to multiple integrations**, use Zapier as an intermediary to setup multiple webhooks. Angi has provided detailed instructions on how to achieve this [**here**](https://intercom.help/angi/en/articles/9454500-integrating-angi-ads-with-hatch).
5. During the setup process, do not skip the testing steps to verify successful integration! And don't forget to hit save/publish.
6. Once the integration is successful, you will need to create a campaign, audience, and workflow to target these leads.
   1. Your target audience should look something like this:

<img alt="" />

<Note>
  **Note** : This integration will only put future leads into a campaign.
</Note>

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why is instant lead engagement important?">
    Speed to Lead is extremely important when it comes to new leads. Learn more about Instant Lead Engagement [here](/getting-started/intro-to-hatch/what-is-speed-lead).
  </Accordion>

  <Accordion title="Why have my Angi Ads leads stopped flowing into Hatch?">
    Angi Ads' direct webhook connection only supports a single url endpoint. So if you added a new connection (for example to a CRM) then it would replace an existing Hatch integration. Vice versa, if you had an existing CRM integration and replaced it with Hatch your leads will no longer flow into your CRM.<br /><br />
    Please refer to the documentation on how to use Zapier to setup multiple connections with your Angi account. Alternatively, you could also use Hatch's webhooks to send new contacts from Angi into Hatch and then into your CRM--check that out [here](/integrations/hatch-webhooks/webhooks-basics)!
  </Accordion>

  <Accordion title="What other Instant Lead Engagement Integration do you offer?">
    We offer lead engagement integrations with [Modernize](/integrations/lead-sources/modernize-integration), and more. To see the full list, check out [our website](https://www.usehatchapp.com/partners).
  </Accordion>
</AccordionGroup>


# Angi Leads
Source: https://docs.usehatchapp.com/integrations/lead-sources/angi-leads-integration



In this article, we’ll cover the basics of our integration with Angi Leads (fka HomeAdvisor) including what it does, how to set it up, and frequently asked questions.

Note: If you're not a Hatch user but want to learn more about Angi Integration, head to our [Angi Integration](https://www.usehatchapp.com/integrations/angi) page.

### **Integration Overview**

Hatch's integration with Angi Leads allows your business to win the game of "speed to lead".

Through our integration, leads from Angi Leads are instantly pulled into Hatch and put into a Hatch campaign using text, email and voice communication.

<Note>
  **Angi Subscriptions** follow the same integration process as Angi Leads. The setup instructions below apply to both Angi Leads and Angi Subscriptions.
</Note>

#### **Here’s how it works:**

First, a contact fills out a lead form on Angi.

<img alt="" />

> *Here is an example of a form being filled out on Angie's List.*

Once the form is submitted, Hatch receives that lead information and you can find those leads on your Contacts page. You can see all of the Lead details inside of the contact card.

<img alt="Screenshot 2024-12-10 182945" />

> *This is an example contact. You can see the "Source" comes over as "angileads:leads". All fields collected on your lead form will be shown in Hatch including your SPID and the task name which may be useful for more targeted campaigns.*

For speed-to-lead, we recommend adding contacts instantly into a campaign within Hatch. The contact receives a message that looks like this:

<img alt="" />

> *Here you can see the message Mary was sent after she filled out the lead form on Angie's List.*

When the contact responds to the message, your Hatch user will be able to respond from their Board.

<img alt="" />

> *Here you can see the message Mary sent popped up on the Hatch Board.*

### Setup Instructions

The Angi integration is easy to activate, all you need is Hatch Manager permissions.

1. Visit the Hatch Integrations panel, it will bring you to the Hatch App Marketplace
2. Click "configure" on the Angi app.
3. In the configuration wizard, you will enter your Angi Leads SPID number(s). This is required in order to proceed to "Start Setup", it helps the Angi team complete the request without delay or confusion.
   * If you have more than one Angi Leads account, enter comma separated values in the text box
     <img alt="" />
4. After clicking "Start Setup", an email will be sent to the Angi team to enable the lead feed to Hatch. This email will contain the information to locate your account(s) and the necessary API Key.
5. Additionally, a default Angi campaign, audience, and workflow will be created to help you get started.
6. The Angi app will record if/when a lead is received to confirm activation of the integration. If a lead has not been received within 24 hours, you can generate a follow-up request to Angi right from the app marketplace.
   <img alt="" />

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why is instant lead engagement important?">
    Speed to Lead is extremely important when it comes to new leads. Learn more about Instant Lead Engagement [here](/getting-started/intro-to-hatch/what-is-speed-lead).
  </Accordion>

  <Accordion title="I'm using Angi Ads, will this integration work for me?">
    No, Angi Ads and Angi Leads are integrated separately for the time being. Please check out our [Angi Ads help article](/integrations/lead-sources/angi-ads-integration) for more detail on how to set that up.
  </Accordion>

  <Accordion title="How long does it take to get set up?">
    Barring any issues locating your account, the integration is typically activated same day. Once activated, new leads will start importing into Hatch but you will need to turn on your Angi workflow for leads to start flowing into a Hatch campaign.
  </Accordion>

  <Accordion title="What other Instant Lead Engagement Integrations do you offer?">
    We offer lead engagement integrations with [Modernize](/integrations/lead-sources/modernize-integration) and more. To see the full list, check out [our website](https://www.usehatchapp.com/partners).
  </Accordion>
</AccordionGroup>


# Contractor Appointments
Source: https://docs.usehatchapp.com/integrations/lead-sources/contractor-appointments-integration

Contractor Appointments is a lead source that delivers pre-qualified home services appointments to contractors. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

Contractor Appointments delivers leads into Hatch via webhook. Once setup is complete, new leads are sent to Hatch, and Hatch parses the lead and creates a Contact and
Opportunity record, which can be launched into a Speed to Lead campaign.

Hatch captures the following fields from each Contractor Appointments lead: first name, last name, and email (required), plus
phone number and ZIP code when provided.

#### **Setup Instructions**

When you connect Contractor Appointments from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that
automates the workspace setup and partner coordination for you. Clicking *Connect* on the Contractor Appointments card will
configure your workspace and contact Contractor Appointments (or your designated forwarding source) on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow) wired to the Contractor Appointments lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to coordinate lead delivery. You can review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step*
   to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * The setup request email's read receipt is recorded when the recipient opens it (a tooltip notes that read status may
     be inaccurate if read receipts are blocked).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:contractor-appointments`** have been
     received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Contractor Appointments leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email Contractor Appointments myself?">
    No. The Setup Tracker sends the setup request email automatically when you start the connection. You'll be able to review
    exactly what was sent — and to whom — inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Leads haven't started arriving — what should I do?">
    The *Receive Leads* step shows you whether the setup request email has been opened. If 24 hours have passed and leads
    still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge the recipient directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from Contractor Appointments?">
    Hatch captures first name, last name, and email (all required), plus phone number and ZIP code when included on the lead.
    If you need additional fields parsed or mapped, contact our support team and we can review what's possible based on the format of the leads being forwarded.
  </Accordion>
</AccordionGroup>


# Google Local Services Ads (LSA)
Source: https://docs.usehatchapp.com/integrations/lead-sources/google-local-services-ads-lsa-integration

Sync your Google LSA leads into Hatch and message them back inside the LSA conversation

## How does the Hatch + LSA integration work?

Connecting Hatch to Google LSA does two things:

1. **Brings your LSA leads into Hatch** as contacts and opportunities, so they can be launched into a Speed to Lead campaign the moment they arrive.
2. **Puts the Google LSA conversation inside Hatch.** Messages your lead sends through Google LSA appear in your Hatch Workspace, and replies you send from Hatch — manually, from a campaign, or from your Hatch AI agent — are delivered back into the same Google LSA conversation thread.

<Steps>
  <Step title="The lead reaches out">
    A customer contacts your business from your Google LSA ad — by sending a message or by calling.
  </Step>

  <Step title="Hatch replies instantly inside Google LSA (message leads)">
    For message leads, Hatch sends your configured auto-reply into the Google LSA conversation right away, so the lead knows you've received their request and Google credits your business with a fast response.

    <img alt="Google LSA auto-reply configuration" />

    <Note>
      Auto-replies are sent for **message leads only**. Phone call leads have no message thread to reply into, so they receive no auto-reply.
    </Note>
  </Step>

  <Step title="Hatch syncs the lead">
    Hatch creates the contact and a Lead opportunity, then launches them into your designated Speed to Lead campaign.
  </Step>

  <Step title="The conversation continues in Hatch">
    Anything the lead sends back through Google LSA shows up in your Hatch Workspace as an inbound message and notifies your team. Replies your team sends from the LSA app also appear, so the whole thread is in one place.
  </Step>

  <Step title="Reply from Hatch — or let AI do it">
    Your team can reply directly from the Hatch conversation using the **Google LSA** channel. Those replies are also posted into the Google LSA conversation.
  </Step>
</Steps>

***

## Integration Setup

<Steps>
  <Step title="Connect Hatch to Google LSA">
    1. Navigate to the **App Marketplace** within your Hatch account
    2. Filter by "Lead Source" to find the Google LSA integration
    3. Click the **Connect** button
    4. In the OAuth window, allow access to your Google Ads account

    <Warning>
      **Admin access required.** Authorize with a user that has **Admin** permission on every Google Ads account you plan to connect. Accounts where you only have Standard access cannot be linked, and you'll be emailed about the ones that failed.
    </Warning>
  </Step>

  <Step title="Select your accounts">
    You'll see the Google Ads accounts your user can reach, each labeled with its account name, customer ID, and timezone. Select the ones you want to receive leads from.

    <Warning>
      **Manager accounts are not supported.** Hatch links individual business accounts only. Manager (MCC) accounts are filtered out of the list automatically — if you manage several businesses through an MCC, each business account appears separately.
    </Warning>
  </Step>

  <Step title="Assign each account to a workspace">
    For each Google LSA account connected to Hatch, you will be asked to assign each account to one of your Hatch workspaces. Choose the workspace by selecting the dropdown for each Google LSA account.
  </Step>

  <Step title="Configure lead sync and your auto-reply">
    Turn on lead syncing, then enable the auto-responder and set its message. The auto-reply matters for two reasons:

    1. **It sets expectations** — the lead knows you received their request and that you'll follow up directly.
    2. **It protects your ranking** — Google displays your average response time on your ad and favors fast responders. Because the auto-reply is posted inside Google LSA, Google counts it.
  </Step>

  <Step title="Account linking completes automatically">
    When setup finishes, Hatch links each selected Google Ads account so Google can deliver leads in real time:

    * **Hatch sends a linking invitation** for each selected account.
    * **Hatch accepts it on your behalf**, using the Admin access you authorized.
    * **Google emails you** about the link. These messages are expected and confirm the integration is being configured.
    * **Real-time delivery begins** as soon as the link is active.

    Accounts that are already linked are detected and left alone, so re-running setup is safe.

    <Tip>
      **What to expect**: two emails from Google —

      1. A pending request notification (sent immediately)
      2. A confirmation that your account has been linked to Hatch
    </Tip>

    **Email 1: Pending request to link your account**

    <img alt="Google Ads pending invite email" />

    **Email 2: Account linked confirmation**

    <img alt="Google Ads account linked confirmation email" />
  </Step>

  <Step title="Build your audience and campaign">
    Set up the audience and workflow that launches your Google LSA leads into a Speed to Lead campaign. If you'd like your team to reply inside Google LSA, add a **Google LSA** step to that campaign.
  </Step>
</Steps>

***

## Google LSA v1 vs v2

**v2 is the standard integration.** All new Google LSA integrations are set up on v2 automatically — there is nothing to opt into.

| Capability                         | v1 (`integration:google-lsa`)  | v2 (`integration:google-lsa-v2`)                           |
| ---------------------------------- | ------------------------------ | ---------------------------------------------------------- |
| **Lead delivery**                  | Polled on a recurring schedule | Real-time                                                  |
| **Lead types received**            | Message leads only             | Message, phone leads                                       |
| **Contacts created for**           | Message leads                  | All lead types, whenever Google provides a tracking number |
| **Auto-reply**                     | Message leads                  | Message leads                                              |
| **Inbound message sync**           | Polled (about every 2 minutes) | Real-time                                                  |
| **Sending messages from Hatch**    | Supported                      | Supported                                                  |
| **Rate this Lead**                 | Supported                      | Supported                                                  |
| **Google Ads permission required** | Standard                       | **Admin** on every selected account                        |

<Tip>
  **Currently on v1? Reach out to your Account Manager to move to v2.** The upgrade gets you real-time lead delivery, richer lead detail, and instant message sync instead of polling.
</Tip>

***

## Google LSA messaging

### How it works

LSA leads entering Hatch via Google LSA will now be provided with a Google tracking number, instead of an actual phone number. Since these numbers cannot be messaged via SMS, Hatch utilizes the Google messaging API to message these leads directly.
This also allows conversations to be synced between Hatch and Google LSA, so conversations sync across both platforms. Additionally, as Google is no longer providing email addresses for leads, the Hatch contact created from a message lead will not have a valid email address.

Due to API requirements, only **message leads** can receive messages via Google messaging. For reaching out to phone leads, more information can be found below.

### Messages you receive

| What arrives in Hatch                    | Details                                                                                    |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Messages from the lead**               | Delivered to the contact's Hatch conversation as an inbound message                        |
| **Replies your team sent outside Hatch** | Business replies sent from the Google LSA app also appear, so the thread stays complete    |
| **All text channels**                    | Google may route a conversation over message, SMS, or WhatsApp — Hatch ingests any of them |

### Messages you send

You can send a Google LSA message from:

#### A conversation

Pick Google LSA in the message-type selector. The channel is only selectable for contacts that came from Google LSA.

<Steps>
  <Step title="Select LSA message-type">
    <img alt="Google LSA convo zoomed in" />
  </Step>

  <Step title="Type your message">
    <img alt="Google LSA message type" />
  </Step>
</Steps>

To learn more about messages in Hatch, navigate to [Messaging Overview](/getting-started/messaging/overview#messaging).

#### A campaign

Add a Google LSA step. Please note LSA leads can only be messaged via the LSA campaign type.

<Steps>
  <Step title="Select LSA campaign type">
    <img alt="Google LSA zoomed in" />
  </Step>

  <Step title="Fill out your campaign message">
    <img alt="Google LSA campaign step" />
  </Step>
</Steps>

<Warning>
  **Google LSA messages are plain text only.** Attachments are not supported and will cause the message to fail.
</Warning>

<Warning>
  **Ringless voicemail** is not currently supported for LSA Campaigns as it's not supported by Google LSA’s messaging system
</Warning>

### Extensions

If you want to call a Google LSA message lead, you will be required to enter an extension code before speaking with the customer. This code will be displayed in the Hatch conversation
with the contact.

<img alt="Google LSA extension top" />

<Note>
  The hourglass will stick to the number wherever it goes, including the contacts page. When the number is updated, the hourglass will go away. If the number is never updated, after 60 days it will appear 'expired.'
</Note>

### Phone leads

If you are on Google LSA v2, you will also receive LSA phone leads in Hatch. While phone leads cannot be messaged via the Google messaging feature,
you can create separate audiences and campaigns specifically targeting phone leads. These phone leads can be contacted by reaching out via phone call and providing the associated extension number, as described above.

***

## Monitoring inbound leads

The App Marketplace includes an inbound dashboard for Google LSA showing every lead Hatch has received, with:

* **Source** and **lead type** (message, phone call)
* **Date received** — when Google created the lead
* **Message back out** — when Hatch's auto-reply was delivered, so you can confirm your response time
* The **raw payload** from Google, expandable for troubleshooting

Because this dashboard lists every lead Google sent, it's the fastest way to confirm whether a missing lead ever reached Hatch — and, if it did, whether it arrived without the contact details needed to create a contact.

***

## Troubleshooting

### "Your Google LSA V2 integration needs attention"

If one or more accounts can't be linked, Hatch emails you a list of the affected accounts and the reason for each.

<Note>
  **Your integration stays connected.** Only the accounts listed in the email are affected — every account that linked successfully keeps delivering leads in real time.
</Note>

**Example notification:**

<img alt="Google LSA permissions error email" />

| Reason shown                                               | What it means                                                                                              | How to fix it                                                                  |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **Insufficient permissions, admin access required**        | The authorizing user doesn't have Admin on that Google Ads account                                         | Grant Admin access in Google Ads, then reconfigure the integration             |
| **Account is already linked to too many manager accounts** | Google caps how many manager (MCC) accounts a single Ads account can be linked to, and that cap is reached | Remove an existing manager link in Google Ads to free a slot, then reconfigure |
| **Authorization expired or invalid**                       | The Google connection is no longer valid                                                                   | Reconnect the integration through the App Marketplace                          |
| **No accessible Google Ads accounts configured**           | No accounts were selected, or none are reachable by the authorized user                                    | Reconfigure and select at least one business account                           |

**To resolve:** fix the account-level issue in Google Ads, then click **Reconfigure** in the email (or re-authenticate from the App Marketplace). If you don't intend to use an account, uncheck it in your configuration to stop the notifications. If problems persist, contact your Account Manager or Hatch support.

***

## Rating a Lead

You can send Google your assessment of a lead's quality without leaving Hatch. Open the lead's conversation, then in **Quick Actions** click **Rate this Lead**.

Choose a rating — Very Satisfied, Satisfied, Neutral, Dissatisfied, or Very Dissatisfied — and then a reason:

* **Satisfied ratings:** Booked Customer, Likely Booked Customer, Service Related, High Value Service, or Other
* **Dissatisfied ratings:** Geo Mismatch, Job Type Mismatch, Not Ready To Book, Spam, Duplicate, Solicitation, or Other

Choosing "Other" lets you add a comment. Your feedback is sent to Google, which uses it to improve lead quality and may issue credits for poor-quality leads.

<img alt="Google LSA rate lead example" />

***

## FAQ

<AccordionGroup>
  <Accordion title="Which lead types does Hatch create contacts for?">
    On v2, message and phone leads create a contact and a Lead opportunity, as long as Google provides an email address or a phone number for the lead.

    On v1, only message leads are delivered to Hatch at all. If you're missing your phone call leads, that's the reason — talk to your Account Manager about moving to v2.
  </Accordion>

  <Accordion title="Does every lead get an auto-reply?">
    No. Auto-replies are sent for **message leads only**, because message leads are the only ones with a conversation thread in Google LSA to reply into.
  </Accordion>

  <Accordion title="How fast will my message reach my Google LSA leads?">
    On v2, Google pushes each lead to Hatch the moment it's created, so your auto-reply and your Speed to Lead campaign fire immediately.

    On v1, leads are picked up on a polling schedule, so there's a delay of minutes between the lead arriving in Google LSA and landing in Hatch. If you're still on v1, reach out to your Account Manager about moving to v2.
  </Accordion>

  <Accordion title="Will conversations that take place in Hatch show up in Google LSA?">
    Yes. Google LSA messages you send from Hatch — manually, from a campaign step, or from your Hatch AI agent — are posted into the lead's Google LSA conversation.

    This is a change from earlier versions of the integration, where only the auto-reply was written back to Google.
  </Accordion>

  <Accordion title="Do replies my team sends from the Google LSA app show up in Hatch?">
    Yes. Business replies sent outside Hatch are ingested into the Hatch conversation so the thread stays complete. Messages Hatch itself sent aren't duplicated.
  </Accordion>

  <Accordion title="Can I send photos or attachments over Google LSA?">
    No. Google LSA messages are text only. A message with an attachment will fail to send — use SMS or email for those.
  </Accordion>

  <Accordion title="Why do I need Admin permissions?">
    Real-time delivery requires linking your Google Ads account to Hatch's manager account, and only an Admin can accept that link.
  </Accordion>

  <Accordion title="Why did I receive an email from Google about account linking?">
    Setting up the integration links your Google Ads account to Hatch so Google can deliver leads in real time. Google sends transactional emails for both the pending request and the completed link — both are expected.

    Disconnecting Hatch does not automatically unlink your Google Ads accounts. Remove the link in your Google account settings if you want it fully undone.
  </Accordion>

  <Accordion title="Why don't I see my manager account in the account selection list?">
    Manager (MCC) accounts are filtered out by design — Hatch links individual business accounts. If you manage several businesses through an MCC, each one appears in the list separately.
  </Accordion>

  <Accordion title="Why are leads coming in without a first or last name?">
    Google LSA doesn't require the name fields on their form, and Google may show these leads as "Potential Customer" in your LSA notifications.

    Hatch accepts leads without a name, but if your campaign uses the `[[Contact First Name]]` or `[[Contact Last Name]]` snippets the message will read awkwardly. Either remove those snippets from your Speed to Lead campaign or set a snippet fallback.
  </Accordion>

  <Accordion title="A lead is in my Google LSA dashboard but not in Hatch. Why?">
    The most common reason is that Google sent no email address and no phone number with the lead. Hatch needs at least one of the two to create a contact, so leads with neither are recorded but never become contacts.

    Check the inbound dashboard in the App Marketplace — if the lead is listed there, Hatch received it and the contact details were missing. If it isn't listed at all, the account may not be linked correctly; check for a "needs attention" email and see the Troubleshooting section above.
  </Accordion>
</AccordionGroup>


# Hatch Chat Overview
Source: https://docs.usehatchapp.com/integrations/lead-sources/hatch-chat-overview



In this article, we’ll cover the basics of Hatch Chat including what it does, how to set it up, and frequently asked questions.

### **Hatch Chat Overview**

Hatch Chat allows you to connect with your customers directly from your website.

It is *similar* to a traditional webchat, except when the customer submits a message, the conversation continues on their cell phone over text messaging. This allows you to continue the conversation with the contact **even after they leave your website**.

#### Here’s how it works

The Hatch Chat widget is added to your website using a simple-to-install snippet of code. Once set up, the pop-up looks like this and can appear on every page where you put the code snippet.

<img alt="hatch app - hatch chat greeting-1" /> *Here is an example of Hatch Chat on our Website.*

When a customer requests to chat, it will ask them to add their cell number and their message.

<img alt="hatch app - hatch chat send a message-1" />

If they visit your site on their mobile device, it will automatically open their text messaging function and pre-populate a message.

*Here is an example of Hatch Chat on a Mobile Device.* \
<img alt="Hatch-Chat-1-1" />\
Once they submit the message, there are two ways you can handle these inbound messages.

1. You can have them **show up in your Hatch workspace, in the INBOX column** , where you can easily text those customers back.
2. You can set it up to have those **contacts immediately launch into a campaign** , ensuring an instantaneous response.

In Hatch, you will see the message submitted through the website pop into the inbox column.

If their number is already in your Contacts, it will show their name instead of just a number.

For the customer, they will see the first message you send back pop up on their phone. Make sure to introduce yourself!

We also recommend putting the customer into a campaign for gentle follow up. See our suggested campaign verbiage [here](/integrations/lead-sources/hatch-chat-overview).

### **Setting Up**

Setting Up Hatch Chat is easy! It just might require a little work from the team that handles your website.

#### Creating the Snippet

Before installing the snippet, you'll need to modify the snippet below, so it's unique to your account.

1. Determine **which Hatch Workspace** you would like the leads to come into.
   1. Open up the workspace in another tab.
   2. The **Workspace\_ID** is the string of seemingly random letters and numbers in the URL of the workspace.  <img alt="workspace_id_example" />
2. Copy the snippet below and replace **Workspace\_ID with your Hatch Workspace Number.**

**Snippet**

```text theme={null}
<script type="text/javascript">function _loadHatchScripts(t){try{var e=document,n=e.createElement("script");n.src=t,n.async=!0,n.defer=!0,n.dataset.hatchid="WORKSPACE_ID_GOES_HERE";var a=e.getElementsByTagName("script")[0];a.parentNode.insertBefore(n,a)}catch(t){}}window.addEventListener("WebComponentsReady",function(){_loadHatchScripts("<https://hatch-javascript.s3.amazonaws.com/hatchChat-app.js>")}),"attachShadow"in Element.prototype?document.dispatchEvent(new CustomEvent("WebComponentsReady",{bubbles:!0})):_loadHatchScripts("<https://unpkg.com/@webcomponents/webcomponentsjs@2.2.10/webcomponents-bundle.js>");</script>
```

#### **Installing the Snippet**

Once you have your unique snippet created, then it is time to install Hatch Chat. We recommend using Google Tag Manager or installing the snippet directly into your `<head>` tag on your website.

Google Tag Manager

1. Go to [tagmanager.google.com](http://tagmanager.google.com/) and login to your account.
2. Select **Add a New Tag**.
3. Name the tag “Hatch" (or whatever you'd like).
4. Select **Choose a Tag Type** and choose **Custom HTML**.
5. Paste the Hatch Chat Snippet you generated above. Make sure "WORKSPACE\_ID\_GOES\_HERE” is replaced with the board number you’d like messages to go to.
6. Scroll down and select **Triggering**. We want to create a trigger that tells the tag to fire (load) after the page is fully loaded. This will ensure all your site’s content loads before Hatch Chat.
7. Select **+** to add a new trigger.
8. Name your trigger “Window Loaded” and select **Choose a trigger type**.
9. Select **Window Loaded**.
10. Click **Save**
11. When you’re ready to deploy the tag on your website, hit **Submit**.
12. **Confirm that Hatch Chat is displaying on your site**. Once you have the snippet installed, the Hatch Chat widget will be visible on the bottom right of your website.

Head Tag

1. **Identify the `<head>` tag section** of your website.
2. **Paste the Hatch Chat Snippet** you generated above. Make sure "WORKSPACE\_ID\_GOES\_HERE” is replaced with the your workspace ID you’d like messages to go to, as outlined above.
3. **Publish** your changes.
4. **Confirm that Hatch Chat is displaying on your site**. Once you have the snippet installed, the Hatch Chat widget will be visible on the bottom right of your website.

#### Customizing the Chat Image

The default friendly face associated with Hatch chat is that of one of our co-founders, Bill! While *we* think he has a great face, we realize you might want to personalize this image to your own business.

The Hatch chat image can now be customized in the Hatch workspace settings:

1. Navigate to the appropriate workspace
2. Navigate to the workspace configuration
3. Click Edit under the General settings
4. Upload a new image <img />
5. Don't forget to Save!

### **Putting Contacts into Campaign**

You can use Instant Lead Engagement to allow Hatch to **automatically** follow up with contacts with text and/or voicemail after they fill out the form on your website.

Here is our recommended verbiage for Hatch Chat follow-up:

**Touch 1, When Lead Comes In** Hi, this is **\[\[User First Name]]** with **\[\[Details Company Name]]**. Thanks for texting us! Can you tell me more about what you need help with? If you'd rather not talk over text, reply END.

**Touch 2, Day 2 at 10:00 AM** Thanks again for texting us the other day. I didn’t hear back from you, text me back with what you need help with, I'm here to help. **Touch 3, Day 3 at 2:00 PM** Hi **\[\[Contact First Name]]** , it's **\[\[Details Company Name]]**. Text me back when you have some time so I can help you out! **Touch 4, Day 5 at 9:00 AM** Hi **\[\[Contact First Name]]** , it's **\[\[Details Company Name]]**. If you ever need help with anything, text me at this number!

Work with your Account Manager to customize your messaging based on the needs of your business.

### **Frequently Asked Questions**

<AccordionGroup>
  <Accordion title="How do I adjust the user image that shows?">
    The image that shows in the Hatch Chat Embed can be changed in the Hatch workspace configuration settings. Refer to the [setup instructions](/integrations/lead-sources/hatch-chat-overview#customizing-the-chat-image) above.
  </Accordion>

  <Accordion title="Can I adjust the verbiage in the pop-up?">
    At this time, the verbiage can not be adjusted.
  </Accordion>

  <Accordion title="Can I change the color of the pop-up on my site?">
    At this time, the color can not be changed.
  </Accordion>

  <Accordion title="Can I change the position or size of the pop-up on my site?">
    At this time, the position or size can not be changed.
  </Accordion>
</AccordionGroup>


# HelloProject
Source: https://docs.usehatchapp.com/integrations/lead-sources/hello-project-integration

HelloProject is a lead source that connects home services contractors with qualified homeowner leads. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

HelloProject delivers leads into Hatch via webhook. Once setup is complete, HelloProject sends new leads to a unique
Hatch ingestion address, and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect HelloProject from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates the
third-party coordination for you. Clicking *Connect* on the HelloProject card will configure your workspace and contact
HelloProject on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (a group, a campaign, and a workflow)
   wired to the HelloProject lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to HelloProject asking them to begin delivering your leads to a unique Hatch ingestion address. You can
   review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When HelloProject opens the setup request email, the read receipt is recorded (a tooltip notes that read status may
     be inaccurate if HelloProject blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:helloproject`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your HelloProject leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email HelloProject myself?">
    No. The Setup Tracker sends the request email to HelloProject automatically when you start the connection. You'll be able
    to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="HelloProject hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether HelloProject has opened our setup email. If 24 hours have passed and leads
    still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if HelloProject's mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from HelloProject?">
    Hatch captures the standard lead identification fields (such as name, email, and phone) when they're present.
  </Accordion>

  <Accordion title="Can Hatch send a reply or status update back to HelloProject?">
    No. The integration is one-way (HelloProject → Hatch). All outreach to the lead happens
    through your Speed to Lead campaign in Hatch.
  </Accordion>
</AccordionGroup>


# Home Appointments
Source: https://docs.usehatchapp.com/integrations/lead-sources/home-appointments-integration

Home Appointments is a lead source that delivers pre-set in-home appointments to home services contractors. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

Home Appointments delivers leads into Hatch via webhook. Once setup is complete, Home Appointments sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect Home Appointments from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that
automates the third-party coordination for you. Clicking *Connect* on the Home Appointments card will configure your
workspace and contact Home Appointments on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the Home Appointments lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to Home Appointments asking them to begin delivering your leads. You can review
   the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When Home Appointments opens the setup request email, the read receipt is recorded (a tooltip notes that read status
     may be inaccurate if Home Appointments blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:home-appointments`** have been
     received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Home Appointments leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email Home Appointments myself?">
    No. The Setup Tracker sends the request email to Home Appointments automatically when you start the connection. You'll be
    able to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Home Appointments hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether Home Appointments has opened our setup email. If 24 hours have passed and
    leads still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read
    receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from Home Appointments?">
    Hatch captures the standard lead identification fields (such as name, email, phone, and appointment details) when they're
    present.
  </Accordion>
</AccordionGroup>


# HomeBuddy
Source: https://docs.usehatchapp.com/integrations/lead-sources/home-buddy-integration

HomeBuddy is a lead source that connects homeowners with home improvement contractors for projects like roofing, siding, and windows. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

HomeBuddy delivers leads into Hatch via webhook. Once setup is complete, HomeBuddy sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect HomeBuddy from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates the
third-party coordination for you. Clicking *Connect* on the HomeBuddy card will configure your workspace and contact
HomeBuddy on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the HomeBuddy lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to HomeBuddy asking them to begin delivering your leads. You can review the exact *To*, *CC*, and message body that Hatch sent. Click
   *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When HomeBuddy opens the setup request email, the read receipt is recorded (a tooltip notes that read status may be
     inaccurate if HomeBuddy blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:homebuddy`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your HomeBuddy leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email HomeBuddy myself?">
    No. The Setup Tracker sends the request email to HomeBuddy automatically when you start the connection. You'll be able to
    review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="HomeBuddy hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether HomeBuddy has opened our setup email. If 24 hours have passed and leads still
    haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>
</AccordionGroup>


# HomeYou
Source: https://docs.usehatchapp.com/integrations/lead-sources/home-you-integration

HomeYou is a lead source that connects homeowners with home improvement and remodeling contractors. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

HomeYou delivers leads into Hatch via webhook. Once setup is complete, HomeYou sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect HomeYou from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates the
third-party coordination for you. Clicking *Connect* on the HomeYou card will configure your workspace and contact HomeYou on
your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the HomeYou lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to HomeYou asking them to begin delivering your leads. You can review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When HomeYou opens the setup request email, the read receipt is recorded (a tooltip notes that read status may be
     inaccurate if HomeYou blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:homeyou`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your HomeYou leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email HomeYou myself?">
    No. The Setup Tracker sends the request email to HomeYou automatically when you start the connection. You'll be able to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="HomeYou hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether HomeYou has opened our setup email. If 24 hours have passed and leads still
    haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="Can Hatch send a reply or status update back to HomeYou?">
    No. The integration is one-way (HomeYou → Hatch). All outreach to the lead happens through your Speed to Lead campaign in Hatch.
  </Accordion>
</AccordionGroup>


# Keyword Connects
Source: https://docs.usehatchapp.com/integrations/lead-sources/keyword-connects-integration

Keyword Connects (an EverConnect company) is a lead source that delivers home improvement and remodeling leads to contractors. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

Keyword Connects delivers leads into Hatch via webhook. Once setup is complete, Keyword Connects sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect Keyword Connects from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates
the third-party coordination for you. Clicking *Connect* on the Keyword Connects card will configure your workspace and
contact Keyword Connects (EverConnect) on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the Keyword Connects lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to the Keyword Connects / EverConnect team asking them to begin delivering your leads. You can review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to
   continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When Keyword Connects opens the setup request email, the read receipt is recorded (a tooltip notes that read status
     may be inaccurate if Keyword Connects blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:keyword-connects`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Keyword Connects leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email Keyword Connects myself?">
    No. The Setup Tracker sends the request email to the Keyword Connects / EverConnect team automatically when you start the
    connection. You'll be able to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Keyword Connects hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether Keyword Connects has opened our setup email. If 24 hours have passed and leads
    still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="Can Hatch send a reply or status update back to Keyword Connects?">
    No. The integration is one-way (Keyword Connects → Hatch). All outreach to the lead happens through your Speed to Lead campaign in Hatch.
  </Accordion>
</AccordionGroup>


# Lavin Media
Source: https://docs.usehatchapp.com/integrations/lead-sources/lavin-media-integration

Lavin Media is a lead source that delivers home improvement and remodeling leads to contractors. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

Lavin Media delivers leads into Hatch via webhook. Once setup is complete, Lavin Media sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect Lavin Media from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates the
third-party coordination for you. Clicking *Connect* on the Lavin Media card will configure your workspace and contact Lavin
Media on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the Lavin Media lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to Lavin Media asking them to begin delivering your leads. You can review the exact *To*, *CC*, and message body that Hatch sent. Click *Next Step*
   to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When Lavin Media opens the setup request email, the read receipt is recorded (a tooltip notes that read status may be
     inaccurate if Lavin Media blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:lavin-media`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Lavin Media leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email Lavin Media myself?">
    No. The Setup Tracker sends the request email to Lavin Media automatically when you start the connection. You'll be able
    to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Lavin Media hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether Lavin Media has opened our setup email. If 24 hours have passed and leads
    still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>
</AccordionGroup>


# Modernize
Source: https://docs.usehatchapp.com/integrations/lead-sources/modernize-integration



In this article, we’ll cover the basics of our integration with [Modernize](https://modernize.com/) including what it does, how to set it up, and frequently asked questions.

### **Integration Overview**

Hatch’s integration with Modernize allows your business to win the game of “speed to lead”.

Through our integration, leads from Modernize are instantly pulled into Hatch and put into a Hatch campaign using text, email and voice communication.

See a demo here of what to expect when a lead submits a request through Modernize:

<div>
  <iframe title="Modernize Lead Demo" />
</div>

### **How to Set-up**

1. Visit the Hatch Integrations panel, it will bring you to the Hatch App Marketplace
2. Click "configure" on the Modernize app.
3. After clicking "Start Setup", an email will be sent to the Modernize team to enable the lead feed to Hatch. This email will contain the information to locate your account(s) and the necessary API Key.
4. Additionally, a default Modernize campaign, audience, and workflow will be created to help you get started.
5. The Modernize app will record if/when a lead is received to confirm activation of the integration. If a lead has not been received within 24 hours, you can generate a follow-up request to Modernize right from the app marketplace.
   <img alt="" />

### **Frequently Asked Questions**

<AccordionGroup>
  <Accordion title="Why is instant lead engagement important?">
    Speed to Lead is extremely important when it comes to new leads. The first company to get to a new lead, wins!
  </Accordion>

  <Accordion title="Who is this integration for?">
    This integration is available to Modernize and Hatch Users. There is no additional fee to turn the integration on (from Hatch or Modernize), we’ll just need to work with you to get all the necessary information to get started.
  </Accordion>

  <Accordion title="How long does it take to get set up?">
    The Modernize team will typically activate the integration within 1 business days.
  </Accordion>

  <Accordion title="What other Instant Lead Engagement Integration do you offer?">
    We offer lead engagement integrations with [Angi Leads](/integrations/lead-sources/angi-leads-integration) and more. To see the full list, check out [our website](https://www.usehatchapp.com/partners).
  </Accordion>
</AccordionGroup>


# Porch
Source: https://docs.usehatchapp.com/integrations/lead-sources/porch-integration

Porch is a lead aggregator that delivers homeowner leads to home services contractors. Hatch supports both Porch's pay-per-lead and pay-per-sale programs. Below is a description of the process on how to properly get them connected.

#### How it Works

Hatch supports two Porch lead programs, each with its own setup path:

* **Porch (pay per lead)** — connected via your Porch Subscription Company ID. Leads flow into Hatch from Porch's
  subscription platform.
* **Porch (pay per sale)** — connected via email forwarding using Hatch's guided Setup Tracker.

In both cases, Hatch creates a Contact and Opportunity record for each new lead, which can be launched into a Speed to Lead
campaign. Both programs are one-way (Porch → Hatch) with no back-sync to Porch.

#### **Setup Instructions — Porch (pay per lead)**

1. Select **Porch (pay per lead)** from our App Marketplace page & click connect.

2. Login to your Porch Subscription account in a different tab and find your **Company ID**. It is located in the upper
   right corner on your profile.

3. Add your Company ID to the setup form in Hatch.

4. Click *Activate*.

5. After activation, set up your audience and campaign workflow to launch your Porch leads into a Speed to Lead campaign.

If you are unable to locate your Porch Subscription Company ID, you can email **[support@porch.com](mailto:support@porch.com)** for assistance.

#### **Setup Instructions — Porch (pay per sale):**

When you connect **Porch (pay per sale)** from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that
automates the third-party coordination for you. Clicking *Connect* on the Porch (pay per sale) card will configure your
workspace and contact Porch on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (a group, a campaign, and a workflow)
   wired to the Porch (pay per sale) lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to Porch's pay-per-sale team asking them to begin delivering your leads to a unique Hatch ingestion address. You can review the
   exact *To*, *CC*, and message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When Porch opens the setup request email, the read receipt is recorded (a tooltip notes that read status may be
     inaccurate if Porch blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:porch-pay-per-sale`** have been
     received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Porch leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Which Porch program should I connect?">
    Connect the program(s) you're enrolled in with Porch. If you're a Porch Subscription customer (pay-per-lead), use the
    **Porch (pay per lead)** integration and provide your Company ID. If you receive leads through Porch's pay-per-sale program,
    use the **Porch (pay per sale)** integration, which is set up via Hatch's guided Setup Tracker. You can connect both if you
    participate in both programs.
  </Accordion>

  <Accordion title="Where do I find my Porch Company ID?">
    Log in to your Porch Subscription account in a separate browser tab. Your Company ID appears in the upper right corner of
    your profile. Paste it into the Hatch setup form and click *Activate*.
  </Accordion>

  <Accordion title="Do I need to email Porch myself for the pay-per-sale program?">
    No. The Setup Tracker sends the request email to Porch's pay-per-sale team automatically when you start the connection.
    You'll be able to review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Porch hasn't responded yet — what should I do?">
    For pay-per-sale, the *Receive Leads* step shows you whether Porch has opened our setup email. If 24 hours have passed and leads still haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly.
    Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from Porch?">
    Hatch captures the standard lead identification fields delivered by Porch (name, contact info, and project details).
    Available fields depend on the program and what Porch includes in the lead payload or email. Reach out to our support team if
    you need to verify what's being parsed for your account.
  </Accordion>
</AccordionGroup>


# Remodeling.com
Source: https://docs.usehatchapp.com/integrations/lead-sources/remodelling-com-integration



In this article, we’ll cover the basics of our integration with [Remodeling.com](https://remodeling.com/) including what it does, how to set it up, and frequently asked questions.

**Integration Overview**

Hatch’s integration with Remodeling.com allows your business to win the game of “speed to lead”.

Through our integration, leads that have submitted a request through Remodeling.com are instantly pulled into Hatch and can be targeted into a Hatch campaign using text, email, and voice communication.

<img alt="" />

### **How to Set-up**

1. Visit the Hatch Integrations panel, it will bring you to the Hatch App Marketplace
2. Click "configure" on the Remodeling.com app.
3. After clicking "Start Setup", an email will be sent to the Remodeling.com team to enable the lead feed to Hatch. This email will contain the information to locate your account(s) and the necessary API Key.
4. Additionally, a default Remodeling.com Hatch campaign, audience, and workflow will be created to help you get started.
5. The Remodeling.com app will record if/when a lead is received to confirm activation of the integration. If a lead has not been received within 24 hours, you can generate a follow-up request to Modernize right from the app marketplace.
   <img alt="" />

### Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Why is instant lead engagement important?">
    Speed to Lead is extremely important when it comes to new leads. The first company to get to a new lead wins!
  </Accordion>

  <Accordion title="Who is this integration for?">
    This integration is available to Remodeling.com and Hatch Users. There is no additional fee to turn the integration on (from Hatch or Remodeling.com), we’ll just need to work with you to get all the necessary information to get started.
  </Accordion>

  <Accordion title="How long does it take to get set up?">
    The Remodeling.com team will typically activate the integration within 1 business days.
  </Accordion>

  <Accordion title="What other Instant Lead Engagement Integration do you offer?">
    We offer lead engagement integrations with [Angi Leads](/integrations/lead-sources/angi-leads-integration), [Modernize](/integrations/lead-sources/modernize-integration), and more. To see the full list, check out [our website](https://www.usehatchapp.com/partners).
  </Accordion>
</AccordionGroup>


# Scorpion
Source: https://docs.usehatchapp.com/integrations/lead-sources/scorpion-integration

Scorpion is a digital marketing and lead generation platform that delivers leads to home services and other local businesses. Below is a description of the process on how to properly get them connected with Hatch.

#### How it Works

Scorpion delivers leads into Hatch via webhook. Once setup is complete, Scorpion sends new leads to Hatch,
and Hatch creates a Contact and Opportunity record, which can be launched into
a Speed to Lead campaign.

#### **Setup Instructions**

When you connect Scorpion from the App Marketplace, Hatch walks you through a guided **Setup Tracker** that automates the
third-party coordination for you. Clicking *Connect* on the Scorpion card will configure your workspace and contact Scorpion
on your behalf.

The Setup Tracker has four steps:

1. **Configure Hatch** — Hatch automatically creates the workspace items you need (audience, campaign, workflow)
   wired to the Scorpion lead source. Review what was created and click *Next Step*.

2. **Request Setup** — Hatch automatically sends a setup request email to Scorpion
   asking them to begin delivering your leads. You can review the exact *To*, *CC*, and
   message body that Hatch sent. Click *Next Step* to continue.

3. **Receive Leads** — Hatch waits for the first lead to arrive. This step shows you a live status:
   * When Scorpion opens the setup request email, the read receipt is recorded (a tooltip notes that read status may be
     inaccurate if Scorpion blocks read receipts).
   * **After 24 hours**, a *Send Follow-Up Email* button becomes available if you haven't received leads yet.
   * This step will not complete until leads with a source value of **`integration:scorpion`** have been received.

4. **Confirm Leads** — Once leads start arriving, the tracker shows the incoming opportunities. Click *Complete Setup* to
   finish.

After completing the tracker, set up your audience and campaign workflow (if needed beyond what Hatch auto-created) to launch
your Scorpion leads into a Speed to Lead campaign.

<AccordionGroup>
  <Accordion title="Do I need to email Scorpion myself?">
    No. The Setup Tracker sends the request email to Scorpion automatically when you start the connection. You'll be able to
    review exactly what was sent inside the tracker's *Request Setup* step.
  </Accordion>

  <Accordion title="Scorpion hasn't responded yet — what should I do?">
    The *Receive Leads* step shows you whether Scorpion has opened our setup email. If 24 hours have passed and leads still
    haven't started flowing, the tracker enables a *Send Follow-Up Email* button so you can nudge them directly. Read receipts may not always be reliable if their mail system blocks them, so the follow-up is the most reliable signal.
  </Accordion>

  <Accordion title="What lead fields does Hatch capture from Scorpion?">
    Hatch captures the standard lead identification fields (such as name, email, and phone).
  </Accordion>
</AccordionGroup>


# Thumbtack
Source: https://docs.usehatchapp.com/integrations/lead-sources/thumbtack

Thumbtack is a lead aggregator that sends their customers leads that fit their home improvement needs. Below is a description of the process from our App Marketplace on how to properly get them connected.

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* Thumbtack Pro account with permissions to manage integrations on the businesses you want to connect
* Registered Hatch phone number in Thumbtack

#### How it Works

Once connected, Thumbtack will send a webhook to Hatch when a new lead is received. Hatch will create a Contact and Opportunity record for the lead, which can be launched into a Speed to Lead campaign.

Once the lead is synced with Hatch, the integration will additionally send an automatic reply to the lead via the Thumbtack inbox. This ensures that Thumbtack recognizes and is able to measure that you have replied to the lead. The default automatic reply is this:

> *Thanks for contacting us! We will reach out to you directly.*

#### **Setup Instructions**

1. Select Thumbtack from our App Marketplace page & click connect.

<img alt="" />

2\. Hatch uses O-Auth protocol to connect with Thumbtack. Click connect and simply login to your Thumbtack account to authorize the connection. You will need to select which Thumbtack business to integrate from the drop-down. When successfully connected, the connection bubble should be blue when you return to the Hatch integration

<img alt="" />

3. Don't forget to click *Finish* in order to save!
4. After the integration has been activated, you will need to setup your audience and campaign workflow to launch your Thumbtack leads into a Speed to Lead campaign. Your audience should look something like this at the most basic level (you can additionally filter by different Thumbtack parameters such as business name, request category, lead type, etc):

<img alt="" />

<AccordionGroup>
  <Accordion title="Will the integration record my reply time with Thumbtack to help boost my rating?">
    The integration will be effective in boosting or maintaining a fast reply rate. When Hatch receives the lead from Thumbtack, the integration will send an auto-reply message back to the lead through the Thumbtack platform in order to get credit for replying.
  </Accordion>

  <Accordion title="I'm having trouble connecting my Thumbtack account, it says it's already connected?">
    Thumbtack only allows for 1 lead integration per account. If your account says it's already connected to something (maybe a previous service provider or your CRM), then it needs to be disconnected from that in order to connect with Hatch. Your Hatch onboarding manager or our support team can assist with this process behind the scenes.
  </Accordion>

  <Accordion title="I have multiple Thumbtack businesses, how can I connect them all with Hatch?">
    At this time, the integration instance only supports connecting a single account. Additionally, we can only support displaying a single integration instance in the app marketplace.<br /><br />
    Luckily, our support or onboarding team can assist with setting up additional instances in our back-end: these will function the same, simply will not be accessible in the app marketplace.
  </Accordion>

  <Accordion title="Can I customize the auto-reply message sent through Thumbtack?">
    Yes--but this feature is currently only available in our back-end. Feel free to reach out to our support team with any changes you would like to make to the message.<br /><br />
    <b>Keep in mind:</b> it is best to word the auto-reply in a way that lets the lead know you will be reaching out separately via direct methods, to discourage them from continuing to reply in Thumbtack (any subsequent Thumbtack messages will not be synced with Hatch).
  </Accordion>
</AccordionGroup>


# Thumbtack v2
Source: https://docs.usehatchapp.com/integrations/lead-sources/thumbtack-v2-integration

What Hatch's Thumbtack v2 integration is, how it works, and where to begin.

### What does the Thumbtack v2 integration do?

Hatch offers a native integration with Thumbtack (v2) that you can activate within the App Marketplace (located in
your Hatch workspace). This integration syncs new Thumbtack leads to Hatch in real time so you can launch them into a
Speed to Lead campaign.

Thumbtack v2 uses Thumbtack's Partner API v4 webhook delivery: whenever a customer contacts your business through
Thumbtack, Thumbtack sends a `NegotiationCreatedV4` event to Hatch and Hatch creates a Contact and Opportunity record
for the lead.

A single Thumbtack v2 integration instance can manage **multiple** Thumbtack businesses. Each selected business gets
its own webhook subscription registered with Thumbtack and can be enabled or disabled individually.

Once a lead is synced with Hatch, the integration sends an automatic reply to the lead via the Thumbtack inbox so that
Thumbtack recognizes that you have replied. The default automatic reply is:

> *Thanks for contacting us! We will reach out to you directly.*

### How do you set up the integration?

#### **Requirements**

You will need the following to set up the integration:

* Hatch account with manager privileges
* Thumbtack Pro account with permissions to manage integrations on the businesses you want to connect
* Registered Hatch phone number in Thumbtack

#### **Setup Steps**

1. In Hatch, open the **App Marketplace**.
2. Under the **Lead Sources** filter, click the Connect button for **Thumbtack v2**.
3. Hatch uses OAuth 2.0 to connect with Thumbtack. Click **Connect** and log in to your Thumbtack account to authorize
   the connection.
4. Select the Thumbtack businesses you want to integrate from the list. You can select more than one — each selected
   business will get its own webhook subscription registered with Thumbtack. When successfully connected, the connection
   bubble should turn blue when you return to the Hatch integration screen.
5. Enable the auto-reply (if desired), with the option to customize the message.
6. Click **Finish** to save and activate the integration.
7. After the integration has been activated, set up your audience and campaign workflow to launch your Thumbtack leads
   into a Speed to Lead campaign.

#### Configuration Options

* **Business selection** — A single Thumbtack v2 integration instance can manage multiple Thumbtack businesses. Each
  selected business gets its own webhook subscription with Thumbtack and can be individually enabled or disabled
  without disconnecting the whole integration.

### When does Hatch sync data to/from Thumbtack?

#### Thumbtack → Hatch

Thumbtack data is synced to Hatch in real time via webhooks:

<Note>
  Thumbtack v2 leads are delivered via webhook the moment a customer contacts one of your connected Thumbtack
  businesses. There is no polling interval.
</Note>

* When a customer creates a new negotiation with one of your connected Thumbtack businesses
  (`NegotiationCreatedV4`), Hatch receives a webhook and creates a Lead opportunity along with associated customer and
  request data.

#### Hatch → Thumbtack

**Sync Communications**

When Hatch receives a Thumbtack lead, the integration sends an automatic reply back to the lead through Thumbtack so
your account is credited with a reply, as long as the auto reply is enabled in the instance.

<Note>
  The auto-reply message is configured in the Hatch integration instance. You can use the default message or customize your own!
</Note>

* When a Hatch campaign is launched on a Thumbtack lead, an auto-reply is sent through the Thumbtack messenger so
  that Thumbtack records that the lead was replied to.

### How is Thumbtack data stored in Hatch?

#### Opportunity Models

The Thumbtack v2 integration creates one type of Hatch opportunity:

* **Lead Opportunity** — Created from a Thumbtack `NegotiationCreatedV4` event. Includes customer, business,
  request, and estimate data (see below).

#### Opportunity Creation & Update

<Note>
  When an **opportunity** is generated that doesn't match an existing **contact**, a new **contact** will be created. A
  new **opportunity** will be added to an existing **contact** if a match is found.
</Note>

The integration will create an additional (new) Hatch opportunity when:

* The synced Hatch External ID does not match any existing opportunity's Hatch External ID

### What Thumbtack data is available in Hatch?

#### Selecting Object Resources

Unlike some of our other integrations, the Thumbtack v2 integration does not expose individual resource toggles. Each
`NegotiationCreatedV4` webhook delivers the full set of fields documented below; whichever fields Thumbtack populates
for a given lead will be available on that opportunity. The only configuration that affects what data flows in is
which Thumbtack businesses you've enabled in the integration instance.

#### Available Resource Fields

The following fields are available in the **Lead opportunity** details:

| Resource             | Field Name                                       | Data Type                                                           |
| -------------------- | ------------------------------------------------ | ------------------------------------------------------------------- |
| Event                | `event:eventType`                                | String (NegotiationCreatedV4)                                       |
| Event                | `event:description`                              | String                                                              |
| Event                | `event:webhookID`                                | String                                                              |
| Event                | `event:triggeredAt`                              | Date                                                                |
| Negotiation          | `data:negotiationID`                             | String                                                              |
| Negotiation          | `data:createdAt`                                 | Date                                                                |
| Negotiation          | `data:status`                                    | String (Open, Canceled, Picked)                                     |
| Negotiation          | `data:leadPrice`                                 | String (decimal)                                                    |
| Negotiation          | `data:chargeState`                               | String (Created, Pending, Charged, Refunded)                        |
| Customer             | `data:customer:customerID`                       | String                                                              |
| Customer             | `data:customer:firstName`                        | String                                                              |
| Customer             | `data:customer:lastName`                         | String                                                              |
| Customer             | `data:customer:phone`                            | String                                                              |
| Business             | `data:business:businessID`                       | String                                                              |
| Business             | `data:business:name`                             | String                                                              |
| Business             | `data:business:imageURL`                         | String (URI)                                                        |
| Business             | `data:business:phoneNumber`                      | String                                                              |
| Business             | `data:business:accessCode`                       | String                                                              |
| Request              | `data:request:requestID`                         | String                                                              |
| Request              | `data:request:customerID`                        | String                                                              |
| Request              | `data:request:description`                       | String                                                              |
| Request              | `data:request:travelPreferences:#`               | String (CustomerTravelToProvider, ProviderTravelToCustomer, Remote) |
| Request Category     | `data:request:category:categoryID`               | String                                                              |
| Request Category     | `data:request:category:name`                     | String                                                              |
| Contacted Businesses | `data:request:contactedBusinesses:#:businessID`  | String                                                              |
| Contacted Businesses | `data:request:contactedBusinesses:#:name`        | String                                                              |
| Contacted Businesses | `data:request:contactedBusinesses:#:imageURL`    | String (URI)                                                        |
| Contacted Businesses | `data:request:contactedBusinesses:#:phoneNumber` | String                                                              |
| Proposed Times       | `data:request:proposedTimes:#:start`             | Date                                                                |
| Proposed Times       | `data:request:proposedTimes:#:end`               | Date                                                                |
| Booking              | `data:request:booking:start`                     | Date                                                                |
| Booking              | `data:request:booking:duration`                  | Number                                                              |
| Location             | `data:request:location:address1`                 | String                                                              |
| Location             | `data:request:location:address2`                 | String                                                              |
| Location             | `data:request:location:city`                     | String                                                              |
| Location             | `data:request:location:state`                    | String                                                              |
| Location             | `data:request:location:zipCode`                  | String                                                              |
| Request Details      | `data:request:details:#:question`                | String                                                              |
| Request Details      | `data:request:details:#:answer`                  | String                                                              |
| Attachments          | `data:request:attachments:#:fileName`            | String                                                              |
| Attachments          | `data:request:attachments:#:fileSize`            | Number                                                              |
| Attachments          | `data:request:attachments:#:mimeType`            | String                                                              |
| Attachments          | `data:request:attachments:#:url`                 | String (URI)                                                        |
| Attachments          | `data:request:attachments:#:description`         | String                                                              |
| Estimate             | `data:estimate:type`                             | String (Fixed, PerUnit, OnSite, Hourly, MoreInfo)                   |
| Estimate             | `data:estimate:pricePerUnit`                     | String (decimal)                                                    |
| Estimate             | `data:estimate:unitQuantity`                     | Number                                                              |
| Estimate             | `data:estimate:unitName`                         | String                                                              |
| Estimate             | `data:estimate:total`                            | String (decimal)                                                    |

#### Standard Field Mapping

Hatch standard fields are mapped from Thumbtack detail fields as detailed below.

**Lead Opportunity**

<Note>
  The base object of this opportunity model is the Thumbtack **Negotiation**. Therefore, (as an example) the **External
  ID** field would indicate the ID of the Thumbtack **Negotiation** record.
</Note>

In Lead opportunities, the following Hatch standard fields are mapped from Thumbtack detail fields:

| Hatch Standard Field                                           | Thumbtack Detail Field     |
| -------------------------------------------------------------- | -------------------------- |
| **External ID**                                                | `data:negotiationID`       |
| **External Contact ID**                                        | `data:customer:customerID` |
| **External Created At**                                        | `data:createdAt`           |
| **External Updated At** *(used for Hatch opportunity sorting)* | `data:createdAt`           |
| **First Name**                                                 | `data:customer:firstName`  |
| **Last Name**                                                  | `data:customer:lastName`   |
| **Phone**                                                      | `data:customer:phone`      |

### FAQ

<AccordionGroup>
  <Accordion title="I have multiple Thumbtack businesses — how can I connect them all with Hatch?">
    A single Thumbtack v2 integration instance supports connecting multiple Thumbtack businesses. During setup, select
    all of the businesses you want to route into Hatch — each one will be registered with its own webhook subscription on
    the Thumbtack side. You can also enable or disable individual businesses later without disconnecting the whole
    integration.
  </Accordion>

  <Accordion title="Why don't I see customer email addresses on my Thumbtack v2 leads?">
    The Thumbtack v4 Partner API does not return a customer email address for leads, so Hatch only stores a phone
    number for Thumbtack v2 contacts. If your campaigns rely on email outreach, plan around the phone-only contact
    channel.
  </Accordion>

  <Accordion title="I'm currently using the original Thumbtack integration, can I migrate to Thumbtack v2?">
    We will be offering migrations to Thumbtack v2 at a later date. Once available, we will provide more information!
  </Accordion>
</AccordionGroup>


# WinGen
Source: https://docs.usehatchapp.com/integrations/lead-sources/wingen-integration

In this article, we’ll cover the basics of our integration with WinGen including what it does, how to set it up, and frequently asked questions.

### Integration Overview

Note that this article covers the tactical setup of the Hatch and WinGen integration. For more information on the benefits of the integration, head to our **[Hatch + WinGen partner page](https://www.usehatchapp.com/integrations/wingen)**.

WinGen is a lead management platform featuring movile and web UI that provides the ability to easily capture and manage leads from retail store partners including Costco, Home Depot, and Lowes. Integrate WinGen leads with Hatch to launch leads into a Speed to Lead campaign coupled with Hatch AI to do the heavy lifting in managing and nurturing leads through the customer journey.

<Note>
  Note: The free version of the WinGen app does not support integration, upgrade will be required in order to integrate. Contact [support@wingenapp.com](mailto:support@wingenapp.com) for questions on your subscription.
</Note>

### Setup Instructions

The WinGen integration is easy to activate, all you need is Hatch Manager permissions.

1. Visit the Hatch Integrations panel, it will bring you to the Hatch App Marketplace
2. Click "configure" on the WinGen app.
3. After clicking "Start Setup", an email will be sent to the WinGen team to enable the lead feed to Hatch. This email will contain the information to locate your account(s) and the necessary API Key.
4. Additionally, a default WinGen campaign, audience, and workflow will be created to help you get started. Make sure to enable that workflow if you're ready to start launching leads!
5. The WinGen app will record if/when a lead is received to confirm activation of the integration. If a lead has not been received within 24 hours, you can generate a follow-up request to WinGen right from the app marketplace.
   <img alt="" />

#### Optional Setup

If you're receiving leads for multiple project types, brands, or locations, it may be a good idea to target your Hatch campaign(s) towards any of these datapoints or reference them in your messaging. You can expect the following information to come through from WinGen (in addition to the bare minimum contact information):

* Brand
* Trade
* Territory
* Store
* Retailer Id
* Appointment Type
* Address
* Zip Code


# Yelp
Source: https://docs.usehatchapp.com/integrations/lead-sources/yelp-integration

Hatch's integration with Yelp helps you respond to your leads quickly and easily!

### What does the Yelp integration do?

In order to protect the privacy of consumers who use Yelp to obtain quotes for their projects, Yelp has made the decision not to share the true contact information when a lead is sent through their system. While inconvenient for business users in some aspects, the goal is to maintain user trust in Yelp's platform--ultimately ensuring that users will not hesitate to reach out to businesses about potential projects. To achieve this, Yelp has developed a system of masking the contact information of both lead and business provider through secure communications channels. But this does put businesses in a position to request the lead's contact information at some point in the conversation.

Hatch's Yelp integration interacts with their APIs to immediately receive a record of new leads and lead messages sent to your business on Yelp. Hatch works with Yelp to ensure that messages sent to contacts via the masked communication channels in Hatch will be successfully delivered to the lead and into the Hatch platform.

If you're using our Hatch AI to manage your conversations, our bots are programmed with a new interaction that will take care of obtaining and updating the lead's true contact information. **Learn more about interacting with temporary contacts and how Hatch AI makes this process easier for businesses[ here](/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch)!**

### How does the Yelp integration work?

Yelp will send a webhook notification to Hatch each time a new lead or lead message is received.

* When a new lead event is received, Hatch will create a new Opportunity and Contact records using the temporary contact information. The project details will be included in the Hatch Opportunity details. You can target this contact in an audience and immediately launch it into a campaign workflow (all of which will be automatically created for you!)
* When a new lead message is received, Hatch will create a Yelp message in the Hatch conversation history. Hatch will also mark the message as read in the Yelp inbox.
  * Be aware that this means all new messages moving forward will sync to your Hatch workspace and you can respond from Hatch. This includes messages from leads that were created prior to activation of the integration. The only exception is if a lead that is older than 30 days sends a message, they will not be assigned new temporary contact methods by Yelp so they cannot sync with Hatch.
* When a lead message is responded to via Hatch, the response will also populate in the Yelp inbox and mark the lead's message as replied.

<Tip>
  It's important to be cognizant that the lead will receive your messages from the Yelp platform while messaging through the Yelp integration, so it may be advisable to provide a direct contact method for future communications.
</Tip>

#### Yelp Message

For the most reliable messaging experience, we recommend using our new Yelp message type instead of sms/email. This specialized message type uses Yelp's API to create a direct messaging channel with the lead. Once a Hatch message hits the Yelp platform, it is forwarded through their system to the lead's phone and/or email, depending on what notifications they have subscribed to. It is equivalent to sending a direct message to the lead using Yelp's own user interface.

In the Hatch UI, you can identify messages that have been sent via the Yelp messaging channel with the Yelp icon:

<img alt="Screenshot 2024-12-19 165232" />

When a new Yelp message is received, the reply type is automatically set to Yelp as well. If you have received the lead's true phone and email and want to send a message that way, you can change the message type by clicking the icon in the message box.

<Warning>
  Caution: You **must** maintain an active Yelp integration to ensure delivery of messages through the Yelp messaging channel. If for any reason your Yelp connection has gone bad, both email and in-app alerts will be issued. If you're experiencing any instability, make sure that the Yelp user authorizing the integration is not authorizing any other Yelp integrations.
</Warning>

The Yelp message type only works while the current Hatch opportunity is sourced from Yelp. If for some reason your message has not been successfully delivered through the Yelp channel, the delivery failure and reason will be shown in the conversation history.

### Integration Setup

1. Navigate to the Hatch workspace in which you would like to enable the Yelp communications and campaign workflow.
2. Navigate to the App Marketplace tab.
3. Filtering by "Lead Source," you will find the Yelp integration. Click the Connect button.
4. When you see the O-auth window, click to allow access to your Yelp account. [See the FAQ below](/integrations/lead-sources/yelp-integration#faq) for notes and clarification on what you're giving Hatch access to.

<Note>
  **Note** : you can only connect a Yelp account to a single integration. If you attempt to provide o-auth access to more than 1 integration, the connection will break.
</Note>

5. On the next screen, you will see a list of Yelp business IDs associated with your user account. To sync leads from a business, enable the toggle. You may enable more than one business.
6. Once a business has been enabled, you will need to choose from the drop-down which of your Hatch workspaces to sync the lead messages with. Whichever workspace you choose is where the inbound communications will appear on the salesboard. Additionally, that workspace's phone number will be added to the business's phone allowlist.

<img alt="Screenshot 2024-10-25 181612" />

7\. Once the integration is complete, you can find an automatically created target audience, campaign, and workflow with our recommended speed to lead sequence already setup and ready to go--just turn the workflow on when you're ready to start launching leads!

### Additional Hatch Configuration

#### Allowlist

In order to message with Yelp's leads, two things need to occur, both of which Hatch will take care of:

1\. SMS & phone calls may only be placed after the number you are calling from has been added to Yelp's allowlist. Hatch will whitelist your workspace numbers with Yelp.

2\. Email messages must have a specific, unaltered footer identifying the allowed sender. Hatch will automatically append this footer to all emails sent to Yelp contacts.

#### Campaign

Generally, Hatch recommends a multi-channel campaign in order to reach your contacts quickest in whatever mode they prefer. In this particular case, the Yelp messaging channel already takes care of that: A Yelp message from the business to a lead is mirrored to **both** of a lead's contact methods (if they have provided both an email and a phone number).

This means that it's not necessary for your Hatch campaign to send emails and texts to a lead: using the Yelp message type, every message will be delivered to the lead as both a text and email. In fact, using multiple contact methods to reach the lead may result redundant or spammy seeming messages.

*For example* , if your Hatch campaign is sending an initial text and then follows with a similar email 15 minutes later: instead of getting *two* messages, the lead will get *four* messages (all saying basically the same thing--you can see how that might seem strange or annoying!).

**Hatch's recommendations:**

* Use the Yelp message type
  * Yelp's messaging system does not enable the use of images or HTML, so treat your Yelp messages like an sms message! Keep it simple and use plain text.

* Campaign voicemail drops are not supported at this time (but you can still call the lead outside of the context of the campaign sequence).

### FAQ

<AccordionGroup>
  <Accordion title="Can I connect my Yelp account to more than 1 integration?">
    Yelp's OAuth is only valid for a single API connection, so an individual user's credentials can be used to authorize only 1 integration. Attempting to connect to another integration instance or another service will disrupt the connection of your Hatch integration and may result in missed leads or communications.
  </Accordion>

  <Accordion title="What if I am currently working with a Yelp Advertising Partner and/or Agency, can I still enable a Hatch integration?">
    Yes, if you are currently working with a [Yelp Advertising Partner and/or Agency](https://business.yelp.com/partners/) you can enable Hatch to receive your Yelp leads, so that you can read/respond to your Yelp leads within Hatch.
    However we strongly recommend that you communicate this fact as well as your intentions to your [Yelp Advertising Partner and/or Agency](https://business.yelp.com/partners/) to ensure there are no conflicts with the services they provide, prior to enabling the Hatch connection. By communicating your intentions with your [Yelp Advertising Partner and/or Agency](https://business.yelp.com/partners/) prior, this will provide the time needed for proper coordination, thus avoiding any unexpected outcomes and/or confusion.
  </Accordion>

  <Accordion title="How long is Yelp's temporary contact information valid?">
    Yelp enables the masked communication session for 30 days. After 30 days, the temporary contact methods will expire and are not able to be used for communicating with this contact. This will be reflected in the Hatch contact card (read more [**here**](/getting-started/messaging/working-with-leads-with-temporary-information-ins-hatch)).
  </Accordion>

  <Accordion title="How long does it take for my phone numbers to be added to Yelp's allowlist?">
    Currently, it may take up to 48 hours for Yelp to add your Hatch numbers to their allowlist. Planned improvements will be coming in the future to reduce this timeframe and/or potentially allow users to self-service within their Yelp accounts.
  </Accordion>

  <Accordion title="Why can't I access the lead's temporary phone number in my Yelp account anymore?">
    This is a Yelp limitation. Yelp only provides the lead's temp phone number to 1 platform, so if the Hatch integration is enabled they are sending the phone number to Hatch and it will not be visible in Yelp.

    You can look up the lead on the Hatch Contacts page to obtain the phone number if you wish to call them (assuming the lead opted in to phone communication). You can also add an outbound calling step to your Hatch campaign!
  </Accordion>

  <Accordion title="Will using Hatch affect my reply time that is tracked by Yelp?">
    Yes! Messages sent via the Yelp temporary contact methods are automatically tracked in their system as a reply made to the lead. Thus, using Hatch to instantly launch the leads into a Speed to Lead campaign will increase your reply time!
  </Accordion>

  <Accordion title="Some Yelp messages are not importing to my Hatch account—Why?">
    Hatch needs an email or phone number in order to create a contact record. If you have an older lead (a lead that was received more than 30 days prior to activating your Hatch integration) then Yelp will not assign a temporary contact method to that lead, so Hatch cannot import it.

    Additionally, any Business replies sent from Yelp are not synced into Hatch by design. Yelp does not differentiate the source of a Business reply so it's not possible to determine if it was sent from Hatch or Yelp.
  </Accordion>

  <Accordion title="What access does Hatch require from my Yelp account?">
    The following permission is required in order to activate the integration:

    * Read and Respond to Yelp Leads on your behalf
    * Receive the following information from my Yelp account: business account name, email, photo, and role
    * Display listing details
  </Accordion>

  <Accordion title="Why are leads splitting into multiple Hatch contacts with different temporary phone and email?">
    This is a result of a bug that has been discovered on the Yelp side. Yelp is in the process of fixing this issue.
  </Accordion>

  <Accordion title="Why are my campaign messages being blocked?">
    If you are trying to send a message via the temporary email method, you may be running into a Yelp limitation. A lead message may be replied to only **one** time using the temporary contact email. This same limitation exists if you were to respond via the Yelp notification thread in your personal email inbox.

    <img alt="Screenshot 2024-11-26 150038" />

    For this reason, we recommend using the Yelp message type which will directly message the lead through the APIs.
  </Accordion>
</AccordionGroup>


# Zapier + Hatch: Integrate with Lead Sources
Source: https://docs.usehatchapp.com/integrations/lead-sources/zapier-hatch-integrate-with-lead-sources

In this article, we’ll cover how you can connect via Zapier to bring in leads from various sources into Hatch. 

We recommend giving [Part One (Basics)](/integrations/general/zapier-hatch-part-1-basics) and [Part Two (Triggers and Actions)](/integrations/general/zapier-hatch-part-two-trigger-and-actions) of our Zapier + Hatch series a read before proceeding!

### Here’s How it Works

1. A potential customer fills out a lead form on your website, social media, or on a lead aggregator like [StickyLeads](https://stickyleads.com/).
2. Once the form is submitted, a “Zap” will run and send that information over to Hatch.
3. Hatch receives that lead information and creates a Contact, which you can target for campaign by creating a workflow in Hatch.

### Creating the Zap

1. From the [Zapier Dashboard](https://zapier.com/app/dashboard), click **Make a Zap**.

   <img alt="" />

2. **This will open the zap editor where you can create a series of steps from different triggers and actions.**

   <img alt="" />

3. **Set up your lead source as the trigger in your new Zap.** This is the form or source you want coming into Hatch. Search for the app you want to connect. For this example, we're going to connect our Facebook Ads account.

4. **Once you find your lead source app, it will prompt you to select your Trigger Event.** This is going to be different based on the app you are connecting but typically this is a variation of a **new lead** is submitted or a **new entry** is received (the language will change a bit depending on what App you are connecting). For this example, we're selecting New Submission. Select and click Continue.

5. **Next, you'll need to authenticate using your credentials or by logging into the app you are connecting.** This will look a little different for each app depending on their policies. You may be asked to allow Zapier to access your app. Click Allow and Continue.

6. Once you've authenticated, you'll see the app is connected and you can *Continue*.

7. At this point, most apps will prompt you to **"test" the connection** and pull up a test lead. This step is necessary in order to have data to use in the following configuration steps. The lead may or may not be a live lead from your account (it may just be test data that the app publisher chooses). Confirm that the test lead is showing the data needed for your zap, and then Continue. If not, you may need to select another test lead.

8. **Now it is time to select your Action. Upon selecting the Hatch app, choose the "Create Contact" action.** Click *Continue*.

9. You will be asked to authorize a Hatch account. If you have previously authorized access to your Hatch org, you can select it from a drop-down. Otherwise, connect a new account. You may authorize connections to more than one Hatch org.

   <img alt="" />

10. **After clicking *Connect* , you will receive a pop-up prompting you to enter the API key** (this can be obtained from Hatch Support as covered in part 1)

    <img alt="" />

11. After you have completed the authorization, you should see your Hatch account connected. It can be changed if the wrong account was selected. Click *Continue*.

    <img alt="" />

12. **Next, you will move onto Configuring your action.** This involves selecting the form data sent to Hatch, mapping and/or naming the fields sent to Hatch, and choosing which workspace to send the data to.

13. The action has some pre-set standard Hatch fields that we recommend mapping data into. Only 3 are *technically* listed as required by the action, however, it is important to note that **Hatch requires contacts to have at least a phone number *or* email.** You can hover over the field names to read a description of their meaning. A list of these is provided below in the [FAQ](/integrations/lead-sources/zapier-hatch-integrate-with-lead-sources#faq) as well.

14. **Click the + sign on a field name in order to map (insert) data from your form fields.** This will pop-up a new screen where you can search for the available fields. These fields are generated by the test record generated from your trigger, so if you don't see a field you are looking for you may need to trigger a new test. \*\*

    <img alt="" />

    If you choose to enter text manually, this is considered "hard-coded": meaning that same exact value will appear on all Hatch contact records generated by the action. This is not typically recommended.

15. If you want to bring additional fields over that do not map to a Hatch standard field, you can map these to the **Contact Details.** Since details are *custom* , you will need to create a field name to appear in Hatch in addition to mapping the value from the form. Click the "add value set" to add additional custom fields.

    In this example, I will create a contact detail to map my Facebook campaign name:

    <img alt="" />

16. The Hatch standard field named "Source" will default to "Zapier", thus it is not required. However, **we highly recommend creating a custom, meaningful value for this source field,** since this will be the method by which we can target these leads in Hatch. In this example, I will name my source Facebook Leads but if you were creating a zap for your website you might name this Website Leads. Simply type in the value to "hard-code" it for all contacts generated by this zap.

    <img alt="" />

17. **Finally, select a Board ID from the provided drop-down**. If you do not see a Board ID you are looking for, you may not have authorized the correct Hatch Org.

    <Note>
      One Note: Hatch Contacts are actually associated to a back-end concept called a Hatch Department. The Board ID is what you a user sees in the UI. Board IDs are all associated to a Department. When you select a Board ID in the drop-down, the contacts will actually be available to all Boards associated to the same Department as the Board you selected.
    </Note>

    We understand this may be a confusing concept. All that to say-- if you have a single form that may need to send contacts to multiple Hatch boards, you may not need to create multiple zaps to achieve this. Please feel free to consult with your Hatch representative on the implementation as needed.

18. Once everything has been mapped, hit **Test and Review**. If everything is working correctly, the Zap will create a test contact in your Hatch workspace. You will be presented with an Opportunity ID in the testing step "Data Out" if successful.

<img alt="" />

19. The final step is to confirm the test contact came through to Hatch with the expected format and details. Within Hatch, go to [**Contacts**](/how-to-use-hatch/contacts/contacts-basics). Search for the name of the test contact that was sent.
20. If your Zap is ready to go live, the final step is to click **Publish**.

### Setting up a Hatch Speed to Lead campaign

If you would like contacts coming in through a Zapier connection to go directly into a Hatch campaign, the Zapier integration is only step 1--these additional steps will need to be completed in Hatch.

* **Create an audience** that captures your Zapier contacts. Using our audience builder, your audience might look something like this (simply replace the highlighted value with the value of the source field you created in the zap):

<img alt="" />

* **Create a campaign** (we have a template library to get started or you can duplicate a campaign you use with other leads!)
* **Create an instant launch workflow** that will instantly drop new contacts from the audience into the campaign.

## FAQ

<AccordionGroup>
  <Accordion title="I'm having trouble mapping my form fields to the Hatch fields, the form data isn't what Hatch is expecting--what should I do?">
    If your form data is not exactly as expected for use with Hatch, there are a few routes you could take to solve this. Here's an example:

    In my Facebook form, the lead name field is "Full Name". However, Hatch requires a "First Name" and "Last Name" fields.

    <img alt="" />

    <ul>
      <li>Modify the form. Make sure to review if you have any other processes dependent on the form data first.</li>
      <li>Use a Zapier formatter step between the Trigger and Action steps. This may require an upgraded account.</li>
      <li>Accept some level of inaccuracy. In my example above, I have shown how to bypass the issue by mapping the entire Full Name to First Name, and adding a period to the required Last Name field.</li>
    </ul>
  </Accordion>

  <Accordion title="What are the expected fields on the Hatch contact?">
    <table>
      <thead>
        <tr>
          <th>Field Name</th>
          <th>Example</th>
          <th>How it’s used in Hatch</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td><b>Contact ID</b></td>
          <td>101299433</td>
          <td>This is the unique identifier for that contact or lead. If we ever see that a lead has the same contact ID, then we can update the data to make sure it's up to date.</td>
        </tr>

        <tr>
          <td><b>Contact First Name\*</b></td>
          <td>Sarah</td>

          <td />
        </tr>

        <tr>
          <td><b>Contact Last Name\*</b></td>
          <td>Stevens</td>

          <td />
        </tr>

        <tr>
          <td><b>Contact Phone Number\*</b></td>
          <td>190-184-1948</td>
          <td>Used to contact customer</td>
        </tr>

        <tr>
          <td><b>Contact Email\*</b></td>
          <td>[sarahstevens@gmail.com](mailto:sarahstevens@gmail.com)</td>
          <td>Used to contact customer</td>
        </tr>

        <tr>
          <td><b>Contact Details</b></td>
          <td>8 Windows 123 Richmond Lane Blue Couch</td>
          <td>Used to provide additional custom details. For example, let's say on the lead form the customer is asked to say how many windows they want.  A details field called "number of windows" can be created. Then, you can include in your messaging “We see you are looking for 8 windows. Let’s see what we can do.”</td>
        </tr>

        <tr>
          <td><b>Contact Status</b></td>
          <td>New Lead</td>
          <td>Used to distinguish contacts within Hatch or your CRM</td>
        </tr>

        <tr>
          <td><b>Contact Created At</b></td>
          <td>03/24/2020</td>
          <td>Used to determine when the lead came in to the original source.</td>
        </tr>

        <tr>
          <td><b>Source</b></td>
          <td>Facebook Leads</td>
          <td>Used to determine where the lead originated from (Default value is "Zapier" but this is not recommended)</td>
        </tr>
      </tbody>
    </table>
  </Accordion>
</AccordionGroup>