{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"WhatsApp Integration","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"whatsapp-integration","__idx":0},"children":["WhatsApp Integration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":1},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Questionnaires can be configured to invite participants via WhatsApp, using the Meta WhatsApp Business API, instead of (or in addition to) SMS and email."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#configuring-whatsapp-integration"},"children":["Configuring WhatsApp Integration"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#when-a-whatsapp-invite-is-sent"},"children":["When a WhatsApp Invite Is Sent"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#sending-behavior"},"children":["Sending Behavior"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#supported-whatsapp-languages"},"children":["Supported WhatsApp Languages"]}]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#failure-behavior"},"children":["Failure Behavior"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#delivery-status-tracking"},"children":["Delivery Status Tracking"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#webhook-setup-meta-side"},"children":["Webhook Setup (Meta Side)"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#getting-your-credentials-from-meta-production"},"children":["Getting Your Credentials from Meta (Production)"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuring-whatsapp-integration","__idx":2},"children":["Configuring WhatsApp Integration"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open the questionnaire in the Clearspeed web app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the questionnaire-specific left navigation bar, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Integration"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WhatsApp Integration"]}," section, click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Modify Credentials"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/whatsapp-step1-integration-page.564dd0077b9d11a32f6fff18e6091c48a200b87c6503520b30b76b7c8044dc13.9c1bb791.png","alt":"Integration page showing the WhatsApp Integration section with the Modify Credentials button"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Integration page, WhatsApp Integration section"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":4},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fill in the following fields:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta Access Token"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta WhatsApp Business API access token. Masked in the UI, with a show/hide toggle."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta Phone Number ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Meta-registered phone number ID sending messages."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta Template Name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name of the pre-approved Meta message template to use."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Allowed Placeholders"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Placeholders to insert into the template body, chosen via the placeholder picker."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/whatsapp-step2-modify-credentials.239ad9e836fb8434f7069b7f507b925d9152bd3b16c9ea6a7dbc832ec5497862.9c1bb791.png","alt":"Modify Credentials dialog showing Meta Access Token, Meta Phone Number ID, Meta Template Name, and Allowed Placeholders picker"},"children":[]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Screenshot placeholder — Modify Credentials dialog"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":5},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"allowed-template-parameters","__idx":3},"children":["Allowed Template Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only these are accepted:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate_name"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_number"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionnaire_url"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dial_number"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-a-whatsapp-invite-is-sent","__idx":4},"children":["When a WhatsApp Invite Is Sent"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automatically"]}," — when a participant is created with a phone number, if WhatsApp integration is fully configured for the questionnaire, the participant is invited via WhatsApp instead of SMS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manually"]}," — an admin can trigger (or re-trigger) a WhatsApp invite via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send Message Invite"]}," action on the Participant list/detail view."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"sending-behavior","__idx":5},"children":["Sending Behavior"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Participant phone number must be in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["E.164 format"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+14155552671"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The template language should be the same as the language(s) configured in the Questionnaire — the language used at send time is resolved from each participant's own language, so the approved Meta template must exist for every language the Questionnaire supports."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A retry within ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["30 seconds"]}," of a prior non-failed WhatsApp send for the same participant/questionnaire is treated as a duplicate and returns the original send result rather than sending again."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-whatsapp-languages","__idx":6},"children":["Supported WhatsApp Languages"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Language"},"children":["Language"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meta Language Code"},"children":["Meta Language Code"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arabic"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ar"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arabic (Egyptian)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ar_EG"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Arabic (Qatari)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ar_QA"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Afrikaans"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["af"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Albanian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["sq"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bulgarian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["bg"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Chinese"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["zh_CN"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Croatian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hr"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Czech"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["cs"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Danish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["da"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Dutch"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["nl"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (UK)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_GB"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (US)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_US"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (Australia)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_AU"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (Canada)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_CA"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (India)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_IN"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["English (Malaysia)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["en_MY"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Estonian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["et"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Finnish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fi"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["French"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fr"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["French (Canada)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fr_CA"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["German"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Greek"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["el"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hausa"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ha"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hindi"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["hi"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Italian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["it"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Japanese"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ja"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Kazakh"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["kk"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Korean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ko"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Latvian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["lv"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Lithuanian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["lt"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Malay"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ms"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Norwegian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["nb"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pashto"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ps_AF"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Persian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["fa"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Polish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["pl"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Portuguese (Brazilian)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["pt_BR"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Punjabi"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["pa"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Romanian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ro"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Russian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ru"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Serbian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["sr"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slovak"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["sk"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Slovenian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["sl"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Spanish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["es"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Spanish (Chilean)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["es_CL"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Swedish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["sv"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Thai"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["th"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Turkish"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tr"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ukrainian"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["uk"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Urdu"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ur"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vietnamese"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["vi"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Zulu"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["zu"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A participant whose configured language isn't in this list cannot be sent a WhatsApp invite."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"failure-behavior","__idx":7},"children":["Failure Behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a WhatsApp send fails — for any reason (bad credentials, unapproved template, invalid phone number, provider outage, etc.) — on the automatic invite sent at participant creation, the failure is caught and the participant is automatically sent an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SMS invite instead"]},", using the same participant/questionnaire data. An audit log entry is recorded noting the WhatsApp failure and the fallback to SMS. The participant still receives an invite; only the channel changes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"specific-failure-scenarios","__idx":8},"children":["Specific Failure Scenarios"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scenario"},"children":["Scenario"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Result"},"children":["Result"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp integration incomplete (any of Access Token / Phone Number ID / Template Name / Template Language missing)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected — \"WhatsApp provider is not configured for this questionnaire\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Questionnaire has no guide URL configured"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected — \"questionnaire is not configured with a guide URL\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Participant's language has no supported WhatsApp language mapping"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected — \"no WhatsApp template language mapping for language_code ...\""]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Participant phone number not in E.164 format"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rejected — invalid phone number format"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duplicate send within 30 seconds of a prior non-failed attempt"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not resent — returns the original send's result"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meta rejects or fails the send (e.g. bad credentials, unapproved template)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send fails — error surfaced with the underlying provider error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Message sent successfully but the delivery record fails to save"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send is still considered successful, but delivery status updates cannot be tracked for that message"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-status-tracking","__idx":9},"children":["Delivery Status Tracking"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Meta sends delivery status callbacks — sent, delivered, read, failed — via webhook, which update the WhatsApp message record."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-setup-meta-side","__idx":10},"children":["Webhook Setup (Meta Side)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Since Clearspeed runs in multiple regional environments, the webhook must be registered separately per region — using that region's own domain."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Meta supports two ways to configure this:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-a--app-level-webhook-via-dashboard","__idx":11},"children":["Option A — App-Level Webhook (via Dashboard)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Applies to every WhatsApp Business Account (WABA) and phone number connected to the App, unless overridden. This is the option that matches Clearspeed's setup (one webhook per region, not per tenant)."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://developers.facebook.com/"},"children":["Meta for Developers"]}," → your production App → ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WhatsApp → Configuration"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook"]},", click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Edit"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Callback URL"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify Token"]}," (values below), then click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify and Save"]}," — Meta will call the Callback URL with the Verify Token to confirm it before saving."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Still under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook"]},", click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Manage"]}," and subscribe to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["messages"]}]}," field — this delivers status updates (sent/delivered/read/failed) and inbound messages to Clearspeed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-b--per-waba--per-phone-number-override-via-graph-api","__idx":12},"children":["Option B — Per-WABA / Per-Phone-Number Override (via Graph API)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Meta's Graph API also supports overriding the callback URL and verify token for a specific WABA or phone number, instead of using the App-wide one:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /{waba-id}/subscribed_apps\noverride_callback_uri=<callback-url>\noverride_callback_uri_verify_token=<verify-token>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This exists for Tech Providers/ISVs managing many clients' WABAs under one shared App, where each client needs its own callback endpoint. Not needed for Clearspeed's current setup, since routing is per-region rather than per-tenant — but relevant if a tenant ever needs to receive WhatsApp events on their own endpoint independent of the region-wide webhook."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"values-to-enter","__idx":13},"children":["Values to Enter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Callback URL"]}," (per region):"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Region"},"children":["Region"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Webhook URL"},"children":["Webhook URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["United States"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.us.clearspeed.com/message-delivery/webhooks/meta"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["United Kingdom"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.uk.clearspeed.com/message-delivery/webhooks/meta"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify Token"]},": provided by Clearspeed's integration team — use the exact value they give you. Meta sends this back during the verification handshake to confirm the endpoint is authentic."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-your-credentials-from-meta-production","__idx":14},"children":["Getting Your Credentials from Meta (Production)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Prerequisites"]},": a verified Meta Business, and the App/WhatsApp Business Account switched from Development to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Live"]}," mode — otherwise sends are restricted to a handful of pre-registered test numbers."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"meta-access-token","__idx":15},"children":["Meta Access Token"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Business Settings → Users → System Users"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create (or select) a System User with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin"]}," role."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Generate New Token"]}," → select your App → grant the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp_business_messaging"]}," (and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp_business_management"]},") permissions."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy the generated permanent token — this is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Meta Access Token"]},". Treat it as a secret; rotate it if exposed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"meta-phone-number-id","__idx":16},"children":["Meta Phone Number ID"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WhatsApp Manager → API Setup"]}," (or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Phone Numbers"]},"), select the production number registered for sending."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Copy its Phone Number ID — this goes in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Meta Phone Number ID"]}," field."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"meta-template-name","__idx":17},"children":["Meta Template Name"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["WhatsApp Manager → Message Templates → Create Template"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add one placeholder in the template body for each value you want filled, choosing only from the allowed parameters: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference_number"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionnaire_url"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_code"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dial_number"]},". Add them in the same order they'll be selected in the Allowed Placeholders picker on the Integration page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit for Meta's approval — templates must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["approved"]}," before they can send to real participants."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Once approved, use the template's exact name as the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Meta Template Name"]},"."]}]}]},"headings":[{"value":"WhatsApp Integration","id":"whatsapp-integration","depth":1},{"value":"Overview","id":"overview","depth":2},{"value":"Configuring WhatsApp Integration","id":"configuring-whatsapp-integration","depth":2},{"value":"Allowed Template Parameters","id":"allowed-template-parameters","depth":3},{"value":"When a WhatsApp Invite Is Sent","id":"when-a-whatsapp-invite-is-sent","depth":2},{"value":"Sending Behavior","id":"sending-behavior","depth":2},{"value":"Supported WhatsApp Languages","id":"supported-whatsapp-languages","depth":3},{"value":"Failure Behavior","id":"failure-behavior","depth":2},{"value":"Specific Failure Scenarios","id":"specific-failure-scenarios","depth":3},{"value":"Delivery Status Tracking","id":"delivery-status-tracking","depth":2},{"value":"Webhook Setup (Meta Side)","id":"webhook-setup-meta-side","depth":2},{"value":"Option A — App-Level Webhook (via Dashboard)","id":"option-a--app-level-webhook-via-dashboard","depth":3},{"value":"Option B — Per-WABA / Per-Phone-Number Override (via Graph API)","id":"option-b--per-waba--per-phone-number-override-via-graph-api","depth":3},{"value":"Values to Enter","id":"values-to-enter","depth":3},{"value":"Getting Your Credentials from Meta (Production)","id":"getting-your-credentials-from-meta-production","depth":2},{"value":"Meta Access Token","id":"meta-access-token","depth":3},{"value":"Meta Phone Number ID","id":"meta-phone-number-id","depth":3},{"value":"Meta Template Name","id":"meta-template-name","depth":3}],"frontmatter":{"title":"WhatsApp Integration","description":"How to configure Meta WhatsApp Business API credentials so participant invitations are sent via WhatsApp, including webhook setup, supported languages, and failure behavior.","seo":{"title":"WhatsApp Integration"}},"lastModified":"2026-07-23T09:25:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/whatsapp-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}