whatsapp-docs-mcp 1.0.3 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +2 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +54 -2
- package/dist/index.js.map +1 -1
- package/dist/tools.d.ts +10 -0
- package/dist/tools.d.ts.map +1 -1
- package/dist/tools.js +59 -0
- package/dist/tools.js.map +1 -1
- package/dist/utils/search.d.ts +18 -2
- package/dist/utils/search.d.ts.map +1 -1
- package/dist/utils/search.js +328 -93
- package/dist/utils/search.js.map +1 -1
- package/dist/utils/search.test.js +128 -0
- package/dist/utils/search.test.js.map +1 -1
- package/docs/catalogos/sell_products_and_services.md +1 -1
- package/docs/flows/changelog.md +613 -0
- package/docs/flows/gettingstarted/health_insurance.md +537 -0
- package/docs/flows/gettingstarted/personalised_offer.md +495 -0
- package/docs/flows/gettingstarted/pre_approved_loan.md +506 -0
- package/docs/flows/gettingstarted/purchase_intent.md +246 -0
- package/docs/flows/gettingstarted.md +52 -0
- package/docs/flows/guias.md +60 -0
- package/docs/flows/playground.md +135 -0
- package/docs/flows/referencia.md +102 -0
- package/docs/flows/support.md +32 -0
- package/docs/flows.md +98 -0
- package/docs/{mensagens/limites_de_mensagens → messaging_limits}/upcoming_changes.md +1 -1
- package/docs/suporte.md +408 -0
- package/package.json +9 -2
|
@@ -0,0 +1,537 @@
|
|
|
1
|
+
<!-- Source: https://developers.facebook.com/docs/whatsapp/flows/gettingstarted/health-insurance -->
|
|
2
|
+
<!-- Scraped: 2025-12-21T15:24:15.346Z -->
|
|
3
|
+
|
|
4
|
+
[Plataforma do WhatsApp Business](https://developers.facebook.com/docs/whatsapp)
|
|
5
|
+
|
|
6
|
+
[](#)
|
|
7
|
+
|
|
8
|
+
# Use Case Guide: Insurance Quote
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
## Intro and Overview
|
|
13
|
+
|
|
14
|
+
WhatsApp is making it easier than ever for your customers to understand the options available to them, offering a convenient and immediate solution for getting a quote. Creating an experience within a WhatsApp Flow is a quick and easy way for your customers to interact with your offering, without having to exchange multiple messages back and forth.
|
|
15
|
+
|
|
16
|
+
WhatsApp Flows enables your users to get a quote within the chat thread - providing an experience that is quick and easy for users to complete.
|
|
17
|
+
|
|
18
|
+
In this guide, we will walk through the entire process to build a Flow for a ‘Get Insurance Quote’ use case. The templates here can be adapted to suit your use case.
|
|
19
|
+
|
|
20
|
+
Flows we will build will demonstrate how you can:
|
|
21
|
+
|
|
22
|
+
- Collect relevant information to help build a personalised quote
|
|
23
|
+
- Allow your users to customise their preferred excess amount
|
|
24
|
+
- Request appropriate personal information of the people who the insurance will cover
|
|
25
|
+
- Allow your users to select the payment frequency
|
|
26
|
+
- Review available insurance plans based on the selections and present a description for each
|
|
27
|
+
- Publish, Send, and Monitor your Flow
|
|
28
|
+
|
|
29
|
+
This template can be further adapted to collect additional information from the customer. We’ve created the Flow JSON Template for this experience, which you can access [here](#flows-json-template).
|
|
30
|
+
|
|
31
|
+
## Getting Started
|
|
32
|
+
|
|
33
|
+
To follow this guide, ensure you have:
|
|
34
|
+
|
|
35
|
+
- Completed [prerequisites](/docs/whatsapp/flows/gettingstarted#prerequisites) for building Flows.
|
|
36
|
+
- A [Glitch](https://l.facebook.com/l.php?u=https%3A%2F%2Fglitch.com%2Fsignup&h=AT2yrZ7oAaEu3D4M3o8jRmDC3noC7intNXdkKCPK56mhCYSLBM3Fef7HjcKgMANH949ITqhvQc_3OVvF4OGSkpuYNsefmFhcwW-b4GG93BLvdPU3eZenruAobTLnT05P2QeEv84XMbtZoUxp0WD4fJ1Jt3M) account
|
|
37
|
+
|
|
38
|
+
[](#)
|
|
39
|
+
|
|
40
|
+
## Flows JSON Template
|
|
41
|
+
|
|
42
|
+
Flow JSON
|
|
43
|
+
|
|
44
|
+
{
|
|
45
|
+
|
|
46
|
+
"version": "7.3",
|
|
47
|
+
|
|
48
|
+
"data\_api\_version": "3.0",
|
|
49
|
+
|
|
50
|
+
"routing\_model": {
|
|
51
|
+
|
|
52
|
+
"APPLICANTS": \[
|
|
53
|
+
|
|
54
|
+
"COVER\_LEVEL"
|
|
55
|
+
|
|
56
|
+
\],
|
|
57
|
+
|
|
58
|
+
"COVER\_LEVEL": \[
|
|
59
|
+
|
|
60
|
+
"EXCESS"
|
|
61
|
+
|
|
62
|
+
\],
|
|
63
|
+
|
|
64
|
+
"EXCESS": \[
|
|
65
|
+
|
|
66
|
+
"DETAILS"
|
|
67
|
+
|
|
68
|
+
\],
|
|
69
|
+
|
|
70
|
+
"DETAILS": \[
|
|
71
|
+
|
|
72
|
+
"YOUR\_HEALTH",
|
|
73
|
+
|
|
74
|
+
"ADDITIONAL\_APPLICANT"
|
|
75
|
+
|
|
76
|
+
\],
|
|
77
|
+
|
|
78
|
+
"YOUR\_HEALTH": \[
|
|
79
|
+
|
|
80
|
+
"ADDITIONAL\_APPLICANT",
|
|
81
|
+
|
|
82
|
+
"POLICY\_SELECTION"
|
|
83
|
+
|
|
84
|
+
\],
|
|
85
|
+
|
|
86
|
+
"ADDITIONAL\_APPLICANT": \[
|
|
87
|
+
|
|
88
|
+
"POLICY\_SELECTION"
|
|
89
|
+
|
|
90
|
+
\],
|
|
91
|
+
|
|
92
|
+
"POLICY\_SELECTION": \[
|
|
93
|
+
|
|
94
|
+
"SELECTED\_POLICY"
|
|
95
|
+
|
|
96
|
+
\],
|
|
97
|
+
|
|
98
|
+
"SELECTED\_POLICY": \[
|
|
99
|
+
|
|
100
|
+
"YOUR\_QUOTE"
|
|
101
|
+
|
|
102
|
+
\],
|
|
103
|
+
|
|
104
|
+
"YOUR\_QUOTE": \[
|
|
105
|
+
|
|
106
|
+
"SUMMARY"
|
|
107
|
+
|
|
108
|
+
\],
|
|
109
|
+
|
|
110
|
+
"SUMMARY": \[\]
|
|
111
|
+
|
|
112
|
+
},
|
|
113
|
+
|
|
114
|
+
"screens": \[
|
|
115
|
+
|
|
116
|
+
Enter to Rename, ⇧Enter to Preview
|
|
117
|
+
|
|
118
|
+
Preview
|
|
119
|
+
|
|
120
|
+
Run
|
|
121
|
+
|
|
122
|
+
Configurações
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
Select screen
|
|
127
|
+
|
|
128
|
+
APPLICANTS
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
* * *
|
|
135
|
+
|
|
136
|
+
Preview Flow
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
# Tell us who you'd like to cover?
|
|
141
|
+
|
|
142
|
+
Who would you like to cover?
|
|
143
|
+
|
|
144
|
+
- Just myself
|
|
145
|
+
|
|
146
|
+
- Myself & another person
|
|
147
|
+
|
|
148
|
+
- My family
|
|
149
|
+
|
|
150
|
+
- Just my children (under 18)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
* * *
|
|
154
|
+
|
|
155
|
+
# Additional applicant
|
|
156
|
+
|
|
157
|
+
Additional applicant
|
|
158
|
+
|
|
159
|
+
Number of people you want to add to this policy
|
|
160
|
+
|
|
161
|
+
Continue
|
|
162
|
+
|
|
163
|
+
Gerenciada pela empresa. Saiba mais Saiba mais
|
|
164
|
+
|
|
165
|
+
### Create new flow from a template
|
|
166
|
+
|
|
167
|
+
1. In the [Flows section of WhatsApp Manager](https://business.facebook.com/wa/manage/flows/) click on the **Create Flow** button in the top right corner.
|
|
168
|
+
2. In the Create page, fill in the details for the pre-approved loan Flow:
|
|
169
|
+
- **Name** - Type _Insurance Quote_, or choose another name you like.
|
|
170
|
+
- **Categories** - Select _Lead generation_.
|
|
171
|
+
- **Template** - Choose _Provide Insurance Quote_. You can further customize the template to suit your use case.
|
|
172
|
+
3. Click **Create** to create Flow.
|
|
173
|
+
|
|
174
|
+
You can preview the Flow on the right of the Builder UI.
|
|
175
|
+
|
|
176
|
+
The Flow remains in the draft state as you edit it. You can share it with your team for testing purposes only. To share it with a large audience, you’ll need to publish it. However, you can’t edit the Flow once you [publish](#publishing). Since you will still need to add the endpoint URL for this Flow, leave it as a draft for now and proceed to the next step, where you’ll configure the demo backend endpoint.
|
|
177
|
+
|
|
178
|
+
**See also**
|
|
179
|
+
|
|
180
|
+
- [Flow JSON Overview](/docs/whatsapp/flows/reference/flowjson)
|
|
181
|
+
|
|
182
|
+
[](#)
|
|
183
|
+
|
|
184
|
+
## Configure Demo Backend on Glitch
|
|
185
|
+
|
|
186
|
+
WhatsApp Flows lets you connect to an external endpoint. This endpoint can provide dynamic data for your Flow and control routing. It also receives user-submitted responses from the Flow.
|
|
187
|
+
|
|
188
|
+
For testing purposes, this template uses Glitch to host the endpoint. Using Glitch is entirely optional, and not required to use Flows. You can [clone the endpoint code from GitHub](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2FWhatsApp%2FWhatsApp-Flows-Tools%2Ftree%2Fmain%2Fexamples%2Fendpoint%2Fnodejs%2Finsurance-quote&h=AT1I54oLR9EipGIrAH8K4dCQTQRt_QCZQkLBEGjNnV_QzRmeyZhWCNNymkqtTWQnTKa3Shiszf1zg_1dCN3XPW_LuboarN8Z9T9tWoCVGkat2fbt-WWxTwxMPwYTenHfG36hlOGECd_Uhw4HmWsh07KQzaY) and run it in any environment you prefer.
|
|
189
|
+
|
|
190
|
+
### 1\. Remix (fork) Glitch endpoint
|
|
191
|
+
|
|
192
|
+
Access the [endpoint code in Glitch](https://l.facebook.com/l.php?u=https%3A%2F%2Fglitch.com%2Fedit%2F%23%21%2Fwhatsapp-flows-insurance-quote&h=AT3lHM1hz_bQel8oPrk3rVF_RcMhhQLaWpeddn043-jwZOLlg1zJv2b4eQ6-Etycs2Ar07Zx2eYCl-lzsw7fPbVZGSULpg83u8Hb_SWhiv0LEayZviSubaEAhGuE3qPYIRXAgnm8A8uhyaEMgJbYwM5VNf0) and remix it to get your unique domain. To remix it, click **Remix** at the top of the page. A unique domain will appear as a placeholder in the input element on the right side of the Glitch page.
|
|
193
|
+
|
|
194
|
+
### 2\. Setup encryption key
|
|
195
|
+
|
|
196
|
+
Private key helps decrypt the messages received. The passphrase will be used to verify the private key. Along with the private key, you also need its corresponding public key, which you’ll upload later. Never use the private keys for your production accounts here. Create a temporary private key for testing on Glitch, and then replace it with your production key in your own infrastructure.
|
|
197
|
+
|
|
198
|
+
1. Generate the public-private key pair by running the command below in the Glitch terminal. Replace `YOUR_PASSPHRASE` with your designated passphrase. Access the Glitch terminal by clicking the **TERMINAL** tab at the bottom of the page a run following command: `node src/keyGenerator.js YOUR_PASSPHRASE`
|
|
199
|
+
|
|
200
|
+
2. Copy the passphrase and private key and paste them to the .env file. Click on the file labeled **.env** on the left sidebar, then click on **✏️ Plain text** on top. _Do not edit it directly from the UI, as it will break your key formatting._
|
|
201
|
+
|
|
202
|
+
3. After you set the environment variables, copy the public key that you generated and [upload the public key](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/whatsapp-business-encryption#set-business-public-key) via the Graph API.
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
### 3\. Set endpoint URI
|
|
206
|
+
|
|
207
|
+
Once you set up encryption keys, you can proceed with setting Endpoint URI for your flow.
|
|
208
|
+
|
|
209
|
+
1. At the top right of the Glitch page, click on **Share** and copy the **Live Site** URL from the displayed modal.
|
|
210
|
+
|
|
211
|
+
2. Head to the [Flow Builder](https://business.facebook.com/wa/manage/flows/) and in the Flow Builder click on the **three dot** menu in top right corner of the screen. Select **Setup** under the **Endpoint** section.
|
|
212
|
+
|
|
213
|
+
3. A popup will appear, allowing you to configure the endpoint URI, business phone number, and app on Meta for Developers. Save the Live Site URL copied from the Glitch into the first step of modal.
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
After making the necessary configurations, perform a health check from the last step of the modal. You should be able to get a successful response (if you get an error please check the details and the provided resolution advice).
|
|
217
|
+
|
|
218
|
+
### 4\. Set App Secret (optional)
|
|
219
|
+
|
|
220
|
+
App secret is used in signature verification. It helps you check whether a request is coming via WhatsApp and, therefore, is safe to process. You’ll add it to the **.env** file.
|
|
221
|
+
|
|
222
|
+
To access your app secret, select your App from the [dashboard in the Meta for Developers](https://developers.facebook.com/apps/). In the left navigation pane under **App settings**, choose **Basic**. Click **Show** under **App secret** and copy the secret. Then, return to Glitch, open the .env file, and create a variable named APP\_SECRET with the value of the secret you copied.
|
|
223
|
+
|
|
224
|
+
Now you have completed all the required steps to be able to test flow with the provided endpoint.
|
|
225
|
+
|
|
226
|
+
**See also**
|
|
227
|
+
|
|
228
|
+
- [Detailed code walk through](#overview-of-demo-backend) for demo backend
|
|
229
|
+
- [Implementing endpoint for Flows](docs/whatsapp/flows/guides/implementingyourflowendpoint) for full details on how to build production endpoint
|
|
230
|
+
|
|
231
|
+
[](#)
|
|
232
|
+
|
|
233
|
+
## Testing and Debugging
|
|
234
|
+
|
|
235
|
+
### Debug flow using the interactive preview
|
|
236
|
+
|
|
237
|
+
After you complete the configurations, toggle the interactive preview in the WhatsApp Builder UI to test the Flow.
|
|
238
|
+
|
|
239
|
+
1. Trigger the interactive preview by clicking on settings menu in the **Preview** section of the Flow Builder and enabling **Interactive mode** toggle.
|
|
240
|
+
|
|
241
|
+
2. In the modal that appears, select the phone number, enter any string as **Flow token** and choose the **Request data** option under **Request data on the first screen**. This sends a request to the endpoint to retrieve data for the first screen.
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
Now, click on **Actions** tab at the bottom of the code editor in Builder. You’ll see an `init` action in the list. Click on it to see the details and you will see the decrypted request sent to the endpoint. There will also be decrypted response received from endpoint with the initial data payload.
|
|
245
|
+
|
|
246
|
+
Return back to **Preview** and proceed to select option from radio button selection. Back in **Actions** tab notice action has changed to `data_exchange` and selected option is visible when you click on the last entry in the action log under request tab.
|
|
247
|
+
|
|
248
|
+
Keep testing out the Flow and observe the data changes in the **Actions** tab. Similar logs will be generated when users interact with the Flow from their mobile devices.
|
|
249
|
+
|
|
250
|
+
You can also see decrypted request and responses logged in the Glitch LOGS tab at the bottom of the Glitch screen.
|
|
251
|
+
|
|
252
|
+
### Send draft flow to your device
|
|
253
|
+
|
|
254
|
+
Before you publish your flow you can also send it and test it on an actual device. To send draft flow to your device, follow [instructions here](/docs/whatsapp/flows/guides/testingdebugging#send-draft-flow-to-your-device).
|
|
255
|
+
|
|
256
|
+
**See also**
|
|
257
|
+
|
|
258
|
+
- [Flow Testing and debugging guide](/docs/whatsapp/flows/guides/testingdebugging)
|
|
259
|
+
|
|
260
|
+
[](#)
|
|
261
|
+
|
|
262
|
+
## Publishing
|
|
263
|
+
|
|
264
|
+
When you first created your Flow, it entered the Draft state. And as you edited and saved the modified Flow JSON content, it remained in the Draft state. You are able to send the Flow while it's in the Draft state, but only for testing purposes. If you want to send the Flow to a larger audience, you'll need to Publish the Flow.
|
|
265
|
+
|
|
266
|
+
You can publish your Flow once you have ensured that:
|
|
267
|
+
|
|
268
|
+
- All validation errors and [publishing checks](/docs/whatsapp/flows/guides/healthmonitoring#publishing-checks) have been resolved.
|
|
269
|
+
- The Flow meets the [design principles](https://developers.facebook.com/docs/whatsapp/flows/guides/bestpractices) of WhatsApp Flows
|
|
270
|
+
- The Flow complies with [WhatsApp Terms of Service](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.whatsapp.com%2Flegal%2Fterms-of-service%2F%3Flang%3Den&h=AT1CxuqsByfV7pcdbS2wnq3Tk0qKUVktMdg2VnutuvYYXJzAI9CoYYK_DaqXF6Y9o0u8_LnjRL8pDwMfU6LuAgQRhOxHsOGtp769de9gjLSvPqhaJyRqP9mpWcX9aTsbpLQfrUhjKTJ8a4OFoQ_kuXzGNiE), the [WhatsApp Business Messaging Policy](https://l.facebook.com/l.php?u=https%3A%2F%2Ffaq.whatsapp.com%2F933578044281252&h=AT0oPrcn0o97mkDntcozM7CMOPXQNzyMWURtcOzQ2q2C9yN5vLPPbe_g7OCe9bDjTK-9X6Hyhdu_yWUKXs_xye-BHHQ_GBWvYhQPx3BH8bPNe7Mwz-YkTHexn-V7EJ-Xw8RwHlBnW_XuZSYnwYF_Ncmggfg) and, if applicable, the [WhatsApp Commerce Policy](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.whatsapp.com%2Flegal%2Fcommerce-policy%2F%3Flang%3Den&h=AT1YCZyGHs36RrJ3_jx8X6xtU7B-G_xH6ZDz5bsiyraIBKmEnw3w4CKhYt7iivZPt4JS1zP7aUnINcNTMGgjWUIbi2BiXIpSIWj8rbCamjawtVFOMVI3ZTCf9gT71rSTXYPNJJxdRsi6K7IOGd-3mL6RyRI)
|
|
271
|
+
|
|
272
|
+
Remember, once a Flow has been published it can no longer be modified. See [Flow Status Lifecycle](/docs/whatsapp/flows/gettingstarted/flows-lifecycle) for more information on the different Flow states.
|
|
273
|
+
|
|
274
|
+
To publish your Flow, open the **three dot** menu to the right of the **Save** button and click **Publish**. Once published, the Flow can be sent to anyone!
|
|
275
|
+
|
|
276
|
+
[](#)
|
|
277
|
+
|
|
278
|
+
## Sending
|
|
279
|
+
|
|
280
|
+
You can send your WhatsApp Flow as:
|
|
281
|
+
|
|
282
|
+
- **[Template messages](https://developers.facebook.com/docs/whatsapp/flows/gettingstarted/sendingaflow#templatemessages)** - these do not require a 24-hour customer service window to be open between you and the message recipient before the message can be sent.
|
|
283
|
+
- **[Interactive Flow messages](https://developers.facebook.com/docs/whatsapp/flows/gettingstarted/sendingaflow#userinitiated)** - these can only be sent to a user when a customer service window is open between you and the user.
|
|
284
|
+
|
|
285
|
+
[Learn more about sending your Flow](https://developers.facebook.com/docs/whatsapp/flows/gettingstarted/sendingaflow)
|
|
286
|
+
|
|
287
|
+
[](#)
|
|
288
|
+
|
|
289
|
+
## Receiving flow response
|
|
290
|
+
|
|
291
|
+
Upon flow completion a response message will be sent to the WhatsApp chat. You will receive it in the same way as you receive all other messages from the user - via message webhook.
|
|
292
|
+
|
|
293
|
+
[Learn more about how to setup messaging webhook](/docs/whatsapp/flows/gettingstarted/receiveflowresponse)
|
|
294
|
+
|
|
295
|
+
[](#)
|
|
296
|
+
|
|
297
|
+
## Monitoring
|
|
298
|
+
|
|
299
|
+
Flow monitoring is only applicable to Flows with endpoint.
|
|
300
|
+
|
|
301
|
+
After your Flow is published and being sent to the customers, it is important to monitor your Flow's health and address any problems as they are discovered by WhatsApp.
|
|
302
|
+
|
|
303
|
+
There are multiple ways how you can monitor your flows:
|
|
304
|
+
|
|
305
|
+
- Metrics Dashboard in WhatsApp Account Manager
|
|
306
|
+
- Navigate to [Flow section of Whatsapp Account Manager](https://business.facebook.com/wa/manage/flows/) and click on any published flow with the endpoint. You will be presented with a Details page with a Performance Metrics Dashboard.
|
|
307
|
+
- Metrics API
|
|
308
|
+
- All the data presented in the Details page is also available to be queried through [Flows Metrics API](https://developers.facebook.com/docs/whatsapp/flows/reference/metrics_api).
|
|
309
|
+
- Quality Webhooks
|
|
310
|
+
- You should also [subscribe to Flows Quality Webhooks](https://developers.facebook.com/docs/whatsapp/flows/reference/flowswebhooks#subscribe-to-webhooks) to be updated in real time about the statuses and performance of your business' Flows.
|
|
311
|
+
|
|
312
|
+
See [Flow Health and Monitoring](https://developers.facebook.com/docs/whatsapp/flows/guides/healthmonitoring) overview for more information.
|
|
313
|
+
|
|
314
|
+
[](#)
|
|
315
|
+
|
|
316
|
+
## Next Steps
|
|
317
|
+
|
|
318
|
+
Now that you have successfully completed this guide, learn more about what you can do with this Flows in our [Guides](/docs/whatsapp/flows/guides) and [Reference](https://developers.facebook.com/docs/whatsapp/flows/reference) sections.
|
|
319
|
+
|
|
320
|
+
[](#)
|
|
321
|
+
|
|
322
|
+
## Overview of demo backend
|
|
323
|
+
|
|
324
|
+
There are four JavaScript files in the [Glitch example src directory](https://l.facebook.com/l.php?u=https%3A%2F%2Fglitch.com%2Fedit%2F%23%21%2Fwhatsapp-flows-insurance-quote&h=AT1z6wZLx5oPlM62oYaRcjJK8204WawGY8Kx-PBPVGjUNHVavYm9sAp-8-AMPg0FXf8yBOUG0gZCzgx42oQotaVwsQLWG1YpYV3hj0nGPUeEPUeeqYgFOSiw5whiWlr4Z5TBxebagGH7gVh5UeYCGnOOVcQ): `encryption.js`, `flow.js`, `keyGenerator.js`, and `server.js`. The entry file is `server.js`, so let’s look at it first.
|
|
325
|
+
|
|
326
|
+
### server.js
|
|
327
|
+
|
|
328
|
+
The `server.js` file starts by configuring the Express application to use the express.json middleware to parse incoming JSON requests. Then, it loads the environment variables needed for the endpoint.
|
|
329
|
+
|
|
330
|
+
```
|
|
331
|
+
const { APP_SECRET, PRIVATE_KEY, PASSPHRASE, PORT = "3000" } = process.env;
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
The `server.js` file also contains a POST endpoint that performs different steps:
|
|
335
|
+
|
|
336
|
+
Checks that the private key is present:
|
|
337
|
+
|
|
338
|
+
```
|
|
339
|
+
if (!PRIVATE_KEY) {
|
|
340
|
+
throw new Error('Private key is empty. Please check your env variable "PRIVATE_KEY".');
|
|
341
|
+
}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Validates the request signature using the isRequestSignatureValid function found at the bottom of the file:
|
|
345
|
+
|
|
346
|
+
```
|
|
347
|
+
if(!isRequestSignatureValid(req)) {
|
|
348
|
+
// Return status code 432 if request signature does not match.
|
|
349
|
+
// To learn more about return error codes visit: https://developers.facebook.com/docs/whatsapp/flows/reference/error-codes#endpoint_error_codes
|
|
350
|
+
return res.status(432).send();
|
|
351
|
+
}
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
Decrypts incoming messages using the decryptRequest function found in the encryption.js file:
|
|
355
|
+
|
|
356
|
+
```
|
|
357
|
+
let decryptedRequest = null;
|
|
358
|
+
try {
|
|
359
|
+
decryptedRequest = decryptRequest(req.body, PRIVATE_KEY, PASSPHRASE);
|
|
360
|
+
} catch (err) {
|
|
361
|
+
console.error(err);
|
|
362
|
+
if (err instanceof FlowEndpointException) {
|
|
363
|
+
return res.status(err.statusCode).send();
|
|
364
|
+
}
|
|
365
|
+
return res.status(500).send();
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
const { aesKeyBuffer, initialVectorBuffer, decryptedBody } = decryptedRequest;
|
|
369
|
+
console.log("💬 Decrypted Request:", decryptedBody);
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
Decides what Flow screen to display to the user. You’ll look at the getNextScreen function in detail later.
|
|
373
|
+
|
|
374
|
+
```
|
|
375
|
+
const screenResponse = await getNextScreen(decryptedBody);
|
|
376
|
+
console.log("👉 Response to Encrypt:", screenResponse);
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Encrypts the response to be sent to the user:
|
|
380
|
+
|
|
381
|
+
```
|
|
382
|
+
res.send(encryptResponse(screenResponse, aesKeyBuffer, initialVectorBuffer));
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
### encryption.js
|
|
386
|
+
|
|
387
|
+
This file contains the logic for encrypting and decrypting messages exchanged for security purposes. See [Code examples](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint#code-examples) section of Endpoint implementation guide for encryption examples in other languages.
|
|
388
|
+
|
|
389
|
+
### keyGenerator.js
|
|
390
|
+
|
|
391
|
+
This file helps generate the private and public keys, as you saw earlier.
|
|
392
|
+
|
|
393
|
+
### flow.js
|
|
394
|
+
|
|
395
|
+
The logic for handling the Flow is housed in this file. It starts with an object assigned the name `SCREEN_RESPONSES`. The object contains screen IDs with their corresponding details, such as the preset data used in the data exchanges. This object is generated from Flow Builder under **"..." > Endpoint > Snippets > Responses**. In the same object, you also have another ID, `SUCCESS`, that is sent back to the client device when the Flow is successfully completed. This closes the Flow.
|
|
396
|
+
|
|
397
|
+
The `getNextScreen` function contains the logic that guides the endpoint on what Flow data to display to the user. It starts by extracting the necessary data from the decrypted message.
|
|
398
|
+
|
|
399
|
+
```
|
|
400
|
+
const { screen, data, version, action, flow_token } = decryptedBody;
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
WhatsApp Flows endpoints usually receive three types of requests:
|
|
404
|
+
|
|
405
|
+
- A [data\_exchange](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint#data_exchange_request) request signified by a `data_exchange` action
|
|
406
|
+
- An [error notification](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint/#error_notification_request) request signified by a `data.error` element
|
|
407
|
+
- A [health check](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint/#health_check_request) request signified by a `ping` action
|
|
408
|
+
|
|
409
|
+
#### Health check and Error handler
|
|
410
|
+
|
|
411
|
+
The function handles the health check and error notifications using if statements and responds accordingly, as shown in the snippet below:
|
|
412
|
+
|
|
413
|
+
```
|
|
414
|
+
// handle health check request
|
|
415
|
+
if (action === "ping") {
|
|
416
|
+
return {
|
|
417
|
+
version,
|
|
418
|
+
data: {
|
|
419
|
+
status: "active",
|
|
420
|
+
},
|
|
421
|
+
};
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
// handle error notification
|
|
425
|
+
if (data?.error) {
|
|
426
|
+
console.warn("Received client error:", data);
|
|
427
|
+
return {
|
|
428
|
+
version,
|
|
429
|
+
data: {
|
|
430
|
+
acknowledged: true,
|
|
431
|
+
},
|
|
432
|
+
};
|
|
433
|
+
}
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
#### INIT handler
|
|
437
|
+
|
|
438
|
+
When a user clicks the Flow’s call to action (CTA) button, a request with `INIT` action is sent to the endpoint. This action returns the initial data for the APPLICANTS screen.
|
|
439
|
+
|
|
440
|
+
```
|
|
441
|
+
// handle initial request when opening the flow and display APPLICANTS screen
|
|
442
|
+
if (action === "INIT") {
|
|
443
|
+
return {
|
|
444
|
+
...SCREEN_RESPONSES.APPLICANTS,
|
|
445
|
+
data: {
|
|
446
|
+
...SCREEN_RESPONSES.APPLICANTS.data,
|
|
447
|
+
additional_applicants_count: undefined,
|
|
448
|
+
},
|
|
449
|
+
};
|
|
450
|
+
}
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
#### data-exchange handlers
|
|
454
|
+
|
|
455
|
+
For `data_exchange` actions, a switch case structure is used to determine what data to send back based on the screen ID and other request data.
|
|
456
|
+
|
|
457
|
+
For the first screen with ID `APPLICANTS` we handle two requests. If the `cover_for_additional` field of the request is not null, it means that the user has selected to add additional applicant and therefore a new additional\_applicants\_count and add\_additional boolean are returned back to the client to keep track of additional applicants.
|
|
458
|
+
|
|
459
|
+
If the `cover_for_additional` field of request is null, it means that the user clicked on the Continue button on the Applicants screen. We return the next screen name in the response (`COVER_LEVEL`) and data received from the client.
|
|
460
|
+
|
|
461
|
+
For the next two screens, `COVER_LEVEL` and `EXCESS`, we set the initial data for next screen and attach data received from the Flow.
|
|
462
|
+
|
|
463
|
+
On the `DETAILS` screen, if user has selected they want to cover only their children we skip `YOUR_HEALTH` screen.
|
|
464
|
+
|
|
465
|
+
```
|
|
466
|
+
if (data.cover === "my_children") {
|
|
467
|
+
return {
|
|
468
|
+
...SCREEN_RESPONSES.ADDTIONAL_APPLICANT,
|
|
469
|
+
data: {
|
|
470
|
+
...data,
|
|
471
|
+
additional_applicants: [],
|
|
472
|
+
additional_applicant_title: "Additional Applicant 1",
|
|
473
|
+
additional_applicant_index: 0,
|
|
474
|
+
},
|
|
475
|
+
};
|
|
476
|
+
}
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Otherwise we navigate to next screen `YOUR_HEALTH` and we override specific fields in the initial screen data with data received from Flow.
|
|
480
|
+
|
|
481
|
+
For `YOUR_HEALTH` screen if `cover` is just just for `myself` we take user to `POLICY_SELECTION` screen next.
|
|
482
|
+
|
|
483
|
+
```
|
|
484
|
+
if (data.cover === "myself") {
|
|
485
|
+
return {
|
|
486
|
+
...SCREEN_RESPONSES.POLICY_SELECTION,
|
|
487
|
+
data: {
|
|
488
|
+
// copy initial screen data then override specific fields
|
|
489
|
+
...SCREEN_RESPONSES.POLICY_SELECTION.data,
|
|
490
|
+
...data,
|
|
491
|
+
},
|
|
492
|
+
};
|
|
493
|
+
}
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
Otherwise we navigate to `ADDTIONAL_APPLICANT` screen.
|
|
497
|
+
|
|
498
|
+
For the `ADDTIONAL_APPLICANT` screen while `applicant_index < data.additional_applicants_count` we keep sending user to `ADDTIONAL_APPLICANT` screen until we have collected information for all additional applicants.
|
|
499
|
+
|
|
500
|
+
```
|
|
501
|
+
if (applicant_index < data.additional_applicants_count) {
|
|
502
|
+
return {
|
|
503
|
+
...SCREEN_RESPONSES.ADDTIONAL_APPLICANT,
|
|
504
|
+
data: {
|
|
505
|
+
...rest,
|
|
506
|
+
additional_applicant_title: `Additional Applicant ${
|
|
507
|
+
applicant_index + 1
|
|
508
|
+
}`,
|
|
509
|
+
additional_applicant_index: applicant_index,
|
|
510
|
+
additional_applicants: updateApplicantsList,
|
|
511
|
+
},
|
|
512
|
+
};
|
|
513
|
+
}
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
After all the additional applicants information is collected we navigate to `POLICY_SELECTION` screen.
|
|
517
|
+
|
|
518
|
+
```
|
|
519
|
+
return {
|
|
520
|
+
...SCREEN_RESPONSES.POLICY_SELECTION,
|
|
521
|
+
data: {
|
|
522
|
+
// copy initial screen data then override specific fields
|
|
523
|
+
...SCREEN_RESPONSES.POLICY_SELECTION.data,
|
|
524
|
+
...rest,
|
|
525
|
+
additional_applicants: updateApplicantsList,
|
|
526
|
+
additional_applicants_count: undefined, // we do not need to send the count to the next screen
|
|
527
|
+
additional_applicant_index: undefined, // we do not need to send the index to the next screen },
|
|
528
|
+
};
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
For the `POLICY_SELECTION` screen we set policy details based on `selected_policy` and navigate to `SELECTED_POLICY` screen.
|
|
532
|
+
|
|
533
|
+
From `SELECTED_POLICY` we navigate to `YOUR_QUOTE` screen, where we set `payment_option` based on what user selected and then navigate to final `SUMMARY` screen.
|
|
534
|
+
|
|
535
|
+
After the `SUMMARY` screen is submitted from the client, a success response is sent to the client device to mark the Flow as complete.
|
|
536
|
+
|
|
537
|
+
[](#)
|