Lead Interaction

So you've received a lead through Yelp! What can you do with it?

Yelp Leads allow you to interact with a Lead Submitter in one of four ways inside the Yelp ecosystem:

• By messaging through the Yelp Inbox, which is your Yelp Business Account messaging interface.
• By messaging through Leads API Events.
• By messaging, using a Yelp-generated masked email address, received through the Leads API.
• By phone/messaging, using a Yelp-generated masked phone number, received through the Leads API.
  • The initial outreach can be via call or SMS text.

📘

Messaging through a Yelp Lead

Whether you're communicating with a customer via the Yelp user interface, the Leads API, masked email, or masked phone (SMS), all messages are part of the same unified chat thread. Regardless of the channel, the conversation is consolidated into a single thread for consistency. As such, be sure to stick to one method of communication to avoid confusion.

You can find a consumer user's temporary (masked) email address and/or phone number by calling the Get Lead endpoint. See the example API response below:

{
	"business_id": "SNa1ugk6DNIuvIPu8-AiGA",
	"id": "xKgWk-XoFWBQucET-xr-hw",
	"conversation_id": "49-Acxgj7-0C5SAMG_J7Dg",
	"temporary_email_address": "[email protected]",
	"temporary_email_address_expiry": "2022-01-02T03:04:05+00:00",
	"temporary_phone_number": "+14166666666",
	"temporary_phone_number_expiry": "2022-07-06T00:00:00+00:00"
	"time_created": "2024-08-23T20:56:27+00:00",
	"last_event_time": "2024-08-26T18:17:20+00:00",
	"user": {
		"display_name": "Austin D."
	},
	"project": {
		"survey_answers": [
			{
				"question_text": "How many bathtubs need repairs?",
				"answer_text": [
					"1"
				]....}

🚧

Masked Emails and Masked Phone Numbers

Access to these fields in the API is disabled by default and requires configuration by Yelp before you can use them. Reach out to your Yelp account representative if you're interested in using these fields.

Why Yelp Masks Emails and Phone Numbers

Yelp masks customer phone numbers and email addresses to protect user privacy and ensure a secure, consistent communication experience. By routing messages through masked channels, Yelp can monitor for abuse, enforce platform policies, and provide a seamless way for businesses and customers to interact—without exposing personal contact information. This approach helps build trust while maintaining accountability on both sides of the conversation. Check out this blog to learn more!

How to Manage Temporary/Masked Email Address

The Temporary/Masked Email Address of the Lead Submitter will always be passed via our Get Lead endpoint and can be used for multiple communications for up to 30 days until it expires.

Best Practice

While you can engage with leads using the Yelp Inbox or the Leads API, you also have the option to contact them directly via email. Communicating with customers through their masked email address is relatively simple. If you choose to take this approach, please follow the best practices outlined below:

• Stick with plain text when formatting your email response. Including formatting or URLs in the email could affect our system's ability to correctly parse the email body. This means:
  • No HTML or rich text formatting
  • No embedded links or full URLs
    • If you would prefer to include a URL, we would recommend using a URL shortener such as Bitly, TinyURL, or Short URL. These types of URLs work well with the email parser.
  • No images or attachments

Correct Usage: Here is an example of an email body formatted correctly:

Thank you for your interest in our services. We're excited to help you with your project! Please feel free to reach out if you have any more questions. To learn more about our team, check out https://bit.ly/3XyzAbC! 

Best regards, 
The Team 

Incorrect Usage: The following example includes common mistakes that should be avoided:

Thank you for your interest in our services. [Bold]We're excited to help you with your project![/Bold] 

• Please feel free to reach out if you have any more questions. 
• To learn more about our team, check out https://yelp.com!

Best regards, 
The Team  

• In the incorrect example, the email includes rich text formatting as well as a full URL.

How to Manage Temporary/Masked Phone Number

The Temporary/Masked Phone Number of the Lead Submitter will only be passed via our Get Lead endpoint. It can be used for multiple communications for up to 30 days until it expires if the Lead Submitter opts-in to be communicated with via phone/SMS.

If you plan to leverage this field, we recommend to call the Get Lead endpoint after receiving the Masked Phone Number Opt-In Status event webhook .

Due to the phone number verification process on the consumer side, masked phone numbers may not be immediately available upon your initial receipt of a lead. Look out for a webhook event with "event_type":"CONSUMER_PHONE_NUMBER_OPT_IN_EVENT" if you are looking to process leads that include a masked phone number. Please note that at the time of writing, about 40% of Yelp Leads include a masked phone number. Keep this in mind as you design your integration.

Allow-Listing Outbound Phone Numbers

Before using a Yelp masked phone number, you must first register the phone number(s) you plan to use for outbound communication. This security measure ensures that all communication sent to customers via Yelp originates from a verified number associated with your business.

First, ensure you have an active Phone Availability Zap trigger set up.

Then, you will need to provide a comprehensive list of phone numbers you use to outbound dial Yelp phone leads so Yelp can add them to your businesses' allowlist. Additionally, share the best phone number where the Lead Submitter can contact you directly. This step is a requirement of receiving and using masked phone numbers from a Yelp Lead. You can provide your phone number(s) to your Yelp account representative or by filling out this form.

🚧

Note to Channel Partners

Because you may be managing multiple clients leveraging multiple outbound call-lines, it may not be feasible for you to maintain an updated list of all of your clients’ outbound phone numbers and therefore access to this field may not be available.

SMS Exchanges

You can send outbound SMS texts to the masked phone number, but two-way SMS is not currently supported. Any replies from the Lead Submitter are accessible in the Yelp Inbox of your Business Owner Account or via the Leads API Events feed.

Yelp Inbox

If you're interested in managing Yelp Leads communication directly through your Business Account Yelp Inbox, you can construct a link to a lead-specific chat using the URL template below. The business_id and lead_id needed to construct this URL can be found in the GET Lead response of the API.

https://biz.yelp.com/leads_center/{{business_ID}}/leads/{{leads_ID}}