How to install the WhatsApp Connector by Respira in Zendesk

Important

This process is quite complex. If you get stuck, we can set up the WhatsApp Connector together.

Before you start

Be aware that there are 2 types of WhatsApp messages:

• Free text messages
• Templated (also called proactive) messages

Your customers can send free text WhatsApp messages whenever they want. If your customer sends you a message, you only have 24 hours to reply with free text. Due to Facebook policy, If 24 hours have passed, or if you want to start a conversation, then you have to use templated messages.

Free text WhatsApp messages are supported by Zendesk out of the box, but templated messages are not. This app enables you to do that.

License requirements

In order to be able to send templated WhatsApp messages, you will need:

1. An active Zendesk Suite , Zendesk Professional, or Sunshine Conversations License
2. A Facebook for Business account
3. A dedicated phone number linked to a WhatsApp account

If you do not have any of these, please contact us or Zendesk Advocacy to get support.

Sending Templated WhatsApp messages

Please follow these steps in order to install the WhatsApp connector and send your first WhatsApp message:

1. Install the WhatsApp Connector by Respira app from the Zendesk Marketplace
2. Create a user account
3. Create a connection
4. Enter your Conversations API credentials
5. Enter your Meta for Business (WhatsApp) credentials
6. Grant OAuth permissions to this App
7. Enable the Webhook for error notification 
8. Create your first template and send your first templated WhatsApp message
9. Set up the Ticket Sidebar App

1.- Install the WhatsApp Connector by Respira from the Zendesk Marketplace

In order to install the app, you have to:

1. Visit the Zendesk Marketplace, and look for our app. For example, you can search for "Respira".
2. Click on the app icon.
3. Click install.

You can also follow this link and click install.

After doing this, you will find a new icon in the left bar of your Zendesk Workspace:

Watch this video to see how it is done:

 

2.- Create a user account

Click on the new icon. You will be taken to the login screen. Click Sign up, and enter your email.

When you create your account, an email will be sent to you with your password. If you don´t receive it, please check your SPAM email inbox.

After receiving your email, you can go back to the login page and enter your email and the password you just got in your email. You can change that password later if you want.

In this video you can see the sign up process:

3.- Create a connection

Go back to the WhatsApp Connector by Respira app, and log in using the password you received in your email:

Then click to add a new connection, from the Home section, or from the Connections section under Settings:

You must now fill the form on the left:

The following data must be entered:

• Name: a name for your connection. For example: My WhatsApp Line 1-800 xxx xxx
• Zendesk Subdomain or username: your Zendesk subdomain. If your Zendesk instance is for example under https://mycompany.zendesk.com, your subdomain is "mycompany". Enter it.
• Active: Yes

Then click Save.

Check out this video to see it in action:

4.- Enter your Conversations API credentials

Go to the Admin Center in Zendesk, and search for the Conversations API in the menu. 

Then Click on create a new API Key, and give it a name:

After that, you will see the data, but you will only see it once, so watch out:

Make sure to store this data safely, since you won´t be able to see them again.

Back in the WhatsApp Connector by Respira app (previous tab in your browser), enter:

• Sunshine Conversations API Key Id: the ID of the newly created Sunshine Conversations API Key (Key ID in the screenshot above).
• Sunshine Conversations API Key Secret: the "secret" part of the API key (Secret Key in the screenshot above).
• Sunshine Conversations App Id: The App Id in Sunshine conversations, see screenshot above (App ID in the screenshot above).
• Sunshine Conversations API URL: The URL that Sunshine conversations will use.
  • If you are in Europe: https://api.eu-1.smooch.io
  • Outside Europe: https://api.smooch.io
  • If you have a Zendesk Suite license, you can also use https://{{mysubdomain}}.zendesk.com/sc

Once you have entered this data, a "Check Connection" button will appear. Click on it to make sure the connection works, and then click save.

Here is a video on how to create a connection:

5.- Enter your Meta for Business (Facebook) credentials

You need to have the WhatsApp channel enabled before being able to continue. More information here.

WhatsApp Business Integration Id

If you created your account before June 2022, the Sunshine Conversations or Meta support team must provide the WhatsApp Business Integration Id.

If you created your account after June 2022, you can get it from the Zendesk Admin Center, since it is shown as a parameter in the url of the WhatsApp Channel.

The WhatsApp Business Integration Id is the last parameter of the url, the text after the last slash bar:

WhatsApp Business Account Namespace

If you are logged in into Facebook with the right profile, you can use this link to find it:

https://business.facebook.com/wa/manage/message-templates/

Otherwise, navigate to: https://business.facebook.com, and then:

1. Click configuration
2. Search for WhatsApp, and click the link (if you don't see it, you might need to contact Facebook Support).
3. Go to WhatsApp accounts (or Cuentas de WhatsApp in Spanish), and then click on WhatsApp administrator (Administrador de WhatsApp in Spanish):
4. And then, under Account Tools, message templates:

You can find it under the Namespace button on your Meta for Business template manager:

Last but not least, don't forget to click Save. You will also find a button to check if the WhatsApp settings are correct after you have entered the data.

If you have no access to your Facebook account, you can open a ticket with the Zendesk Support team so they can provide that for you. To do so:

• At the top right of your Zendesk screen, click on your profile.
• Click Get Help
• A messaging window will pop up at the bottom right of your screen. Click on Start a new Conversation
• Type "Get Facebook Namespace". Choose "Messaging", then "I still need help",  then "Connect to another team" as product and send the request to the Sunshine Conversations team, and then type again "Get Facebook Namespace". They will respond to you in a few hours with your namespace.

See below how to set up the WhatsApp settings:

6.-Grant OAuth Permission to the app

Now go to Settings. You can go by navigating to the home section and clicking Settings, or by clicking on the menu and clicking Settings.

You will be redirected to another tab. It all went well, a message saying "You have successfully granted access to Respira" will show up. Then close the tab and click on "Check Status" to make sure the status is "Granted":

 

7.- Enabling the Webhook for error notification

If you want your tickets to be updated when an error occurs (highly recommended), for example if a message can not be delivered to the recipient, you need to enable the Conversations Webhook from the settings. To do so, go to Settings, then click on Enable Webhook. You can check the status after doing it to be sure it all went well.

 

8.- Create your first template and send your first proactive WhatsApp message

After you have your connection set up, you are ready to send your first notification. The easiest way to do it is by sending a single notification. Here is how to do it:

1. Create a new Facebook template
2. Send a single notification to a known number

8.1. Creating a new Facebook template. 

You can create a new template by navigating to Templates, and then clicking on Add WhatsApp template, or in the plus icon at the top right of your screen:

More information about template creation here.

8.2.- Send a single notification to a known number

To do this, navigate to Single Messages, and fill in the form. Send the message to a known WhatsApp number to make sure that the message is delivered.

And after the notification delivery, a ticket should have been created. Here is what you should be seeing:

Watch this video to find out how to create a new template and send a single message (8.1 and 8.2):

If you don't receive your WhatsApp message, and your connection has been set up correctly, you should receive an error explaining the issue in your ticket. There is a list of the most common errors in our documentation.

NEXT STEPS

After setting up your connection, you can are ready to send WhatsApp notifications. You can do it by:

• Sending single WhatsApp messages
• Sending bulk WhatsApp Notifications
• Using the Ticket Sidebar App

Feel free to contact us if you have queries.