Templates

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.

Get Templates

GET https://api.jelou.ai/v1/bots/:botId/templates

Returns all templates for your bot.

Path Parameters

Name	Type	Description
botId	string	Describe your bot id required for search your templates

Query Parameters

Name	Type	Description
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

200 Contains the result array of templates and other useful information for pagination

{
  "pagination": {
    "limit": 50,
    "total": 1,
    "offset": 0,
    "totalPages": 1
  },
  "results": [
    {
      "id": 39,
      "template": "¡Hola! Somos *Jelou*. Te damos la bienvenida.",
      "displayName": "Bienvenida Jelou",
      "elementName": "bienvenida_jelou",
      "companyId": 5,
      "botId": "<botId>",
      "paramsNumber": 0,
      "params": [],
      "createdAt": "2020-03-12T22:35:05.000Z",
      "updatedAt": "2020-03-12T22:35:05.000Z",
      "isVisible": true,
      "type": "HSM",
      "language": "ES",
      "shouldAssign": true,
      "teamId": null
    }
  ],
  "links": [
    {
      "number": 1,
      "url": "/v1/bots/[phone]/templates?page=1&limit=50"
    }
  ]
}

422: Unprocessable Entity Validation error, occurs when the sent payload does not follow the format validations for each field of the payload.

{
	"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

POST https://api.jelou.ai/v1/bots/:botId/templates

Create an HSM Template.

Path Parameters

Name	Type	Description
botId*	string	Bot id

Query Parameters

Name	Type	Description
sendToAprove	boolean	Defines if a template should be sent to WhatsApp for approval

Request Body

Name	Type	Description
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

200

{
  "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"
  }
}

404: Not Found

{
  "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."
    }
  }
}

422: Unprocessable Entity

{
  "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."
      }
    ]
  }
}

500: Internal Server Error

{
  "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.

Message Templates - WhatsApp Business Platform On-Premises API - Documentation - Meta for DevelopersMeta for Developers

Languages supported by WhatsApp

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.

Language	Language code	Content
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}}.

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.

Field	Description
text	Button text, this value cannot be updated.
type	Button type. Value QUICK_REPLY

[
  {
    "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.

Field	Description
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": "Ventas",
    "phone_number": "[phone]",
    "type": "PHONE_NUMBER"
  },
  {
    "type": "URL",
    "text": "Jelou Apps",
    "url": "https://apps.jelou.ai/{{1}}",
    "example": "https://apps.jelou.ai/bots"
  }
]

3. OTP

It is used to get a "One Time Password". It is an array of objects. It can have a maximum of 1 button.

Field	Description
text	Button text, this value cannot be updated.
type	Button type. Value OTP

[
  {
    "text": "COPY CODE",
    "type": "OTP"
  }
]

extraSettings Structure

Field	Type	Description
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.

Sample API request

1. Text

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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 --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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 --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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": "[phone]"
		}
	]
}'

4. Image

curl --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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 --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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 --request POST \
  --url 'https://api.jelou.ai/v1/bots/BOT_ID/templates?sendToAprove=true' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --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"
}'