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!

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. 
  
  

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:

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. 

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 for notes and clarification on what you're giving Hatch access to. 
   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. 
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.
   
   
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

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. 

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).

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. 

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!

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. 

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

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.

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.

For this reason, we recommend using the Yelp message type which will directly message the lead through the APIs.