Working with Secure Forms
Send a secure form as a bot response to a user. After a submission of secure form, the bot receives the secure form information.
Secure forms can be used to collect non-PCI information such as the name, age, and date of birth.
With secure forms sending as a bot response, we do not collect payment information such as the card details or authentication methods.
To send a secure form to a user as bot response:
- Retrieve the secure forms
- Send a secure form as a bot response to the user
- Successful submission of the secure form by the user
- Bot receives the submitted information.
Note
- Khoros Care does not allow a bot to send any PCI form.
- You can send a secure form only with non-expired fields as a bot response.
Retrieving the Secure Forms
To generate the access token, use the access token API. With the access token, use the secureForm/getForms API to retrieve the list of the secure forms.
Example
Request
https://api.app.lithium.com/api/v2/secureForm/getForms
Response
The id field represents the secure form ID. The nested IDs in the “fields” are the different fields in a secure form.
In the below response, the id - AABBCCDD-1122-4A5B-A12R-123456DDD789 is the secure form ID and the nested IDs - CCCDDD-4ABC-1BC2-7777-STUVWXYZ123, EEEFFFG1-3567-88HH-67U8-ZYXWTER2, HHHHJKL-1234-5678-9012-234TYUIOP are the IDs of the fields such as form header, student name, and subject in a secure form.
{
"status": "success",
"data": [
{
"id": "AABBCCDD-1122-4A5B-A12R-123456DDD789",
"name": "Personal Details Form",
"description": null,
"enabled": true,
"deleted": false,
"applyTagIdsToRequest": null,
"applyTagIdsToResponse": null,
"fields": [
{
"id": "CCCDDD-4ABC-1BC2-7777-STUVWXYZ123",
"settings": {
"type": "HEADER",
"required": true,
"label": null,
"subtext": "",
"headerText": "Class",
"icon": null
},
"authorProfileMapping": null,
"authorMetadataMapping": false,
"orderIndex": 0
},
{
"id": "EEEFFFG1-3567-88HH-67U8-ZYXWTER2",
"settings": {
"type": "SHORT_TEXT",
"required": false,
"label": "Students",
"subtext": "",
"value": "",
"canExpire": false,
"expirationType": "NONE",
"maxLength": null,
"hintText": "Enter a student name",
"customValidationEnabled": false,
"customValidation": null,
"customValidationMessage": null
},
"authorProfileMapping": null,
"authorMetadataMapping": false,
"orderIndex": 0
},
{
"id": "HHHHJKL-1234-5678-9012-234TYUIOP",
"settings": {
"type": "SHORT_TEXT",
"required": false,
"label": "Subject",
"subtext": "",
"value": "",
"canExpire": false,
"expirationType": "NONE",
"maxLength": null,
"hintText": "Enter the subject",
"customValidationEnabled": false,
"customValidation": null,
"customValidationMessage": null
},
"authorProfileMapping": null,
"authorMetadataMapping": false,
"orderIndex": 0
},
{
"id": "MMMNNNOOOP-QRS1-1234-5678-789OIPLKJ",
"settings": {
"type": "NUMBER",
"required": false,
"label": "Marks",
"subtext": "",
"value": "",
"canExpire": false,
"expirationType": "NONE",
"maxValue": 100,
"minValue": 0,
"hintText": "Enter marks of that subject",
"customValidationEnabled": false,
"customValidation": null,
"customValidationMessage": null
},
"authorProfileMapping": null,
"authorMetadataMapping": false,
"orderIndex": 0
}
],
"expirationInMilli": 600000,
"expirationTimeUnit": "MINUTES",
"linkExpirationInMilli": 86400000,
"linkExpirationTimeUnit": "HOURS",
"languageCode": null,
"confirmationMessage": null,
"privacyPolicyUrl": null,
"termsConditionsUrl": null,
"teamIds": null,
"version": null,
"channels": [
{
"network": "facebook",
"networkInstance": "facebook",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "twitter",
"networkInstance": "twitter",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "apple",
"networkInstance": "apple",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "email",
"networkInstance": "email",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "instagram",
"networkInstance": "instagram",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "googlemessages",
"networkInstance": "googlemessages",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "whatsapp",
"networkInstance": "whatsapp",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "sms",
"networkInstance": "sms",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
},
{
"network": "brandmessenger",
"networkInstance": "brandmessenger",
"externalId": null,
"filters": [
{
"type": "ANY_ID"
}
]
}
],
"cnameDefinition": null,
"headerHtml": {
"enabled": true,
"injectableStyle": null
},
"footerHtml": {
"enabled": true,
"injectableStyle": null
},
"customCss": {
"enabled": true,
"injectableStyle": null
},
"alwaysShowInWebview": false,
"blockChatInput": false,
"authorProfileMapping": null,
"authorMetadataMapping": false,
"addResponsesToMetadata": false
},
....
"alwaysShowInWebview": false,
"blockChatInput": false,
"authorProfileMapping": null,
"authorMetadataMapping": false,
"addResponsesToMetadata": false
}
]
}
Sending a Secure Form as Bot Response
From the secure forms list, let’s send a non-PCI secure form “Personal Details form” as a bot response to the user. Use the /bots/v3/form API to send a secure form.
While sending a secure form, we include the coordinate field, author field, comment, and a secure form ID.
Note
You can send a non-PCI form only if it has no expiring fields.
Example
Request
curl -L 'https://api.app.lithium.com/bots/v3/form' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <bearer-token>' \
-d '{
"type": "secure_form",
"coordinate": {
"companyKey": "DOCSSANDBOX",
"networkKey": "brandmessenger",
"externalId": "<external-id>",
"botId": "testauto-bmv2-live-bot",
"scope": "PRIVATE",
"normalizedAuthorId": "docssandbox-111222-33334444-5556666",
"messageId": "docsAAABBBCCCC567890-"
},
"author": {
"id": "docssandbox-111222-33334444-5556666",
"fullName": "Mr. John Brown"
},
"comment": "let's send a non-pci form",
"secureFormId": "AABBCCDD-1122-4A5B-A12R-123456DDD789"
}'
Response
A 202 response is returned indicating the request is successful.
Submitting and Receiving the Form Details
Once you’ve sent the secure form as a bot response, ensure that the secure form is received in the Brand Messenger Chat Widget.
Complete the secure form with the necessary information and submit it in the chat widget.
In your Khoros Care Agent View console, verify that the submitted form details are shown. This information is also sent to the bot.
Updated 4 months ago