Trigger Message (WhatsApp API's Implementation)

Low-level-design: High Level Diagram Whatsapp Integration (Meta)

Requirements: As soon as the failed_delivery_events are received need to trigger WhatsApp notification to the customer using WhatsApp Meta cloud APIs

Implementation:

At GCP Project:

• Create a subscriber for nf_shipments events

• The event subtype is failed_delivery

• The listener is a WhatsApp notifications service

At DB Level:

• New tables are to be added for DLR, outgoing messages, incoming

• Details mentioned in “Low-level-design”

At Code Level:

• Post API: whatsappEventListener receives the fdr event with resource “shipment” & eventSubType “failed_delivery”.

• Event received in decoded and stored in Map<String, Object>

  { "resource": "shipment", "eventType": "PUT", "eventSubType": "failed_delivery", "accountSlug": "vitaminplanet", "accountId": null, "actor": "SYSTEM", "version": "v1", "request_data": [], "response_data": { "customerOrderNumber": "4980116095129", "orderSiteID": "", "vendorOrderNumber": "#98079", "externalShipmentID": "4980116095129-90758", "externalWarehouseID": "Gurgaon_FC", "externalChannelID": "CH1299", "externalWmsChannelName": "SCITRON_SHOPIFY_VITAMINPLANET_AGGN_2295", "external_wms_channel_id": 2295, "channelLabel": "Scitron Shopify", "integrationType": "7", "vendorPartyID": null, "partner_as2_id": null, "defaultWarehouseCode": "Gurgaon_FC", "facilityLabel": "Gurgaon (AGGN)", "facilityType": "auperator", "orderDate": "2023-06-05 16:58:58", "portal_id": 27, "paymentType": "Cash on Delivery (COD)", "expectedShipDate": "2023-06-06 12:00:00", "dispatchAfterDate": null, "externalManifestNumber": null, "channelManifestNumber": null, "order_id": 48884718, "channel_id": 1299, "warehouse_id": 650, "channel_account_id": 0, "account_id": 379, "connectionId": 482, "locationId": "67070591129", "region": "Zonal", "isMetro": "0", "isSpecialplace": "0", "shippingConnectionId": 0, "picklistCode": null, "invoiceNumber": "INVVITHZ42616", "boxType": "UNKNOWN", "isPriorityShipment": "0", "isGift": "0", "invoice_url": "https:\/\/storage.googleapis.com\/invoicefiles-prod\/invoice\/4980116095129-90758-1685964612847.pdf", "invoiceDate": "2023-06-05 17:00:09", "label_url": "https:\/\/storage.googleapis.com\/eshopbox_wms_uploads\/myntraLabel\/20230605210903274917906.pdf", "labels": "", "shippingInfo": [], "boxAdditionalRecommendation": [], "dimension_length": "26", "dimension_width": "16", "dimension_height": "20", "weight": "1550", "trackingID": "1704612602165", "trackingDomain": "track.scitron.com", "packageID": "", "barcode": "", "taxAmount": 0, "shipChargeAmount": 0, "courierName": "Delhivery", "cp_id": 4, "created_at": "2023-06-05 16:59:09", "updated_at": "2023-06-06 19:49:23", "status": "failed_delivery", "remarks": "code verified cancellation", "warehousePincode": "122503", "thirdPartyShipping": false, "customerName": "Aman Verma", "customerContactNumber": "7891971009", "email": "Amitv12330@gmail.com", "channelSlug": "vitaminplanet90", "status_updated_at": "2023-06-08 16:06:16", "status_log": { "created": "2023-06-05 16:59:09", "accepted": "2023-06-05 17:00:08", "picked": "2023-06-05 17:30:14", "packed": "2023-06-05 21:09:05", "out_for_pickup": "2023-06-06 16:46:12", "dispatched": "2023-06-06 19:49:23", "intransit": "2023-06-08 10:13:42", "out_for_delivery": "2023-06-08 12:09:06", "failed_delivery": "2023-06-08 16:06:16" }, "status_log_first_occurrence": { "failed_delivery": "2023-06-08 16:06:16", "out_for_delivery": "2023-06-08 12:09:06", "intransit": "2023-06-07 00:16:22", "dispatched": "2023-06-06 19:49:23", "out_for_pickup": "2023-06-06 16:46:12", "packed": "2023-06-05 21:09:05", "picked": "2023-06-05 17:30:14", "accepted": "2023-06-05 17:00:08", "created": "2023-06-05 16:59:09" }, "status_log_count": { "created": 1, "accepted": 1, "picked": 1, "packed": 1, "out_for_pickup": 1, "dispatched": 1, "intransit": 7, "out_for_delivery": 1, "failed_delivery": 1 }, "status_log_id": "124953537", "orderExternalCreatedAt": "2023-06-05 16:59:05", "shippingAddress": { "customerName": "Aman Verma", "addressLine1": "Sadafal kunj", "addressLine2": "Arjun club road ward num 26", "city": "churu", "state": "RAJASTHAN", "postalCode": "331403", "countryCode": "IN", "countryName": "INDIA", "contactPhone": "7891971009", "email": "Amitv12330@gmail.com" }, "warehouseAddress": { "addressLine1": "MJ Logistics Private Limited, Seabird Marine Services Pvt Ltd", "addressLine2": "Village Babra Bakirpur, Pataudi Road Near Adani Logistic Park, ICD Patli, Gurgaon, Haryana(122503)", "city": "Gurgaon", "state": "Haryana", "postalCode": "122503", "gstin": "06AAFCB0498R2Z2" }, "id": 17148471, "isCOD": "1", "track_payload": { "clickPostTrackData": { "location": "Sardarshahr_IndustrialArea_D (Rajasthan)", "additional": { "courier_partner_edd": "2023-06-09", "destination_hub_inscan_ts": null, "order_id": "4980116095129-90758", "latest_status": { "status": "RT In Transit", "clickpost_status_description": "FailedDelivery", "clickpost_status_bucket": 5, "reference_number": "4980116095129-90758", "clickpost_status_bucket_description": "Failed delivery", "remark": "Code verified cancellation", "timestamp": "2023-06-08T14:58:41Z", "location": "Sardarshahr_IndustrialArea_D (Rajasthan)", "clickpost_city": null, "clickpost_status_code": 9 }, "is_rvp": false, "ndr_status_code": 14, "ndr_status_description": "OTP-based cancellation", "account_code": "ESB_Delhivery_Forward_500g_Express", "npr_status_code": null, "npr_status_description": null }, "status": "RT In Transit", "clickpost_city": null, "clickpost_status_code": 9, "clickpost_status_description": "FailedDelivery", "cp_id": 4, "remark": "Code verified cancellation", "account_code": "ESB_Delhivery_Forward_500g_Express", "waybill": "1704612602165", "timestamp": "2023-06-08T14:58:41Z" } }, "account_slug": "vitaminplanet", "packed_date": "2023-06-05 21:09:05", "items": [ { "order_item_id": 31200595, "lineItemSequenceNumber": 12566731260057, "orderItemID": "4980116095129-31200595", "itemID": "45162317217945", "sku": "06REP3HBCN3", "asin": "", "productName": "Advance Whey Protein with 20 Vitamins & Minerals", "quantity": 1, "orderItemCreatedAt": "2023-06-05 16:59:05", "customerPrice": 2099, "lineItemTotal": 1889.0999999999999, "invoiceTotal": 1889.0999999999999, "cashOnDeliveryCharges": 0, "discount": 209.90000000000001, "taxRate": 0, "taxAmount": 0, "inventoryItemCode": "G-IB1735411", "giftMessage": "", "isGift": "0", "giftLabelContent": "", "lineItemOrderStatus": "", "ordendr_status_descriptionrItemIDs": [ "4980116095129-31200595" ], "productImageUrl": null, "productAdditionalInfo": { "size": "Kulfi \/ 1KG \/ Gloves" }, "expectedDeliveryDate": "2023-06-09", "shippingCharges": 0, "productUrl": null, "originalOrderItemId": null, "isVirtualKit": "1", "component": [ { "inventoryItemCode": "G-IB1665164", "productAdditionalInfo": "", "whOrderItemID": "4980116095129-31200595\/1", "esin": "63MYP3HA5I0" }, { "inventoryItemCode": "G-IB1735411", "productAdditionalInfo": "", "whOrderItemID": "4980116095129-31200595\/2", "esin": "75V0P3HA6O1" } ], "onhold": "0", "cancellationAdditionalReason": "", "cancellationReason": "", "customerOrderItemID": "", "recallBlockedInventoryUsed": "" } ] }, "previous_data": [], "resource_type": "shipment.update", "account_slug": "vitaminplanet", "custom": [] }

• A POST API message queue listener is created where we process the queue

• There are various fdr reasons we need to create methods for all the cases and with details received in the event above we call particular related method

• Next, we fetch the connectionId and set it in the cache if the cache is empty else we fetch the details from the cache and proceed. (key:whatsapp_{account_slug} → map(conenction_id, templateId, etc) - entire map + connection details(whatsapp phone number, access token))

• We will have a method generateTemplateRequest that will be used to create the templateRequest which is to be sent to the customer on the basis of the FDR.

• This method will take input variables like Name, Phone number, accountSlug, orderId, Order Items, FDR, etc. which will be used in the template to generate the msg that is to be sent to the customer.

• Data to be pushed in taskqueue "account_slug": "vitaminplanet" "eventSubType": "failed_delivery" "customerOrderNumber": "4980116095129" "account_id : "379" "contactPhone": "7891971009" "expectedDeliveryDate": "2023-06-09" "orderItemIDs": "4980116095129-31200595" "quantity": 1 status": "RT In Transit" "failed_delivery": "2023-06-08 16:06:16" "externalShipmentID": "4980116095129-90758" "ndr_status_description": "OTP-based cancellation" "vendorOrderNumber": "#98079", "order_id": 48884718, "trackingID": "1704612602165", "remarks": "code verified cancellation", "thirdPartyShipping": false, "customerName": "Aman Verma", "customerContactNumber":"7891971009", "status_log": { "created": "2023-06-05 16:59:09", "accepted": "2023-06-05 17:00:08", "picked": "2023-06-05 17:30:14", "packed": "2023-06-05 21:09:05", "out_for_pickup": "2023-06-06 16:46:12", "dispatched": "2023-06-06 19:49:23", "intransit": "2023-06-08 10:13:42", "out_for_delivery": "2023-06-08 12:09:06", "failed_delivery": "2023-06-08 16:06:16" }, "shippingAddress": { "customerName": "Aman Verma", "addressLine1": "Sadafal kunj", "addressLine2": "Arjun club road ward num 26", "city": "churu", "state": "RAJASTHAN", "postalCode": "331403", "countryCode": "IN", "countryName": "INDIA", "contactPhone": "7891971009", "email": "Amitv12330@gmail.com" }

• As soon as the template is fetched we prepare our body for triggering graph API which has the body mentioned below (https://graph.facebook.com/105339412622627/messages)

• Response

  { "messaging_product": "whatsapp", "contacts": [ { "input": "919650186697", "wa_id": "919650186697" } ], "messages": [ { "id": "wamid.HBgMOTE5NjUwMTg2Njk3FQIAERgSQUM1RDgwMzMyRTNFRjdCNzQzAA==" } ] }

• The template sent out will also be stored in database in outgoingMessagesTable with the time details when the message was sent and other details.

• All the DB fields will be populated shipment_status_logs_id, customer_phone, business_phone, wa_template_id, root_message_id, message_id, payload, external_updatedAt, created_at from the payload after a successful response is received from meta in wa_outgoing_messages table after fetching messages.id from the API response.

  INSERT INTO wa_outgoing_messages (shipment_status_logs_id, customer_phone, business_phone, wa_template_id, root_message_id, message_id, payload, external_updatedAt, created_at) VALUE ('12345', '7042226080', '15550512539', '1493673698103012', '', 'wamid.HBgMOTE5NjUwMTg2Njk3FQIAERgSQUM1RDgwMzMyRTNFRjdCNzQzAA==', '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "918383000700", "type": "template", "template": { "name": "customer_unreachable", "language": { "code": "en_US" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Pablo" }, { "type": "text", "text": "566701" }, { "type": "text", "text": "Pablo" }, { "type": "text", "text": "566701" }, { "type": "text", "text": "Pablo" }, { "type": "text", "text": "566701" } ] } ] } }', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

• A webhook is also registered on whatsapp which will receive all the delivery reports regarding when the message was sent, delivered, etc. which be saved in wa_dlr_messages table.

  INSERT INTO wa_dlr_messages (wa_outgoing_message_id, message_id, STATUS, payload, external_timestamp, created_at, updated_at) VALUES ('1234565432', 'wamid.HBgMOTE5NjUwMTg2Njk3FQIAERgSQUM1RDgwMzMyRTNFRjdCNzQzAA==', 'sent', ' { "object": "whatsapp_business_account", "entry": [ { "id": "105945132543354", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15551009938", "phone_number_id": "108687922264083" }, "statuses": [ { "id": "wamid.HBgMOTE5NjUwMTg2Njk3FQIAERgSQUM1RDgwMzMyRTNFRjdCNzQzAA==", "status": "read", "timestamp": "1687433938", "recipient_id": "919650186697" } ] }, "field": "messages" } ] } ] }','2023-08-24 18:28:44', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

   

  • Next step will handle different cases on the basis of FDR and customer response :
    
    

Reference : https://app.diagrams.net/#G1CBXPAjiYlbevSpXWCLcm3_yXANLssVR3#{"pageId"%3A"WxXofK7jHqP6YTWFo0m3"}

• On the basis of the above table, we will be creating different scenarios and take action accordingly.

• In case of a button reply containing a date, the customer reply would be saved else it will be used to take a corresponding action.

  INSERT INTO wa_customer_reply_messages (wa_context_outgoing_message_id, reply_message_id, customer_reply_type,button_reply_id, payload, external_timestamp, created_at, updated_at) VALUES (wa_context_outgoing_message_id, reply_message_id, customer_reply_type, button_reply_id, payload, external_timestamp, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);

• Firstly the customer response will be saved in DB in table wa_customer_reply_messages.

• Next, we will proceed with taking action.

• We will take action as per the above table on the basis of which, either a static message(using triggerStaticMessage method) will be prepared or an interactive button message(using triggerButtonMessage method).

• For some cases like add alternate number or update address a link to the customer portal is generated and sent to the customer to take action as a static message.

• For both cases the outgoing message is saved in DB.

  INSERT INTO wa_outgoing_messages (wa_context_outgoing_message_id, shipment_status_logs_id, root_message_id, customer_phone, business_phone, message_id, payload, external_updatedAt, created_at, updated_at) VALUES (wa_context_outgoing_message_id, shipment_status_logs_id, root_message_id, customer_phone, business_phone, message_id, payload, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)

• For cases like new delivery date and cancel order NDR resolution API will be called internally after fetching customer and order details from DB. It will also require to generate a full token(another API is used for this) in order to make the API call.

• All the customer and order details are saved in the PoeSettingsAndNotificationsDto and then used to trigger the whatsapp API where dto has all the required fields for the same.

• All the whatsapp connection details are saved in the CustomerDetailsDto and then used to trigger the NDR Resolution API where dto has all the required fields for the same.

• After successful action is completed a static message will be sent to the user.

• As a default case if a random text is received we send a response similar to Need support including support details if any.

  Thank you for your response. If you have any queries related to your order, please contact our customer support team. Our team would be happy to assist you.

   

•