Twilio Integration: Composing & sending WhatsApp messages
Before continuing, please review Getting started with WhatsApp.
Once you have configured Groundhogg to send and receive messages with WhatsApp, you can begin to message your customers and collect WhatsApp IDs through opt-in forms.
Collecting WhatsApp IDs and consent
Before you can send messages via WhatsApp, you must first collect a contact's WhatsApp ID and opt-in consent.
Consent MUST be obtained ahead of sending messages to users via WhatsApp.
You can manually set a contact's WhatsApp ID and consent via the contact record.
Both fields are also mappable fields for webhooks and form integrations field mapping.
Use the following shortcode syntax to collect the WhatsApp ID and consent as custom fields in a Groundhogg form.
[text required="true" label="WhatsApp ID" placeholder="15555555555" name="whatsapp_id"] [checkbox label="I agree to receive messages via WhatsApp" name="whatsapp_optin_status" value="1" required="true"]
The WhatsApp ID is stored as a contact meta field with meta key whatsapp_id.
Sending scenarios
Two scenarios affect what kinds of messages you can send with WhatsApp.
When starting new conversations
In order to start a new conversation (send the first message) you must use an approved template.
You can view, manage, and create new templates in the Twilio Console.
We recommend copying the templates and adding them as SMS templates in Groundhogg as both our WhatsApp and SMS integrations reference the SMS templates, making it easy to standardize messaging across both channels.
When copying the template, replace the template tags {{1}} with Groundhogg replacements such as {first}.
When replying to incoming messages
If a recipient replies to one of your approved templates or is the first to message you, then you can reply with any message within 24 hours.
After 24 hours, if you have not heard back from the recipient, your following message to them must be an approved template.
Sending messages in Groundhogg
There are three ways you can communicate with your contacts via WhatsApp in Groundhogg.
Twilio Reply Benchmark
The Twilio Reply benchmark allows for implementing a simple message flow that facilitates opting into the list by messaging specific keywords.
- Run when these keywords are sent to your Twilio number... Enter keyword(s) and select (Any keywords, All keywords)
- And the channel is... - Select ( Twilio or WhatsApp, Only SMS, Only WhatsApp )
- Prompt which asks for the subscriber's name... - Default: Thanks for texting [ Business Name ] Just a couple questions. Please tell us your name. Edit as desired.
- Prompt which asks for the subscriber's email address... - Default: Thanks for that. Please text us your best email address. Edit as desired.
- Prompt which asks for the subscriber's email address if the one they provided is invalid... - Default: Oops! The email address you provided is invalid. Can you try again? Edit as desired.
- The message to send when the subscriber has successfully signed up! - Default: YAY! You're subscribed {first_name}! Check your inbox for next steps. Edit as desired.
- Send this message if the contact is already subscribed... - Default: [ Blank ]
Sending WhatsApp messages in funnels
There are two WhatsApp actions:
Send WhatsApp Reply
When the Send WhatsApp Reply action is used as a step in a funnel an SMS(text message) will be sent with the following settings:
- Search for an SMS template... - Search by entering the first few characters or choose from the available templates.
- + Create new SMS - Click the link and a popup will be presented. Enter the SMS title, content and select message type(Marketing, Transactional). [ Save Changes ]
Send WhatsApp Template
When the Send WhatsApp Template action is used as a step in a funnel an SMS(text message) will be sent with the following settings:
- Enter the WhatsApp Template ID
- Pass in variables into the template including Replacement codes
- [ Send Test ] to verify the proper result
If no WhatsApp ID is available for the contact, or if they have not provided consent, or they have withdrawn consent to receive messages via WhatsApp, the action will be skipped.
Composing one-off messages
You can also compose one-off messages to contacts via the contact record. Click the WhatsApp icon in the contact details card.
The WhatsApp icon will only show if the contact has a WhatsApp ID and has opted-in to receive messages via WhatsApp. If setting these manually you may have to refresh the page.
You will be able to select an SMS template as a base.
Composing one-off messages is subject to the same limitations as any other message, meaning you must use an approved message template if outside the 24-hour session period.
Opting out & managing WhatsApp consent
Recipients can opt-out of messages from WhatsApp by replying with any of the following keywords.
- STOP
- UNSUBSCRIBE
When this happens the contact's WhatsApp opt-in status is revoked and Groundhogg will prevent further messages from being sent.
This consent is local to Groundhogg, meaning it will not impact other services utilizing your Twilio WhatsApp integration. WhatsApp consent does not impact the contact's global opt-in status.
If the contact replies again with a keyword that matches any active Twilio Opt-in Flows then Groundhogg will change their consent status to opted-in.