Conversations Inbox | Integration with HubSpot

Hi there!

Would you like to automate the repetitive task of sending a welcome message to a new customer who just sent you a WhatsApp message?

In this tutorial, you will learn how to integrate tyntec’s Conversations Inbox WhatsApp channel with the HubSpot CRM so that you can save WhatsApp contacts in your CRM and send welcome messages automatically.

Integrating with HubSpot

There are many integration possibilities with tyntec's Conversations Inbox. In this tutorial, you will achieve the following integration scenario: When a new customer sends a message to your WABA number, a new contact will be created in HubSpot with basic details, and a free-form WhatsApp welcome message will be sent to the customer automatically.

You will need

  • Your WABA phone number that has been approved by tyntec
  • Your tyntec API key from your tyntec account
  • A HubSpot CRM account with Super Admin access
  • A mobile phone with WhatsApp installed and a working phone number as a testing customer
  • An ngrok account and the binary installed for development
  • Node.js and your favorite text editor or IDE with JavaScript highlighting

Step One: HubSpot basic setup

Let’s get started with the basic setup of HubSpot.

1. Create a HubSpot developer account, go to Manage apps, and create an app, which will hold the webhook for processing contact creation events.

2. In the app Auth tab, add oauth and contacts scopes for the app.

Start by setting the webhook with required scopes

Important: Copy the client_id and client_secret of your app, you’re going to need them in the next step

3. Create a custom contact property named origin. The app uses this flag to ensure that only contacts that came from WhatsApp, and not other contacts created in HubSpot, receive free-form welcome messages. This restriction is added to comply with the WhatsApp Business Policy.

Go to your non-developer HubSpot CRM account, then Settings, and in the section Properties click on the Create property button.

Visit the properties settings to create new one.

Enter some Basic info for the property, and most importantly, label the property as Origin.

create a new property named origin

Next, select Single-line text for the Field type and uncheck Show in forms, because this property will be used only by your app and not by humans. Click on the Create button.

Set the field type to single-line text

Step Two: Get your integration app ready

For your quick start with integrations, we’ve prepared a WhatsApp HubSpot Integration Demo. Look at what the code does: You will notice that the server.js file contains two service routes (/ and /auth) to setup the app in HubSpot, and two integration webhooks:

  • /whatsAppTrigger which will handle callbacks from the Conversations Inbox API to receive a WhatsApp message from a customer, and calls the HubSpot API to check if this contact is saved in the CRM and to create a new contact, eventually.
  • /contactCreated which will handle callbacks from the HubSpot API, once the new contact has been created and calls the Conversations Inbox API to send the welcome message.

Let’s just quickly get your app running in the development style:

1. Clone the repository.
2. Install dependencies:

npm install

3. Run ngrok in a terminal:

ngrok http 3000

4. Set environment variables used by the app in your OS:

  • HS_CLIENT_ID – the client_id from HubSpot
  • HS_CLIENT_SECRET – the client_secret from HubSpot,
  • HS_OAUTH_REDIR – the redirect URI to complete app authorization (the /auth endpoint of your app),
  • CMD_API_KEY – the API key from tyntec,
  • WABA_NUMBER – your WABA number in the international format without leading +/00.

5. And finally, start the app in another terminal:

node server.js

Step Three: Set up the Conversations Inbox webhook

Let the Inbox know where to deliver relevant events. You’re going to set Conversations Inbox API webhook in via POST request in Postman.

1. From the chat-integrations directory, import the CMD.postman_collection.json into Postman.

2. Open the Set Webhook request and change the URL in the body to the /open endpoint on your server (for example https://YOUR.ngrok.io/whatsAppTrigger). This request will subscribe your URL to incoming message events.

Subscribe through Postman

3. Hit the Send button. You should receive a 204 status in the response if everything is okay.

An Alternative Way to Set up the Conversations Inbox webhook

If you don't want to use Postman, you can use cURL to let Conversations Inbox know where to send incoming messages. 

1. Create a file subscribeCMD.json for the subscription of your WhatsApp trigger webhook to WhatsApp message events in Conversations Inbox:

{
  "events": [ "message" ],
  "url": "https://YOUR.ngrok.io/whatsAppTrigger"
}

2. Now use it with a call to Conversations Inbox API to subscribe:

curl -H "Content-Type: application/json" -H "Authorization: Bearer CMD_API_KEY" --data @subscribeCMD.json https://api.cmd.tyntec.com/v3/channels/WABA_NUMBER@whatsapp.eazy.im/webhooks

There you go! The Conversations Inbox API knows about your webhook, and it will fire when it has a new WhatsApp message from a customer.

Step Four: Subscribe your webhook to HubSpot

Let HubSpot know about your other webhook!

1. Go back to your HubSpot app management in the developer account, and in the app's settings, select Webhooks.

Subscribe webhook on your ngrok oauth endpoint

Enter your webhook URL in the Target URL field, set throttling, and save the setting.

2. Now click on Create subscription and subscribe to contact creation events.

Select contact

Fill in the details and click on Subscribe.

3. To activate your subscription, select the checkbox of the subscription and click on Activate.

When it’s activated, it should look like this

Your webhook will show as active

And that’s it!

Tip: HubSpot has the option to subscribe via its API as well, if you prefer that method.

Step Five: Install your app in HubSpot CRM

You are almost done! Now you can install your app so that HubSpot CRM connects with your webhook for created contacts.

1. Visit your ngrok URL inside your internet browser. You will see an Install your app in Hubspot link that contains the authorization information for your app required by HubSpot.

App authentication on your ngrok address.

To initiate the installation of your app in the HubSpot, click the link.

2. Select the account in which you want to install your app.

Any account that isn’t a developer account will do.

Select your non-dev account

3. Grant access to the app and confirm that you’re not a robot.

Grand access for the sample app

HubSpot will redirect you to your app to complete the authorization, which the sample application automatically does.

4. Voila! Now when you check your Connected apps in your account > Settings > Integrations, you should see your app listed.

a new connected app has appeared.

Step Six: Try it out

Let’s see what happens when a new user messages your WABA number.

1. In the dashboard of your non-developer HubSpot account, go to Contacts. You can see that in our testing account, there are no contacts yet.

A fresh new testing account

2. Now play at being a customer and send a WhatsApp message to your WABA number.

3. Voila! Contact created in HubSpot.

A new contact from WhatsApp has been automatically created.

And you can see in the Conversations Inbox that the app has sent a welcome message back! If you check your phone, you see the same message on your Whatsapp.

And new message in Support Inbox goes alongside the new Hubspot contact.

Congratulations on completing your integration!

More?

You can add various other integrations as well by following similar steps. You might, for example, assign the customer as a new lead, and based on that event, let your app create a task, assign it to an employee and notify them with a WhatsApp message on their work number.