Setting up a trigger to send proactive WhatsApp messages from Zendesk

If you have the Respira WhatsApp Connector installed, you can set up a trigger in Zendesk to send WhatsApp messages when some events occur, e.g. when a ticket is created with a certain tag, when an email is received with a given subject, when an API call is received from another app like Zapier or some custom app, etc.. 

Before starting, you need to have a Webhook in Zendesk that points to our servers. If you don't have it, here is how to do it.

The process is as follows:

1. Create a Webhook to connect to the WCR API (if you already have it, omit this step). 
2. Go to the Admin Center and create a new trigger
3. Add an action notifying the a Webhook in Respira

1.- Create a Webhook to connect to the WCR API.

Go to the Admin Center, and search for Webhooks. Then click Create Webhook:

Select "Trigger or automation". Then in Section 2 (Add details), enter:

• Name: The name of your choosing, it could be "Send WhatsApp Message"
• Endpoint URL: https://respirainternet.com/sunco/api/v3/messages/
• Request method: POST
• Request format: Form encoded
• Authentication: Basic authentication
• Username: user email at Respira + "/token". For example, [e-mail]/token. See screenshot below if you are not sure where to get this.
• Password: Your Respira API Key, that identifies the connection you want to use. You can get it from the Connections section in the Respira Zendesk App (see screenshot below).

It should look similar to this:

You can use any combination of user email and active connection, as long as the users are linked to those connections in Respira.

2.- Go to the Admin Center and create a new trigger

Just go to the Admin Center, and search for triggers. Then click on "Triggers". Then click on Add trigger:

3.-Add an action notifying the Webhook 

And then, in your trigger actions, you must notify the Webhook that is linked to the WhatsApp connector (if you don´t have is set up, here is how to do it):

Required parameters

You must always include the following data in every Webhook notification:

• template_name: It is the name of the template you want to use in Facebook. A template must exist under your WABI (Whatsapp Business) account, and be approved by Facebook. Otherwise, the notification will fail.
• language: a language code supported by Facebook. For example, es is Spanish, en is English, fr is French, but also en_GB is supported. See the language codes available here.
• messages -> phone: the phone or phones the trigger needs to send the messages to, along with all the Facebook template parameters, and optionally, delivery dates. Keep in mind that:
  •  You must always enter at least one phone number, with this format: messages[0][phone] 
  • The phone can be a Zendesk placeholder, like {{ticket.requester.phone}} or {{ticket.ticket_field_ID}}, or a fixed number (always with country prefix without zeroes), like [phone].
  • You can set up the trigger to send messages to multiple phones, by adding messages[0][phone]: phone_number_1, messages[1][phone]: phone_number_2, messages[2][phone]: phone_number_3, etc.
  • You can include up to 100 messages per request.

Optional parameters

• ticket_id: it is the ticket number. We need it because the connector will use it to update the ticket with an internal note when it sends the notification, and will add another internal note if it fails. The connector will add some tags to the ticket too. You can omit ticket creation by entering another parameter: omit_ticket_creation: true (below).
• omit_ticket_creation. If you set this parameter to true, no ticket will be created or updated after the WhatsApp message is sent.
• add_to_queue. This parameter must be included if your trigger or automation might be triggered many times all at once. Keep in mind that:
  • if your trigger is triggered multiple times, and you don’t include this parameter, you might get system errors and your users will never get their messages. Worse yet, you will not know which received them and with did not.
  • If your messages array has more than one item, all messages will be queued, regardless of you including this parameter or not.

• origin. An arbitrary identifier of the origin of the request. Use this if you send requests from different apps and you want to track them later.

Message parameters

• phone: This is the phone you want to deliver the notification to. As stated before, this is always required. The format for the key must be messages[0][phone] (see screenshot above). If you send more than one message, specify the phones as messages[0][phone], messages[1][phone], etc. The values can be fixed, like "[phone]" or a placeholder, like {{ticket.requester.phone}}.
• ri_body_param_1, ri_body_param_2 ... ri_body_param_5: The values for the body parameters in your WhatsApp template, marked as {{1}}, {{2}} ... {{5}}. They must have the same format as the phone, e.g. messages[0][ri_body_param_1]. The value can also be a placeholder, like {{ticket.requester.first_name}} or fixed, like "John".
• ri_footer_param_1, ri_footer_param_2, ri_footer_param_3: The values for the footer parameters in your WhatsApp template, marked as {{1}}, {{2}}, {{3}}.. They must have the same format as the phone, e.g. messages[0][ri_footer_param_1]. Like body parameters, the values can be a placeholder or fixed text.
• ri_header_type: If present, it must be one of these: "text", "image", "document", or "video" . If your template has a text header, but the header has no parameters in it ( {{1}} ), do NOT include this parameter. The key must be set with the same format as the phone, e.g. messages[0][ri_header_type].
• ri_header_text: If the ri_header_type parameter is "text" AND THE HEADER TEXT IN YOUR WHATSAPP TEMPLATE HAS A VARIABLE (set as {{1}} ), this is the value of that text. Do not include ri_header_type and ri_header_text in the trigger if the Header text has no parameters in it. They must have the same format as the phone, e.g. messages[0][ri_header_text].
• ri_header_link: If your template header type is "image", "document", or "video", this is the publicly accessible URL of that image, document, or video. You can use the Media Gallery to upload .pdf documents, upload .jpg, .png or .gif images, or upload .mp4 videos. They must have the same format as the phone, e.g. messages[0][ri_header_link].
• delivery_date, delivery_time, iana_timezone. Add these parameters if you want your notification to be delivered at a specific date and time. They must have the same format as the phone, e.g. messages[0][delivery_date], messages[0][delivery_time], messages[0][iana_timezone].

More about template parameters

• You can send up to 5 body parameters. They must be called ri_body_param_1, ri_body_param_2 ... up to ri_body_param_5.
• If your Facebook Template has footer parameters, for example if you have a dynamic link, then add them as ri_footer_param_1, ... up to ri_footer_param_3.
• If your template uses a text header but no parameters, you don´t need to include any parameter as URL parameter.
• If your template uses a text header with 1 parameter, like "This is my header {{1}}", then you need to specify: ri_header_type: "text", and ri_header_text: "My header param". More information about how to send templates with header parameters here.
• If your template uses a header with a pdf document, then you need to specify: ri_header_type: "document", and ri_header_link something like: "https://path-to-my-document/doc.pdf". More information about how to send templates with documents in the header here.
• If your template uses a header with an image, then you need to specify: ri_header_type: "image", and ri_header_link something like: "https://path-to-my-image/image.jpg". More information about how to send templates with images in the header here.
• If your template uses a header with a video, then you need to specify: ri_header_type: "video", and ri_header_link something like: "https://path-to-my-video/video.mp4". More information about how to send templates with video in the header here.
• The scheduled delivery date, time and timezone are optional. If you don´t add them, the notification will be sent immediately.
• The scheduled delivery date and time specified in must obviously be set to a date after the trigger is triggered. It is a good practice leaving at least one hour of margin, otherwise your customer might never receive the message.
• In order to send a scheduled message, all 3 schedule delivery fields (delivery date, delivery time, and IANA timezone) must be included for the delivery date and time to be set up. You must enter all 3 or none.
• This is the list of IANA timezones (column TZ identifier).

Examples

1.- Template without parameters.

Imagine we want to use this template, with name "personal_data_removed", and language English (language code "en"), to send the following message to the ticket requester:

In this case, we would need to set it up like this:

 

2.- Message to several people.

If we wanted to send the same message to several people. We also do not want to create or update the ticket, just send the notifications. We would do:

 

3.- Template with a body parameter.

Imagine we want to use this template, with name "conversation_reset_en", and language English (language code "en"), to send the following message to the ticket requester:

In this case, we would need to set it up like this:

 

4.- Message with a header video.

Say we wanted to send something like this:

In this case, we have a header image, and 2 body parameters. We would enter:

If you create the template using our app, you do not need the ri_header_type and ri_header_link parameters.

The Stop promotions link is part of the template definition, so we do not need to include any footer parameters.

More information about sending messages with images here.

 

Contact us

Contact us if you have queries, or if you need help with the setup for your particular business needs.