HSMs can be personalized by inserting content into a template, such as the recipient's name or specific order details. These placeholders are replaced with actual data when the message is sent.
Once you understand how the structure works and before creating a new template you have to be sure about which templates are already set in your bot. You can check it first by choosing Get Templates. Subsequently, you can create a new one by using the Create Template subsection.
Remember "Templates" are the skeleton of your message and they are approved or rejected by the WhatsApp crew, so it is essential to follow the guidelines to create a proper layout.
{"message": ["Los valores ingresados no son correctos." ],"statusMessage":"failed","status":0,"error": {"code":"E0422","key":"VALIDATOR_ERROR","description":"Error to be thrown when cannot process request because of incoming values","developerMessages": {"es":"Los valores del request no son correctos para ser procesados.","en":"The request values are not correct for processing." },"clientMessages": {"es":"Los valores ingresados no son correctos.","en":"The values entered are not correct." } },"validationError": {"status": [ {"en":"The status field must be one of the following values: PENDING,DELETED,REJECTED,APPROVED,DISABLED","es":"El campo status debe ser uno de los siguientes valores: PENDING,DELETED,REJECTED,APPROVED,DISABLED","pt":"O campo status deve ser um dos seguintes valores: PENDING,DELETED,REJECTED,APPROVED,DISABLED" } ] }}
Create Template
POSThttps://api.jelou.ai/v1/bots/:botId/templates
Create an HSM Template.
Path Parameters
Query Parameters
Request Body
{
"message": [
"Template has been created."
],
"status": "success",
"data": {
"template": "¡Hola! Somos *Jelou*. \nTe damos la bienvenida _{{1}}_. Pronto {{2}} del equipo de desarrollo se comunicará contigo.",
"displayName": "Bienvenida Desarrollo",
"elementName": "test_hsm_api",
"params": [
{
"label": "Nombre del cliente",
"param": "1"
},
{
"label": "Nombre del desarrollador",
"param": "2"
}
],
"paramsNumber": 2,
"isVisible": false,
"language": "ES",
"createdAt": "2021-01-28T15:08:38.492Z",
"updatedAt": "2021-01-28T15:08:38.492Z",
"botId": "<botId>",
"companyId": 5,
"status": "APPROVED"
}
}
{
"message": [
"The Bot could not be found at the moment."
],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E1019",
"key": "BOT_NOT_FOUND",
"description": "Error to be thrown when trying to get a Bot.",
"developerMessages": {
"es": "El botId no se encuentra en la base de datos o ha sido eliminado.",
"en": "The botId is not found in the database or has been deleted.",
"pt": "A botId não é encontrada no banco de dados ou foi apagada."
},
"clientMessages": {
"es": "El Bot no se pudo encontrar por el momento.",
"en": "The Bot could not be found at the moment.",
"pt": "A Bot não pôde ser encontrada no momento."
}
}
}
{
"message": [
"Los valores ingresados no son correctos."
],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E0422",
"key": "VALIDATOR_ERROR",
"description": "Error to be thrown when cannot process request because of incoming values",
"developerMessages": {
"es": "Los valores del request no son correctos para ser procesados.",
"en": "The request values are not correct for processing."
},
"clientMessages": {
"es": "Los valores ingresados no son correctos.",
"en": "The values entered are not correct."
}
},
"validationError": {
"parameters": [
{
"en": "The number of parameters is incorrect.",
"es": "El número de parámetros es incorrecto.",
"pt": "O número de parâmetros está incorreto."
}
]
}
}
{
"message": [
"We are having trouble processing your request. Please try again later."
],
"statusMessage": "failed",
"status": 0,
"error": {
"code": "E0000",
"key": "UNKNOWN_ERROR",
"description": "Error to be thrown when it couldn't be determined the reason of failure",
"developerMessages": {
"es": "Error inesperado occurido, revisar logs.",
"en": "Unexpected error occurred, check logs."
},
"clientMessages": {
"es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta mas tarde.",
"en": "We are having trouble processing your request. Please try again later."
}
}
}
The status field defines whether or not your template was approved by Whatsapp.
Language
The supported language by WhatsApp is detailed on the official page, please check it carefully on the following link.
Content Restrictions (Authentication category)
Meta has restricted the content for the authentication category, the content will be according to the language of the template. Meta is restricted to one parameter.
Params Structure
Use the following structure in the params field when creating a template:
[ {"label":"Nombre del cliente","param":"1" }, {"label":"Nombre del desarrollador","param":"2" }]
Button Structure
Use the following structure in the buttonsfield when the interactive actions are CALL_TO_ACTION ,QUICK_REPLY or OTP
1. QUICK_REPLY
It is used to get quick replies so a user can give a reply when a message shows up by pushing a button easily. It is an array of objects and it can have a maximum of 3 buttons. Each object has two fields.
[ {"text":"Más información","type":"QUICK_REPLY" }, {"text":"Hablar con operador","type":"QUICK_REPLY" }, {"text":"Ventas","type":"QUICK_REPLY" }]
2. CALL_TO_ACTION
It is used to offer a call-to-action so a user can take an action based on their shown options. It is an array of objects. It can have a maximum of 2 buttons and a maximum of 1 button of each type.
It is used to get a "One Time Password". It is an array of objects. It can have a maximum of 1 button.
[ {"text":"COPY CODE","type":"OTP" }]
extraSettings Structure
Sample API request
1. Text
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "template text utility", "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please contact support. Thank you for being a customer!",
"example": "Thank you for your order, Omar! Your confirmation number is 71936. If you have any questions, please contact support. Thank you for being a customer!",
"elementName": "template_text_utility", "params": [ { "param": "1", "label": "client", "example": "Omar" }, { "param": "2", "label": "order", "example": "71936" } ], "paramsNumber": "2", "type": "HSM", "language": "es", "category": "UTILITY", "interactiveAction": "NONE"}'
2. Text with quick reply buttons
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "template quick reply", "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
"example": "Thank you for your order, Omar! Your confirmation number is 57893. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
"elementName": "template_quick_reply", "params": [ { "param": "1", "label": "client", "example": "Omar" }, { "param": "2", "label": "order", "example": "57893" } ], "paramsNumber": "2", "type": "HSM", "language": "en", "category": "UTILITY", "interactiveAction": "QUICK_REPLY", "buttons": [ { "text": "Contact Support", "type": "QUICK_REPLY" }, { "text": "Contact Sales", "type": "QUICK_REPLY" } ]}'
3. Text with call-to-action buttons
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "template_call_action", "template": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
"example": "Thank you for your order, Omar! Your confirmation number is 67996. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
"elementName": "template_call_action", "params": [ { "param": "1", "label": "client", "example": "Omar" }, { "param": "2", "label": "order", "example": "67996" } ], "paramsNumber": "2", "type": "HSM", "language": "en", "category": "UTILITY", "interactiveAction": "CALL_TO_ACTION", "buttons": [ { "text": "Contact Support", "type": "URL", "url": "https://apps.jelou.ai", "example": "https://apps.jelou.ai" }, { "text": "Call", "type": "PHONE_NUMBER", "phone_number": "+15552051314" } ]}'
4. Image
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "template_sample_image", "template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "elementName": "template_sample_image", "params": [ { "param": "1", "label": "client", "example": "Omar" } ], "paramsNumber": "1", "type": "IMAGE", "language": "en", "category": "MARKETING", "mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2Fjeloupocket.jpeg", "interactiveAction": "NONE"}'
5. Document
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "test_document_", "template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "elementName": "test_document_", "params": [ { "param": "1", "label": "client", "example": "Omar" } ], "paramsNumber": "1", "type": "DOCUMENT", "language": "en", "category": "MARKETING", "mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2FdocuementTest.pdf", "interactiveAction": "NONE"}'
6. Video
curl--requestPOST \--url'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \--header'Authorization: Basic dXNlcjpwYXNzd29yZA==' \--header'content-type: application/json' \--data'{ "displayName": "test_video_1", "template": "Hi {{1}}. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "example": "Hi Omar. We invite you to be part of Jelou Pocket. Visit us https://apps.jelou.ai", "elementName": "test_video_1", "params": [ { "param": "1", "label": "client", "example": "Omar" } ], "paramsNumber": "1", "type": "VIDEO", "language": "en", "category": "MARKETING", "mediaUrl": "https://s3.us-west-2.amazonaws.com/cdn.devlabs.tech/images%2FvideoTest.mp4", "interactiveAction": "NONE"}'
Name
Type
Description
Name
Type
Description
Name
Type
Description
Language
Language code
Content
Field
Description
Field
Description
Field
Description
Field
Type
Description
botId
string
Describe your bot id required for search your templates
query
String
Search template by elementName
status
String
Search templates by status. Possible values: PENDING, REJECTED, APPROVED
category
String
Search templates by category. Possible values: UTILITY, MARKETING, AUTHENTICATION
botId*
string
Bot id
sendToAprove
boolean
Defines if a template should be sent to WhatsApp for approval
category*
string
The category of HSM template
Values: UTILITY, MARKETING, AUTHENTICATION
language*
string
Template language.
isVisible
boolean
Defines if the templare should be shown to operators
params*
object
Parameter structure. For the Authentication category, Meta has restricted to one parameter.
paramsNumber*
number
Number of parameters. For the Authentication category, Meta has restricted to one parameter.
elementName*
string
Unique template identifier. It can only contain uppercase letters, underscore (_), and numbers.
displayName*
string
Template display name
template*
string
Template body. For the Authentication category, Meta has restricted the content. Review the restrictions for this category.
type*
string
HSM type. Values:HSM, IMAGE, VIDEO, DOCUMENT
mediaUrl
string
String of the URL media. Required when the HSM type is IMAGE, VIDEO, DOCUMENT.Not applicable for Authentication category
interactiveAction*
string
Interactive action of the HSM. Values:NONE, CALL_TO_ACTION, QUICK_REPLY, OTP
buttons
array
Button structure. Required when the interactive action of the HSM is CALL_TO_ACTION ,QUICK_REPLY or OTP
header
string
Template header. Applicable only for Text type templates. Not applicable for Authentication category and has a limit of 60 characters.
exampleHeader
string
Example of the header. Mandatory only if the template will have a header.
headerParams
String
Parameter structure. The header supports a maximum of one parameter.
example*
string
Example of the template. If the template has a parameter, the parameter should be replaced with an example.
extraSettings
Object
Optional settings for the template. Read the structure section for more information
English
en
{{1}} is your verification code.
Portuguese (BR)
pt_BR
Seu código de verificação é {{1}}.
Spanish
es
Tu código de verificación es {{1}}.
text
Button text, this value cannot be updated.
type
Button type. Value QUICK_REPLY
text
Button text, this value cannot be updated.
type
Button type. Value PHONE_NUMBER, URL
phone_number
Phone number of the button.
url
URL of the button.
example
Example of the URL. Required when the button type is URL.
text
Button text, this value cannot be updated.
type
Button type. Value OTP
addSecurityRecommendation
Boolean
Adds an additional security message in Authentication templates.
codeExpirationMinutes
Number
Adds a footer message with the code expiration time. Values between 1-90 minutes.
allowChangeCategory
Boolean
Let Meta to update the template category if it is required.